A production-grade MCP server for RetailCRM that lets an agent manage e-commerce orders, customers, products, inventory, payments, tasks, references, files, and PII-free analytics via 44 tools and 2 prompt skills.
Orders: list, get, create, update, and view history/status changes; supports incremental sync via since_id.
Customers: list, get, create, update, and merge duplicate customers; view change history; manage customer notes.
Products & inventory: list catalog products and category trees; check stock levels and cost prices per offer/warehouse.
Payments: create, edit, and delete payments on orders.
Tasks: list, create, and edit follow-up tasks/reminders.
Marketing & finance: list customer segments; list and create expense records for margin analytics.
Files: list, get metadata for, and upload files attached to orders/customers.
Reference data: fetch order statuses, delivery types, payment types, stores, sites, countries, order types, and order methods.
Analytics: get period order summaries (revenue, AOV, status distribution), customer summaries, and PII-free SEO-SXO analytics (attribution fields, order analytics, paid orders, order attribution, history) with HMAC join keys.
Prompt skills: new-orders daily overview and customer-search lookup.
Output control: compact shaped summaries by default; detail:"full" for more fields; raw:true for untouched payloads.
Operational features: read-only mode, multi-site site param, client-side rate limiting, retries, and fail-closed safety for analytics secrets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@retailcrm-mcp Show me a summary of today's orders"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Production-grade MCP server for RetailCRM e-commerce CRM. 44 tools + 2 prompt skills for managing orders, customers, products, inventory, payments, tasks, references, and analytics via API v5.
API traffic is transported by the official retailcrm/api-client-php client, pinned to 6.15.32, invoked from Node through a PHP bridge (bin/retailcrm-api.php). The server ships as a self-contained Docker image — no host PHP or Composer required.
Forked from theYahia/retailcrm-mcp (MIT).
Read tools return a compact, shaped summary of only the fields an agent needs — not the full RetailCRM payload. Control verbosity per call:
Param | Effect |
(default) |
|
| All shaped fields (line items, delivery, payments, address…) |
| The untouched RetailCRM response (for debugging) |
⚠️ v3 was a breaking change vs v2: default output is the shaped summary instead of raw JSON. Pass
raw:trueto restore the old payload.
Related MCP server: Method CRM MCP Server
Tool | Description |
| List orders by status, customer, number, date range |
| Get one order by ID or externalId |
| Create an order; link an existing customer ( |
| Update status, customer, delivery, comments |
| Order change history (incremental sync). Default: safe PII-free projection ( |
Tool | Description |
| Search customers by name, email, phone, date |
| Get one customer by ID or externalId |
| Create a customer |
| Edit an existing customer |
| Merge duplicates (destructive) |
| Customer change log (growth/churn, incremental sync) |
Tool | Description |
| Catalog products by name, group, active, price |
| Product category tree |
| Stock levels & cost prices per offer/warehouse |
Tool | Description |
| Record a payment on an order |
| Edit a payment |
| Delete a payment (destructive) |
Tool | Description |
| Free-text customer notes |
| Follow-up tasks/reminders |
Tool | Description |
| Customer segments (RFM/marketing cohorts) |
| Expense records for margin analytics |
Tool | Description |
| Attach & retrieve files (raw octet-stream upload) |
Tool | Description |
| Order/delivery/payment/store reference data |
| Sites the API key can act on (fill the |
| Address & order reference data |
Tool | Description |
| Period-scoped order stats: exact count + revenue, AOV, status distribution |
| New-customer count for a date range |
Read-only, pagination-complete analytics that a Yandex Metrica layer can join on a pseudonymous key — no customer identity persisted or returned. Criteria: docs/criteria/retailcrm-analytics-sxo-v1.md.
Tool | Description |
| Search ORDER custom-field metadata (code/name/type; request scoped with |
| PII-free order analytics for a date window ( |
| Same projection restricted to orders proven fully paid by non-empty |
| PII-free attribution for one order by id/externalId |
| Incremental change feed via the official |
Projection is allowlist-only: ids, timestamps, status, order method, site, total/currency, native source/medium/campaign, retailcrm_client_id (native label — never represented as Yandex client_id), configured attribution tokens, safe item fields, authoritative sales_channel and the HMAC-SHA256 join key. sales_channel is read only from the order's own customFields.sales_channel; missing historical, empty, malformed or unsupported values are UNKNOWN. Delivery, order method, site, source and attribution never determine the sales channel. The legacy channel field remains compatibility-only and is derived from sales_channel without fallback. payment_evidence separates order-level CRM proof from payment-amount evidence: crm_fully_paid, the canonical full_paid_at and its byte-equal compatibility alias paid_at come only from non-empty order.fullPaidAt (payment/order statuses can never populate them); paymentComplete=true selects individual numeric payment amounts only for crm_paid_amount and amount_matches; payment_provider is evidence-only, proven solely by completed payments with exactly mapped types. sber_paid_amount_rub reuses that safe crm_paid_amount only when the proven provider is SBER (otherwise null; the acquiring fee is never calculated here), and delivery_income_rub is the customer-paid delivery.cost copied only when the safe delivery projection accepted a finite non-negative number (never derived from totalSumm, netCost, delivery type or defaults). The RetailCRM-only states are CRM_PAID, PARTIAL and UNKNOWN; FINANCE_CONFIRMED requires a separate downstream settlement join and is not emitted here. Item revenue sums every prices[] tranche (price*quantity) when the tranches are numerically complete, otherwise initialPrice * quantity - discountTotal, where discountTotal is the total discount for the line; vat_rate is the provider's string verbatim; item SKU is offer.externalId → xmlId → article. History old/new values are exposed only for status, payments and fullPaidAt as full_paid_at; a history record without an orderExternalId gets join_key: null with join_key_omitted_reason: "no_order_external_id" (never a CRM-id HMAC). max_orders/max_records are page-aligned soft stops (may overshoot by at most one 100-record page), stated in each output's bounds block. Names, phones, emails, addresses, comments, marking codes, user ids and arbitrary custom fields are never emitted. All order analytics tools fail closed when RETAILCRM_ANALYTICS_HMAC_SECRET is absent or shorter than 32 characters.
Skill | Description |
| Quick daily overview of today's orders |
| Find a customer by name, email, or phone |
In RetailCRM, go to Settings > Integration > API keys.
Create an API key with the required permissions (orders, customers, store, references). For a multi-site key, pass the site code on create/edit tools (see list_sites).
Note your domain (the yourstore part of yourstore.retailcrm.ru).
Secrets are provided via environment variables only — never on the command line, in config files, or in logs.
Variable | Required | Description |
| Yes | Your RetailCRM domain (e.g. |
| Yes | API key (sent via the |
| No |
|
| No | Client-side requests/second cap (RetailCRM allows ~10/s) |
| No | PHP executable for the local (non-Docker) path (default |
| No | Path to |
| No | HTTP server bind (default |
| No | Comma-separated allowed |
| No |
|
| For analytics | HMAC-SHA256 key for pseudonymous order join keys (>= 32 chars; order analytics fail closed without it) |
| No | JSON map of canonical key ( |
| No | JSON map of |
| No | JSON map of exact RetailCRM payment type codes to a closed provider set ( |
RETAILCRM_URLis still accepted as a fallback forRETAILCRM_DOMAIN.
Build the self-contained image (Node + PHP CLI/cURL + compiled server + PHP bridge + Composer production dependencies — official retailcrm/api-client-php 6.15.32):
docker build -t retailcrm-mcp:3.1.0 .Run over stdio:
docker run --rm -i \
-e RETAILCRM_DOMAIN=yourstore.retailcrm.ru \
-e RETAILCRM_API_KEY=your-api-key \
retailcrm-mcp:3.1.0Run the Streamable HTTP server instead by appending --http:
docker run --rm -p 127.0.0.1:3000:3000 \
-e RETAILCRM_DOMAIN=yourstore.retailcrm.ru \
-e RETAILCRM_API_KEY=your-api-key \
-e HOST=0.0.0.0 \
retailcrm-mcp:3.1.0 --http{
"mcpServers": {
"retailcrm": {
"command": "docker",
"args": [
"run", "--rm", "-i", "--init",
"-e", "RETAILCRM_DOMAIN",
"-e", "RETAILCRM_API_KEY",
"retailcrm-mcp:3.1.0"
],
"env": {
"RETAILCRM_DOMAIN": "yourstore.retailcrm.ru",
"RETAILCRM_API_KEY": "your-api-key"
}
}
}
}If you prefer not to use Docker, run the same stack locally:
# 1. Node dependencies + compile
npm install
npm run build
# 2. PHP dependencies (Composer >= 2; plugins and scripts disabled)
composer install --no-dev --no-interaction --no-progress --no-scripts --no-plugins --optimize-autoloader
# 3. Run (stdio)
RETAILCRM_DOMAIN=yourstore.retailcrm.ru \
RETAILCRM_API_KEY=your-api-key \
node dist/index.js
# Or the HTTP server
RETAILCRM_DOMAIN=yourstore.retailcrm.ru \
RETAILCRM_API_KEY=your-api-key \
node dist/index.js --httpRequires Node >= 18 and PHP >= 8.1 with the cURL, JSON, mbstring, and openssl extensions.
All normal RetailCRM traffic (GET and form POST) goes through the official
retailcrm/api-client-php 6.15.32 client (SimpleClientFactory::createClient +
CustomMethods/CustomApiMethod), executed inside bin/retailcrm-api.php.
The Node client (src/client.ts) talks to the bridge over JSON on stdin/stdout
with a versioned, fail-closed protocol: malformed, empty, or non-JSON bridge
output is always an error, never success.
files_upload is the one documented compatibility exception. The official
v6.15.32 FilesUploadRequest does not preserve this MCP's ?filename= query
parameter and caller MIME type, so the bridge performs that single call with
PHP cURL — same normalized origin, X-API-KEY header, 15-second timeout, and
bounded error handling. Every other tool uses the official client.
Retry policy is unchanged: 3 attempts, 429 always retried, timeout/5xx retried
for GETs only (never for ambiguous POSTs), optional client-side rate gate.
1. Daily order overview: "Show me all orders created today with status 'new'. Summarize the total count and revenue."
2. Customer lookup and order history: "Find the customer with email anna@example.com. Show their full profile and recent orders."
3. Stock check: "Is the product with externalId SKU-42 in stock, and in which warehouse?"
RetailCRM does not support API-created webhooks. Use Triggers in the admin panel (Settings > Triggers) to send HTTP requests to external endpoints on order/customer events.
Rate limits / 5xx: automatic retry with exponential backoff + jitter (up to 3 attempts).
API errors: RetailCRM error details are parsed and returned to the model as a tool result with isError: true, so the agent can self-correct (e.g. retry with by:"externalId").
Timeouts: 15-second whole-call timeout, enforced by terminating the bridge process.
npm install
npm test # vitest (mock-based; no live API key needed)
npm run lint # eslint
npm run typecheck # tsc --noEmit
npm run dev # stdio dev mode (tsx)
npm run build # clean + compile to dist/MIT — upstream © Yahia (theYahia/retailcrm-mcp); retailcrm/api-client-php is MIT © RetailCRM.
Create an expense record, optionally attributed to an order. Returns {success, id}.
Inputs: summ (required), cost_item (required), date_from (required), site, +3 more.
Create a customer with name, contacts, address, optional externalId. Returns {success, id}.
Inputs: first_name (required), site, email, phones, +6 more.
Create an order with line items and delivery. Link an existing customer via customer_id/customer_external_id, or pass first_name (+phone/email) to create one inline. Returns {success, id, order?}.
Inputs: items (required), site, email, phone, +9 more.
Add a note to a customer (by id or externalId). Returns {success, id}.
Inputs: text (required), site, manager_id, customer_id, +1 more.
Delete a customer note by id. Returns {success}.
Inputs: id (required).
List free-text notes attached to customers. Returns {notes[], pagination}.
Inputs: page, limit, filter_customer_id, filter_customer_external_id.
Customer field-change log for growth/churn signals and incremental sync. Returns {history[], pagination}.
Inputs: raw, page, limit, filter_date_to, +2 more.
Get a file's metadata by id. Returns {file}.
Inputs: id (required).
List files attached to orders/customers. Returns {files[], pagination}.
Inputs: page, limit, filter_filename, filter_order_id, +1 more.
Upload a file (UTF-8 text or base64 binary). Returns {success, file}.
Inputs: content (required), filename (required), base64, content_type.
Get a single customer by id or externalId. Returns a shaped customer; detail:'full' adds address and contact details.
Inputs: id (required), by, raw, detail.
Period-scoped new-customer count for a date range. Returns {period, newCustomers}.
Inputs: date_to (required), date_from (required).
Get a single order by RetailCRM id or externalId. Returns a shaped order; detail:'full' adds items, delivery, payments, comments.
Inputs: id (required), by, raw, detail.
Period-scoped order summary: exact totalCount for the date range plus revenue, average order value, and status distribution aggregated over up to max_pages×100 orders (partial:true if the window exceeds that).
Inputs: date_to (required), date_from (required), max_pages, filter_status.
List expense records (for margin/profit analytics) by date and cost group. Returns {costs[], pagination}.
Inputs: page, limit, filter_date_to, filter_date_from, +1 more.
Valid country ISO codes for addresses/delivery.
Inputs: raw.
List/search customers by name, email, phone, created-date. Returns (summary): pagination + array of {id, name, email, phone, ordersCount, totalSpent}. detail:'full' adds address/externalId/all phones.
Inputs: raw, page, limit, detail, +5 more.
All delivery types with codes, names, default costs.
Inputs: raw.
All order methods (acquisition channels).
Inputs: raw.
List orders with filters by status, customer name, number, and created-date range. Returns (summary): pagination + array of {id, number, status, total, customer, phone, itemCount, createdAt}. Use detail:'full' for line items/delivery/payments, raw:true for the untouched payload.
Inputs: raw, page, limit, detail, +5 more.
All order types (codes/names) — valid values for create_order's order_type.
Inputs: raw.
All payment types with codes and names.
Inputs: raw.
List product groups (category tree). Returns {productGroup[], pagination}.
Inputs: page, limit, filter_active, filter_parent_group.
List catalog products with filters by name, active, group, price range. Returns pagination + array of {id, name, article, active, url, groups, offers}.
Inputs: raw, page, limit, filter_name, +4 more.
List customer segments (RFM/marketing cohorts). Returns {segments[], pagination}.
Inputs: page, limit, filter_type, filter_active.
All sites/stores the API key can act on — use the returned code as the site param on multi-site create/edit.
Inputs: raw.
All order statuses (codes, names, groups, ordering). Call before filtering/updating orders by status.
Inputs: raw.
All warehouses/stores (codes, names, types).
Inputs: raw.
Merge duplicate customers into a target; merged records are DELETED. Returns {success}.
Inputs: result_customer_id (required), merged_customer_ids (required).
Record a payment against an order (amount, type, status, paid_at). Returns {success, id}.
Inputs: type (required), amount (required), site, status, +3 more.
Delete an order payment by id. Returns {success}.
Inputs: id (required).
Edit an existing order payment (amount/status/paid_at). Returns {success}.
Inputs: id (required), by, site, amount, +2 more.
Order change history incl. status transitions; supports incremental sync via filter_since_id and a date window. Returns {history[], pagination}.
Inputs: raw, page, limit, filter_date_to, +3 more.
Stock levels (and cost prices) per offer/warehouse. Use details:true for the per-store breakdown. Returns {offers[], pagination}.
Inputs: page, site, limit, details, +2 more.
Create a task (text, due datetime, performer, linked order/customer). Returns {success, id}.
Inputs: text (required), site, datetime, order_id, +3 more.
Edit a task or mark it complete. Returns {success}.
Inputs: id (required), site, text, complete, +3 more.
List follow-up tasks/reminders, filterable by status/performer/customer. Returns {tasks[], pagination}.
Inputs: page, limit, filter_status, filter_customer, +1 more.
Edit an existing customer (name, email, phones, address) by id or externalId. Only the fields you pass are sent. Returns {success}.
Inputs: id (required), by, site, email, +7 more.
Update an order (status, customer, delivery, comments). Only the fields you pass are sent. Returns {success}.
Inputs: id (required), by, site, email, +11 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 39 tools
Each tool targets a distinct resource-action pair. Even with many list_* tools, the resources (orders, customers, products, statuses, etc.) are clearly different, and descriptions prevent confusion.
Naming is inconsistent: verb-first ('list_orders', 'create_order') for core entities vs noun-first ('tasks_list', 'order_payment_create') for sub-entities. Also 'store_inventories' lacks a verb, breaking the pattern.
At 39 tools, this is far beyond the typical well-scoped range. While the CRM domain is broad, the tool surface would benefit from consolidation, e.g., a generic reference-data lister or grouping sub-resources.
Core order/customer workflows are well covered (CRUD, history, payments, notes). However, product management is missing (only list), and costs/tasks/files lack full CRUD (e.g., no product create/update, no cost edit/delete).
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
