RetailCRM MCP on the official PHP client
retailcrm-mcp
44 tools and 2 prompt skills for RetailCRM built on the official PHP client: orders, customers, inventory, payments, tasks and PII-free analytics
High risk
We rate an entry high when the tool writes to external systems, handles money, production databases or secrets, or runs arbitrary commands. The CLI installs it only with your consent.
Why this level
- Tools create, change and delete orders, payments, customers, tasks and notes, including the destructive merge_customers and order_payment_delete
- Start with RETAILCRM_READONLY=1 and a key with minimal necessary rights
Install
Manual install
docker build -t retailcrm-mcp:3.1.0 .Build the self-contained image with Node and PHP CLI before running.
This is third-party code. Review the repository files before installing.
What it does
The server ships as a self-contained Docker image with Node and PHP CLI, and routes all normal RetailCRM API v5 traffic through the official retailcrm/api-client-php client pinned to 6.15.32, invoked from Node via a PHP bridge, bin/retailcrm-api.php. It provides 44 tools: orders and their history, customers and duplicate merging, products and categories, stock and cost prices per warehouse, order payments, notes and tasks, segments and cost records, files, and status/delivery reference data. Read tools return a compact summary by default instead of the full RetailCRM JSON, with detail:full for the complete shape. A separate set of five tools provides PII-free order analytics meant to join with Yandex Metrica: only a pseudonymous HMAC join key, no names, phones, emails or addresses, and it fails closed if no HMAC secret of at least 32 characters is set.
Who it is for. For RetailCRM teams that need production-grade API coverage: orders, payments, inventory, tasks, plus analytics with no personal-data leakage.
Good fit when
- You need broad RetailCRM API coverage: payments, files, cost tracking, segments, not just basic orders and customers
- You need PII-free order analytics to join with UTM tags and Yandex Metrica
- You need a read-only mode via RETAILCRM_READONLY for safe testing
Not a fit when
- You cannot build or run a Docker image with PHP inside: without Docker you need PHP 8.1+ and Composer installed locally
- You need a minimal server without analytics and a PHP bridge: a simpler fork is easier
- RetailCRM has no API-created webhooks; events need Triggers configured separately in the admin panel
Example request
Show today's orders with status new, total the revenue, and check stock for product SKU-42 across warehousesLimitations
A fork of theYahia/retailcrm-mcp with substantial additions: a PHP bridge, 44 tools, analytics. Requires Docker, or locally PHP 8.1+ with cURL, JSON, mbstring, openssl and Composer 2, making it heavier to install than a plain Node server. The analytics tools refuse to run entirely without RETAILCRM_ANALYTICS_HMAC_SECRET of at least 32 characters. Version v3 changes the default response format to a compact summary instead of raw JSON.
How to disable. Remove the retailcrm entry from your MCP client config and stop the server's Docker container.
MCP
- Transport
- stdio, http
- Authentication
- API key
| Environment variables | |
|---|---|
| RETAILCRM_DOMAIN required | RetailCRM account domain, e.g. yourstore.retailcrm.ru |
| RETAILCRM_API_KEY required, secret | API key, sent via the X-API-KEY header |
| RETAILCRM_READONLY | Set to 1 to hide create, update, merge and delete tools |
| RETAILCRM_ANALYTICS_HMAC_SECRET secret | An HMAC-SHA256 key of at least 32 characters for pseudonymous analytics join keys; without it the analytics tools refuse to run |
Security check
- Tools create, change and delete orders, payments, customers, tasks and notes, including the destructive merge_customers and order_payment_delete
- Start with RETAILCRM_READONLY=1 and a key with minimal necessary rights
README in short
The README describes the 44 tools by section in detail, the compact-by-default response format with detail and raw switches, the PII-free analytics layer with an exact list of fields it never emits, environment variables including RETAILCRM_READONLY and RETAILCRM_ANALYTICS_HMAC_SECRET, running in Docker over stdio and HTTP, a local run without Docker, the bridge architecture to the official PHP client with one documented exception for file uploads via direct cURL, the lack of RetailCRM API webhooks, and the need for admin-panel Triggers instead.
FAQ
How do I restrict the server to read-only?
Set RETAILCRM_READONLY=1, which hides the create, update, merge and delete tools.
Why doesn't order analytics return names and phone numbers?
That is a deliberate limit: the allowlist projection excludes names, phones, emails, addresses and arbitrary custom fields, using only a pseudonymous HMAC join key to link orders.
Related
Salesforce's official DX MCP server: work with orgs, metadata, data, users and Apex tests from your agent
Yandex Kit skills for store management
kit-skills
Yandex's official skill set: catalog, prices, stock, orders, storefront and a weekly checkup for a Yandex Kit store, through Claude Code or Codex
YouGile MCP by Indalo
YouGile MCP
Full 65-operation YouGile API coverage with configurable permissions, write confirmation and a shared company rate limit
Bitrix24 portal MCP server
MCP-сервер портала Битрикс24
Bitrix24's official per-portal MCP: an external agent uses OAuth or a token to read and change tasks, deals, meetings and mail