io.github.theYahia/retailcrm-mcp

MCP-сервер для RetailCRM — заказы, клиенты и товары интернет-магазина через ИИ

Если вы искали, как подключить RetailCRM к нейросети, поднять заказ или карточку клиента и не собирать отчёты руками — это оно. 39 инструментов и 2 навыка поверх API v5: заказы, клиенты, товары, складские остатки, оплаты, задачи, справочники и аналитика. Спрашиваете «что с заказом 12345» — получаете статус, состав и оплату одним ответом.

Промышленный MCP-сервер для e-commerce CRM RetailCRM. 39 инструментов + 2 навыка-промпта для работы с заказами, клиентами, товарами, остатками, оплатами, задачами, справочниками и аналитикой через API v5.

Ответы экономят токены по умолчанию

Читающие инструменты возвращают компактную структурированную сводку только из тех полей, которые нужны агенту, а не весь ответ RetailCRM. Подробность настраивается на каждый вызов:

⚠️ v3 ломает совместимость с v2: по умолчанию отдаётся структурированная сводка, а не сырой JSON. Передайте raw:true, чтобы вернуть прежний формат.

Инструменты (39)

Заказы

Клиенты

Товары и остатки

Оплаты

Заметки и задачи

Маркетинг и финансы

Файлы

Справочники

Аналитика

Навыки-промпты (2)

Настройка

1. В RetailCRM откройте Настройки → Интеграция → Ключи API.
2. Создайте ключ API с нужными правами (заказы, клиенты, склад, справочники). Для мультисайтового ключа передавайте код site в инструментах создания и изменения (см. list_sites).
3. Запомните свой домен (часть yourstore из yourstore.retailcrm.ru).

Переменные окружения

RETAILCRM_URL по-прежнему принимается как запасной вариант для RETAILCRM_DOMAIN.

Подключение к Claude Desktop

{
  "mcpServers": {
    "retailcrm": {
      "command": "npx",
      "args": ["-y", "@theyahia/retailcrm-mcp"],
      "env": {
        "RETAILCRM_DOMAIN": "yourstore.retailcrm.ru",
        "RETAILCRM_API_KEY": "your-api-key"
      }
    }
  }
}

Режим Streamable HTTP

Запуск в виде HTTP-сервера вместо stdio:

RETAILCRM_DOMAIN=yourstore.retailcrm.ru \
RETAILCRM_API_KEY=your-key \
npx @theyahia/retailcrm-mcp --http

• POST /mcp — эндпоинт MCP Streamable HTTP (stateless: на каждый запрос создаётся новый сервер)
• GET /health — проверка состояния (JSON с версией и числом инструментов)
• GET/DELETE /mcp — 405 (в stateless-режиме не используются)
• Привязка по умолчанию: 127.0.0.1:3000. Защита от DNS-rebinding для локальных привязок включена по умолчанию.

Smithery

npx @smithery/cli install @theyahia/retailcrm-mcp

Демо-промпты

1. Обзор заказов за день: «Покажи все заказы, созданные сегодня, в статусе „новый“. Дай итоговое количество и выручку.»

2. Клиент и его история заказов: «Найди клиента с почтой anna@example.com. Покажи полный профиль и последние заказы.»

3. Проверка остатков: «Есть ли товар с externalId SKU-42 в наличии и на каком складе?»

Вебхуки и триггеры

RetailCRM не умеет создавать вебхуки через API. Используйте Триггеры в админке (Настройки → Триггеры), чтобы отправлять HTTP-запросы на внешние эндпоинты по событиям заказов и клиентов.

Обработка ошибок

• Лимиты запросов и 5xx: автоматический повтор с экспоненциальной задержкой и джиттером (до 3 попыток).
• Ошибки API: детали ошибки RetailCRM разбираются и возвращаются модели как результат инструмента с isError: true, чтобы агент мог исправиться сам (например, повторить с by:"externalId").
• Таймауты: 15 секунд на запрос с повтором.

Разработка

npm install
npm test          # vitest (на моках; живой ключ API не нужен)
npm run lint      # eslint
npm run typecheck # tsc --noEmit
npm run dev       # dev-режим stdio (tsx)
npm run build     # очистка + сборка в dist/

Лицензия

MIT

Часть WWmcp · Telegram: @vhodvai