Retailcrm Mcp

io.github.theYahiaPublished by GitHub account theYahiav1.0.0Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

MCP server for RetailCRM that lets an assistant read and manage orders, customers, products, stock, payments, tasks and analytics via API v5.

What you can do
  • Browse, read, create and update orders, including order change history
  • Search, read, create, update and merge customers, plus customer change logs
  • List products, product category trees and stock levels with cost prices
  • Record, edit and delete order payments; list and create expense records
  • Manage customer notes and tasks, and read customer segments
  • Upload and fetch attached files, read reference lists (statuses, delivery and payment types, stores, sites, countries, order types) and pull period summaries of orders and new customers
When to use it
Useful when an assistant should answer questions or act on a live RetailCRM store — checking an order's status, finding a customer by email or phone, verifying stock, or producing daily order and revenue summaries — without exporting data by hand.
Requirements
Runs locally via npx (Node.js) over stdio, or as a Streamable HTTP server with the --http flag. Needs a RetailCRM domain and an API key created in the store's API keys settings; the README documents RETAILCRM_DOMAIN and RETAILCRM_API_KEY, while the manifest lists RETAILCRM_URL as the required secret. Optional settings cover read-only mode, rate limiting and HTTP host binding.
Before you install
The API key grants access to store data, including customer names, emails and phone numbers, which are sent to the model. Write tools create and change orders, customers, payments, notes and tasks, and merge_customers and order_payment_delete are described as destructive. Read-only mode can hide write tools. The README notes version 3 changes default output format, so existing setups may need raw:true.

Installation

In SourceWeft

  1. Open Retailcrm Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

Source: README.md at commit a127a20

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts