io.github.theYahia/retailcrm-mcp
MCP server for RetailCRM — orders, customers management via API v5.
Open source Open in the app JSON README (API)
About
MCP server for RetailCRM — orders, customers management via API v5.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- theyahia
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.0
- Stars
- 1
- Forks
- 1
- Last push
- 2026-09-03T04:52:37Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:31
- Updated
- 2026-08-29 04:01:31
- Origin id
io.github.theYahia/retailcrm-mcp
README
# MCP-сервер для RetailCRM — заказы, клиенты и товары интернет-магазина через ИИ
Если вы искали, как подключить RetailCRM к нейросети, поднять заказ или карточку клиента и не собирать отчёты руками — это оно. 39 инструментов и 2 навыка поверх API v5: заказы, клиенты, товары, складские остатки, оплаты, задачи, справочники и аналитика. Спрашиваете «что с заказом 12345» — получаете статус, состав и оплату одним ответом.
> Промышленный MCP-сервер для e-commerce CRM **RetailCRM**. 39 инструментов + 2 навыка-промпта для работы с заказами, клиентами, товарами, остатками, оплатами, задачами, справочниками и аналитикой через API v5.
[](https://www.npmjs.com/package/@theyahia/retailcrm-mcp)
[](https://smithery.ai/server/@theyahia/retailcrm-mcp)
## Ответы экономят токены по умолчанию
Читающие инструменты возвращают **компактную структурированную сводку** только из тех полей, которые нужны агенту, а не весь ответ 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 или телефону |
## Настройка
1. В RetailCRM откройте **Настройки → Интеграция → Ключи API**.
2. Создайте ключ API с нужными правами (заказы, клиенты, склад, справочники). Для **мультисайтового** ключа передавайте код `site` в инструментах создания и изменения (см. `list_sites`).
3. Запомните свой домен (часть `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
```json
{
"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:
```bash
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
```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/
```
## Лицензия
MIT
---
Часть [WWmcp](https://github.com/theYahia/WWmcp) · Telegram: [@vhodvai](https://t.me/vhodvai)