Retailcrm MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Retailcrm MCP listing page.
MCP-сервер для RetailCRM — заказы, клиенты и товары интернет-магазина через ИИ
Если вы искали, как подключить RetailCRM к нейросети, поднять заказ или карточку клиента и не собирать отчёты руками — это оно. 39 инструментов и 2 навыка поверх API v5: заказы, клиенты, товары, складские остатки, оплаты, задачи, справочники и аналитика. Спрашиваете «что с заказом 12345» — получаете статус, состав и оплату одним ответом.
Промышленный MCP-сервер для e-commerce CRM RetailCRM. 39 инструментов + 2 навыка-промпта для работы с заказами, клиентами, товарами, остатками, оплатами, задачами, справочниками и аналитикой через API v5.
Ответы экономят токены по умолчанию
Читающие инструменты возвращают компактную структурированную сводку только из тех полей, которые нужны агенту, а не весь ответ RetailCRM. Подробность настраивается на каждый вызов:
| Параметр | Что делает |
|---|---|
| (по умолчанию) | detail:"summary" — ключевые поля + блок pagination |
detail:"full" | Все структурированные поля (позиции, доставка, оплаты, адрес…) |
raw:true | Нетронутый ответ RetailCRM (для отладки) |
⚠️ v3 ломает совместимость с v2: по умолчанию отдаётся структурированная сводка, а не сырой JSON. Передайте
raw:true, чтобы вернуть прежний формат.
Инструменты (39)
Заказы
| Инструмент | Описание |
|---|---|
list_orders | Список заказов по статусу, клиенту, номеру, периоду |
get_order | Один заказ по ID или externalId |
create_order | Создать заказ; привязать существующего клиента (customer_id/customer_external_id) или завести нового прямо в вызове |
update_order | Изменить статус, клиента, доставку, комментарии |
orders_history | История изменений заказов, включая смены статусов (инкрементальная синхронизация) |
Клиенты
| Инструмент | Описание |
|---|---|
list_customers | Поиск клиентов по имени, e-mail, телефону, дате |
get_customer | Один клиент по ID или externalId |
create_customer | Создать клиента |
update_customer | Изменить существующего клиента |
merge_customers | Объединить дубли (разрушающая операция) |
customers_history | Лог изменений клиентов (прирост/отток, инкрементальная синхронизация) |
Товары и остатки
| Инструмент | Описание |
|---|---|
list_products | Товары каталога по названию, группе, активности, цене |
list_product_groups | Дерево товарных категорий |
store_inventories | Остатки и себестоимость по торговым предложениям и складам |
Оплаты
| Инструмент | Описание |
|---|---|
order_payment_create | Зафиксировать оплату по заказу |
order_payment_edit | Изменить оплату |
order_payment_delete | Удалить оплату (разрушающая операция) |
Заметки и задачи
| Инструмент | Описание |
|---|---|
customer_notes_list / customer_notes_create / customer_notes_delete | Произвольные заметки по клиенту |
tasks_list / tasks_create / tasks_edit | Задачи и напоминания |
Маркетинг и финансы
| Инструмент | Описание |
|---|---|
list_segments | Сегменты клиентов (RFM и маркетинговые когорты) |
list_costs / create_cost | Записи расходов для аналитики маржи |
Файлы
| Инструмент | Описание |
|---|---|
files_list / files_get / files_upload | Прикрепление и получение файлов (загрузка сырым octet-stream) |
Справочники
| Инструмент | Описание |
|---|---|
list_statuses / list_delivery_types / list_payment_types / list_stores | Справочники статусов, доставок, оплат и магазинов |
list_sites | Сайты, доступные ключу API (для заполнения параметра site) |
list_countries / list_order_types / list_order_methods | Справочники адресов и заказов |
Аналитика
| Инструмент | Описание |
|---|---|
get_orders_summary | Статистика заказов за период: точное количество и выручка, средний чек, распределение по статусам |
get_customers_summary | Количество новых клиентов за период |
Навыки-промпты (2)
| Навык | Описание |
|---|---|
new-orders | Быстрый ежедневный обзор сегодняшних заказов |
customer-search | Найти клиента по имени, e-mail или телефону |
Настройка
- В RetailCRM откройте Настройки → Интеграция → Ключи API.
- Создайте ключ API с нужными правами (заказы, клиенты, склад, справочники). Для мультисайтового ключа передавайте код
siteв инструментах создания и изменения (см.list_sites). - Запомните свой домен (часть
yourstoreизyourstore.retailcrm.ru).
Переменные окружения
| Переменная | Обяз. | Описание |
|---|---|---|
RETAILCRM_DOMAIN | да | Домен вашего RetailCRM (например, yourstore.retailcrm.ru) |
RETAILCRM_API_KEY | да | Ключ API (передаётся в заголовке X-API-KEY) |
RETAILCRM_READONLY | нет | 1 — оставить только читающие инструменты (скрыть create/update/merge/delete) |
RETAILCRM_RATE_LIMIT | нет | Клиентское ограничение запросов в секунду (RetailCRM допускает ~10/с) |
PORT / HOST | нет | Привязка HTTP-сервера (по умолчанию 3000 / 127.0.0.1, только в режиме --http) |
RETAILCRM_HTTP_ALLOWED_HOSTS | нет | Разрешённые значения Host через запятую для защиты от DNS-rebinding |
RETAILCRM_DNS_PROTECTION | нет | off — отключить защиту от DNS-rebinding (HTTP-режим) |
RETAILCRM_URLпо-прежнему принимается как запасной вариант дляRETAILCRM_DOMAIN.
Подключение к Claude Desktop
Режим Streamable HTTP
Запуск в виде HTTP-сервера вместо stdio:
POST /mcp— эндпоинт MCP Streamable HTTP (stateless: на каждый запрос создаётся новый сервер)GET /health— проверка состояния (JSON с версией и числом инструментов)GET/DELETE /mcp—405(в stateless-режиме не используются)- Привязка по умолчанию:
127.0.0.1:3000. Защита от DNS-rebinding для локальных привязок включена по умолчанию.
Smithery
Демо-промпты
1. Обзор заказов за день: «Покажи все заказы, созданные сегодня, в статусе „новый“. Дай итоговое количество и выручку.»
2. Клиент и его история заказов: «Найди клиента с почтой anna@example.com. Покажи полный профиль и последние заказы.»
3. Проверка остатков: «Есть ли товар с externalId SKU-42 в наличии и на каком складе?»
Вебхуки и триггеры
RetailCRM не умеет создавать вебхуки через API. Используйте Триггеры в админке (Настройки → Триггеры), чтобы отправлять HTTP-запросы на внешние эндпоинты по событиям заказов и клиентов.
Обработка ошибок
- Лимиты запросов и 5xx: автоматический повтор с экспоненциальной задержкой и джиттером (до 3 попыток).
- Ошибки API: детали ошибки RetailCRM разбираются и возвращаются модели как результат инструмента с
isError: true, чтобы агент мог исправиться сам (например, повторить сby:"externalId"). - Таймауты: 15 секунд на запрос с повтором.
Разработка
Лицензия
MIT