MCP server for RetailCRM — orders, customers management via API v5.
io.github.theYahia/retailcrm-mcp — MCP server for RetailCRM (API v5)
This MCP server connects to RetailCRM to manage e-commerce data via API v5. It provides tools focused on orders, customers, and products, including access to inventory/stock balances, payments, tasks, reference data, and analytics. Its readme describes interactions that return order status, items, and payment details in a single response.
🛠️ Key Features
MCP server for RetailCRM: orders, customers, and products via API v5
39 tools for managing e-commerce CRM entities
2 skills (prompt-based) for order-related operations
Coverage includes stock balances, payments, tasks, reference books, and analytics
🚀 Use Cases
Ask about a specific order (e.g., order “12345”) to get status, composition, and payment
Retrieve and work with customer and product information through AI-driven queries
Access inventory/stock, payment data, and related tasks without manual reporting
⚡ Developer Benefits
Uses Model Context Protocol (MCP) for integration
Topics indicate TypeScript and API-based access patterns
Tool set spans orders, customers, products, stock, payments, tasks, and analytics
⚠️ Limitations
The readme excerpt only states it operates over RetailCRM API v5; other API versions or capabilities are not described
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
Остатки и себестоимость по торговым предложениям и складам
Статистика заказов за период: точное количество и выручка, средний чек, распределение по статусам
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.
POST /mcp — эндпоинт MCP Streamable HTTP (stateless: на каждый запрос создаётся новый сервер)
GET /health — проверка состояния (JSON с версией и числом инструментов)
GET/DELETE /mcp — 405 (в stateless-режиме не используются)
Привязка по умолчанию: 127.0.0.1:3000. Защита от DNS-rebinding для локальных привязок включена по умолчанию.
Smithery
bash
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 секунд на запрос с повтором.
Разработка
bash
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/
