{
  "markdown": "# MCP-сервер для RetailCRM — заказы, клиенты и товары интернет-магазина через ИИ\n\nЕсли вы искали, как подключить RetailCRM к нейросети, поднять заказ или карточку клиента и не собирать отчёты руками — это оно. 39 инструментов и 2 навыка поверх API v5: заказы, клиенты, товары, складские остатки, оплаты, задачи, справочники и аналитика. Спрашиваете «что с заказом 12345» — получаете статус, состав и оплату одним ответом.\n\n> Промышленный MCP-сервер для e-commerce CRM **RetailCRM**. 39 инструментов + 2 навыка-промпта для работы с заказами, клиентами, товарами, остатками, оплатами, задачами, справочниками и аналитикой через API v5.\n\n[![npm](https://img.shields.io/npm/v/@theyahia/retailcrm-mcp)](https://www.npmjs.com/package/@theyahia/retailcrm-mcp)\n[![Smithery](https://smithery.ai/badge/@theyahia/retailcrm-mcp)](https://smithery.ai/server/@theyahia/retailcrm-mcp)\n\n## Ответы экономят токены по умолчанию\n\nЧитающие инструменты возвращают **компактную структурированную сводку** только из тех полей, которые нужны агенту, а не весь ответ RetailCRM. Подробность настраивается на каждый вызов:\n\n| Параметр | Что делает |\n|-------|--------|\n| _(по умолчанию)_ | `detail:\"summary\"` — ключевые поля + блок `pagination` |\n| `detail:\"full\"` | Все структурированные поля (позиции, доставка, оплаты, адрес…) |\n| `raw:true` | Нетронутый ответ RetailCRM (для отладки) |\n\n> ⚠️ **v3 ломает совместимость** с v2: по умолчанию отдаётся структурированная сводка, а не сырой JSON. Передайте `raw:true`, чтобы вернуть прежний формат.\n\n## Инструменты (39)\n\n### Заказы\n| Инструмент | Описание |\n|------|-------------|\n| `list_orders` | Список заказов по статусу, клиенту, номеру, периоду |\n| `get_order` | Один заказ по ID или externalId |\n| `create_order` | Создать заказ; привязать существующего клиента (`customer_id`/`customer_external_id`) или завести нового прямо в вызове |\n| `update_order` | Изменить статус, клиента, доставку, комментарии |\n| `orders_history` | История изменений заказов, включая смены статусов (инкрементальная синхронизация) |\n\n### Клиенты\n| Инструмент | Описание |\n|------|-------------|\n| `list_customers` | Поиск клиентов по имени, e-mail, телефону, дате |\n| `get_customer` | Один клиент по ID или externalId |\n| `create_customer` | Создать клиента |\n| `update_customer` | Изменить существующего клиента |\n| `merge_customers` | Объединить дубли (разрушающая операция) |\n| `customers_history` | Лог изменений клиентов (прирост/отток, инкрементальная синхронизация) |\n\n### Товары и остатки\n| Инструмент | Описание |\n|------|-------------|\n| `list_products` | Товары каталога по названию, группе, активности, цене |\n| `list_product_groups` | Дерево товарных категорий |\n| `store_inventories` | Остатки и себестоимость по торговым предложениям и складам |\n\n### Оплаты\n| Инструмент | Описание |\n|------|-------------|\n| `order_payment_create` | Зафиксировать оплату по заказу |\n| `order_payment_edit` | Изменить оплату |\n| `order_payment_delete` | Удалить оплату (разрушающая операция) |\n\n### Заметки и задачи\n| Инструмент | Описание |\n|------|-------------|\n| `customer_notes_list` / `customer_notes_create` / `customer_notes_delete` | Произвольные заметки по клиенту |\n| `tasks_list` / `tasks_create` / `tasks_edit` | Задачи и напоминания |\n\n### Маркетинг и финансы\n| Инструмент | Описание |\n|------|-------------|\n| `list_segments` | Сегменты клиентов (RFM и маркетинговые когорты) |\n| `list_costs` / `create_cost` | Записи расходов для аналитики маржи |\n\n### Файлы\n| Инструмент | Описание |\n|------|-------------|\n| `files_list` / `files_get` / `files_upload` | Прикрепление и получение файлов (загрузка сырым octet-stream) |\n\n### Справочники\n| Инструмент | Описание |\n|------|-------------|\n| `list_statuses` / `list_delivery_types` / `list_payment_types` / `list_stores` | Справочники статусов, доставок, оплат и магазинов |\n| `list_sites` | Сайты, доступные ключу API (для заполнения параметра `site`) |\n| `list_countries` / `list_order_types` / `list_order_methods` | Справочники адресов и заказов |\n\n### Аналитика\n| Инструмент | Описание |\n|------|-------------|\n| `get_orders_summary` | Статистика заказов за период: точное количество и выручка, средний чек, распределение по статусам |\n| `get_customers_summary` | Количество новых клиентов за период |\n\n## Навыки-промпты (2)\n\n| Навык | Описание |\n|-------|-------------|\n| `new-orders` | Быстрый ежедневный обзор сегодняшних заказов |\n| `customer-search` | Найти клиента по имени, e-mail или телефону |\n\n## Настройка\n\n1. В RetailCRM откройте **Настройки → Интеграция → Ключи API**.\n2. Создайте ключ API с нужными правами (заказы, клиенты, склад, справочники). Для **мультисайтового** ключа передавайте код `site` в инструментах создания и изменения (см. `list_sites`).\n3. Запомните свой домен (часть `yourstore` из `yourstore.retailcrm.ru`).\n\n## Переменные окружения\n\n| Переменная | Обяз. | Описание |\n|----------|----------|-------------|\n| `RETAILCRM_DOMAIN` | да | Домен вашего RetailCRM (например, `yourstore.retailcrm.ru`) |\n| `RETAILCRM_API_KEY` | да | Ключ API (передаётся в заголовке `X-API-KEY`) |\n| `RETAILCRM_READONLY` | нет | `1` — оставить только читающие инструменты (скрыть create/update/merge/delete) |\n| `RETAILCRM_RATE_LIMIT` | нет | Клиентское ограничение запросов в секунду (RetailCRM допускает ~10/с) |\n| `PORT` / `HOST` | нет | Привязка HTTP-сервера (по умолчанию `3000` / `127.0.0.1`, только в режиме `--http`) |\n| `RETAILCRM_HTTP_ALLOWED_HOSTS` | нет | Разрешённые значения `Host` через запятую для защиты от DNS-rebinding |\n| `RETAILCRM_DNS_PROTECTION` | нет | `off` — отключить защиту от DNS-rebinding (HTTP-режим) |\n\n> `RETAILCRM_URL` по-прежнему принимается как запасной вариант для `RETAILCRM_DOMAIN`.\n\n## Подключение к Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"retailcrm\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@theyahia/retailcrm-mcp\"],\n      \"env\": {\n        \"RETAILCRM_DOMAIN\": \"yourstore.retailcrm.ru\",\n        \"RETAILCRM_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n## Режим Streamable HTTP\n\nЗапуск в виде HTTP-сервера вместо stdio:\n\n```bash\nRETAILCRM_DOMAIN=yourstore.retailcrm.ru \\\nRETAILCRM_API_KEY=your-key \\\nnpx @theyahia/retailcrm-mcp --http\n```\n\n- `POST /mcp` — эндпоинт MCP Streamable HTTP (stateless: на каждый запрос создаётся новый сервер)\n- `GET /health` — проверка состояния (JSON с версией и числом инструментов)\n- `GET`/`DELETE /mcp` — `405` (в stateless-режиме не используются)\n- Привязка по умолчанию: `127.0.0.1:3000`. Защита от DNS-rebinding для локальных привязок включена по умолчанию.\n\n## Smithery\n\n```bash\nnpx @smithery/cli install @theyahia/retailcrm-mcp\n```\n\n## Демо-промпты\n\n**1. Обзор заказов за день:** «Покажи все заказы, созданные сегодня, в статусе „новый“. Дай итоговое количество и выручку.»\n\n**2. Клиент и его история заказов:** «Найди клиента с почтой anna@example.com. Покажи полный профиль и последние заказы.»\n\n**3. Проверка остатков:** «Есть ли товар с externalId SKU-42 в наличии и на каком складе?»\n\n## Вебхуки и триггеры\n\nRetailCRM не умеет создавать вебхуки через API. Используйте **Триггеры** в админке (Настройки → Триггеры), чтобы отправлять HTTP-запросы на внешние эндпоинты по событиям заказов и клиентов.\n\n## Обработка ошибок\n\n- **Лимиты запросов и 5xx:** автоматический повтор с экспоненциальной задержкой и джиттером (до 3 попыток).\n- **Ошибки API:** детали ошибки RetailCRM разбираются и возвращаются модели как результат инструмента с `isError: true`, чтобы агент мог исправиться сам (например, повторить с `by:\"externalId\"`).\n- **Таймауты:** 15 секунд на запрос с повтором.\n\n## Разработка\n\n```bash\nnpm install\nnpm test          # vitest (на моках; живой ключ API не нужен)\nnpm run lint      # eslint\nnpm run typecheck # tsc --noEmit\nnpm run dev       # dev-режим stdio (tsx)\nnpm run build     # очистка + сборка в dist/\n```\n\n## Лицензия\n\nMIT\n\n---\n\nЧасть [WWmcp](https://github.com/theYahia/WWmcp) · Telegram: [@vhodvai](https://t.me/vhodvai)\n",
  "bytes": 7924,
  "sha": "9d5a53b7d264fdf767c3858e717f339dc5afabb8231b0746096a59852945c623",
  "repo_slug": "theyahia/retailcrm-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_theyahia_retailcrm_mcp_75225184/readme"
}