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 分