@theyahia/retailcrm-mcp

Production-grade MCP server for RetailCRM e-commerce CRM. 15 tools + 2 prompt skills for managing orders, customers, products, references, and analytics via API v5.

Tools (15)

Orders

Tool	Description
list_orders	List orders with filters by status, customer, number, date range
get_order	Get a single order by ID or externalId
create_order	Create an order with customer info, line items, delivery
update_order	Update order status, customer details, delivery, comments

Customers

Tool	Description
list_customers	Search customers by name, email, phone, date
get_customer	Get a single customer by ID or externalId
create_customer	Create customer with contact info and address
merge_customers	Merge duplicate customer records

Products

Tool	Description
list_products	List products with filters by name, group, active status, price range

References

Tool	Description
list_statuses	All order statuses (codes, names, groups)
list_delivery_types	All delivery types with default costs
list_payment_types	All payment types
list_stores	All warehouses and stores

Analytics

Tool	Description
get_orders_summary	Order statistics for a date range
get_customers_summary	Customer growth stats for a date range

Prompt Skills (2)

Skill	Description
new-orders	Quick daily overview of today's orders
customer-search	Find a customer by name, email, or phone

Setup

1. In RetailCRM, go to Settings > Integration > API keys
2. Create a new API key with the required permissions (orders, customers, stores, references)
3. Note your domain (the yourstore part of yourstore.retailcrm.ru)

Environment Variables

Variable	Required	Description
RETAILCRM_DOMAIN	Yes	Your RetailCRM domain (e.g. yourstore.retailcrm.ru)
RETAILCRM_API_KEY	Yes	API key from Settings > Integration > API keys
PORT	No	HTTP server port (default: 3000, only for --http mode)

RETAILCRM_URL is still supported as a fallback for backward compatibility.

Usage with Claude Desktop

{
  "mcpServers": {
    "retailcrm": {
      "command": "npx",
      "args": ["-y", "@theyahia/retailcrm-mcp"],
      "env": {
        "RETAILCRM_DOMAIN": "yourstore.retailcrm.ru",
        "RETAILCRM_API_KEY": "your-api-key"
      }
    }
  }
}

Streamable HTTP Mode

Run as an HTTP server instead of stdio:

RETAILCRM_DOMAIN=yourstore.retailcrm.ru \
RETAILCRM_API_KEY=your-key \
npx @theyahia/retailcrm-mcp --http

• POST /mcp -- MCP Streamable HTTP endpoint
• GET /health -- health check (returns JSON with version, tool count)
• Default port: 3000 (override with PORT env var)

Smithery

Install via Smithery:

npx @smithery/cli install @theyahia/retailcrm-mcp

Demo Prompts

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. Quick order creation:

"Create an order for Ivan Petrov, phone +79001234567, for 2x Widget at 500 RUB each, standard delivery to Moscow."

Webhooks / Triggers

RetailCRM does not support API-created webhooks. Instead, use Triggers in the RetailCRM admin panel (Settings > Triggers) to configure automated actions on order/customer events. Triggers can send HTTP requests to external endpoints when conditions are met.

Error Handling

• Rate limits (429): Automatic retry with exponential backoff (up to 3 attempts)
• Server errors (5xx): Automatic retry with exponential backoff
• Validation errors: RetailCRM error details are parsed and returned as readable messages
• Timeouts: 15-second timeout per request with automatic retry

Development

npm install
npm test          # run Vitest tests
npm run dev       # start in dev mode (stdio)
npm run build     # compile TypeScript

Referral Program

Earn up to 50% recurring commission by referring RetailCRM users who connect via this MCP server. Contact @theYahia for details and your referral link.

License

MIT