Retailcrm Mcp

io.github.theYahia由 GitHub 账号 theYahia 发布v1.0.0更新于 Oct 24, 2026

MCP server for RetailCRM — orders, customers management via API v5.

已验证STDIO仅桌面数据与分析商业与电商

概览

AI 生成的概览

RetailCRM 的 MCP 服务器，让助手通过 API v5 读写订单、客户、商品、库存、支付、任务和分析数据。

可以做什么
  • 浏览、读取、创建和修改订单，并查看订单变更历史
  • 按姓名、邮箱、电话搜索客户，读取、创建、修改、合并客户并查看变更日志
  • 列出商品、商品分类树以及按仓库的库存与成本价
  • 记录、修改和删除订单支付；列出并创建用于毛利分析的支出记录
  • 管理客户备注和任务，读取客户分群
  • 上传和获取附件文件，读取状态、配送方式、支付方式、门店、站点、国家、订单类型等字典，并获取订单与新客户的周期汇总
适用场景
适合让助手直接查询或操作线上 RetailCRM 店铺：查看某笔订单的状态、按邮箱或电话找客户、核对库存，或生成每日订单与营收汇总，而无需手工导出数据。
运行要求
通过 npx（Node.js）以 stdio 本地运行，或用 --http 参数以 Streamable HTTP 方式运行。需要 RetailCRM 域名和在店铺 API 密钥设置中创建的 API 密钥；README 说明使用 RETAILCRM_DOMAIN 与 RETAILCRM_API_KEY，而清单将 RETAILCRM_URL 列为必需密钥。可选配置包括只读模式、请求限速和 HTTP 绑定地址。
安装前请注意
API 密钥可访问店铺数据，包括客户姓名、邮箱和电话，这些内容会发送给模型。写入类工具会创建和修改订单、客户、支付、备注与任务，其中 merge_customers 和 order_payment_delete 被标为破坏性操作。只读模式可隐藏写入工具。README 指出 v3 改变了默认输出格式，旧配置可能需要 raw:true。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Retailcrm Mcp，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

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

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

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

[npm] [Smithery]

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

Читающие инструменты возвращают компактную структурированную сводку только из тех полей, которые нужны агенту, а не весь ответ 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. Клиент и его история заказов: «Найди клиента с почтой [email protected]. Покажи полный профиль и последние заказы.»

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

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

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

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

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

Разработка

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

Лицензия

MIT

Часть WWmcp · Telegram: @vhodvai

来源：README.md，提交 a127a20

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v1.0.0最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分