mindbox-mcp
A Mindbox CDP MCP server that lets AI assistants query and manage customer profiles, orders, segments, product lists, and arbitrary Mindbox operations via natural language.
Retrieve customer profiles by email, phone, or external ID (
get_customer)Create orders linked to customers (
create_order)Get customer segments in Mindbox (
get_segments)Fetch paginated product lists (
get_product_list)Update customer profile fields and custom fields (
update_customer)Run arbitrary Mindbox API operations in sync or async mode, with the option to disable this for safety (
run_operation)Supports stdio and HTTP transports, retries with backoff, and skills for common scenarios
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., "@mindbox-mcp Show me the profile for customer with email john@doe.com"
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.
@theyahia/mindbox-mcp
MCP server for the Mindbox CDP API — customer profiles, orders, segments, product lists, and arbitrary operations.
Features
6 tools for working with the Mindbox API
Transport: stdio (default) and Streamable HTTP (
--http)Compatible with Claude Desktop, Claude Code, Cursor, Smithery
Retries with backoff and idempotency (
transactionId), HTTP transport protectionSkills for automating common scenarios
Related MCP server: Constant Contact MCP Server
Installation
Claude Desktop
{
"mcpServers": {
"mindbox": {
"command": "npx",
"args": ["-y", "@theyahia/mindbox-mcp"],
"env": {
"MINDBOX_API_KEY": "ваш_ключ",
"MINDBOX_ENDPOINT_ID": "ваш_endpoint_id"
}
}
}
}Claude Code
claude mcp add mindbox -e MINDBOX_API_KEY=ваш_ключ -e MINDBOX_ENDPOINT_ID=ваш_endpoint_id -- npx -y @theyahia/mindbox-mcpStreamable HTTP
MINDBOX_API_KEY=ваш_ключ MINDBOX_ENDPOINT_ID=ваш_endpoint_id npx @theyahia/mindbox-mcp --http
# MCP endpoint: http://127.0.0.1:3000/mcp
# Health check: http://127.0.0.1:3000/healthBy default, the server listens on 127.0.0.1 (see the Security section). Port — via PORT, host — via HOST.
Docker (HTTP)
docker build -t mindbox-mcp .
docker run --rm -p 3000:3000 \
-e MINDBOX_API_KEY=ваш_ключ -e MINDBOX_ENDPOINT_ID=ваш_endpoint_id \
-e MINDBOX_HTTP_ALLOWED_HOSTS=ваш-домен:3000 \
mindbox-mcpThe container listens on 0.0.0.0:3000. Behind a reverse proxy, add your host to MINDBOX_HTTP_ALLOWED_HOSTS (DNS-rebinding protection).
Smithery
The smithery.yaml file is included. Required parameters: MINDBOX_API_KEY, MINDBOX_ENDPOINT_ID.
Authorization and endpoints
Authorization header: Authorization: Mindbox secretKey="...".
Requests go to POST https://api.mindbox.ru/v3/operations/{sync|async}?endpointId=…&operation=…:
sync — operations with a response (customer profile, segments, order creation, product list). Used by default.
async — fire-and-forget events (views, cart additions). Available for
run_operationviamode: "async".
System operation names (
operation) are configured in each Mindbox project — they are not universal built-in methods. Defaults likeWebsite.GetCustomerInfoare merely a common convention; the project administrator must create operations with matching system names, otherwise Mindbox will returnProtocolError.
Environment variables
Variable | Required | Description |
| yes | Mindbox API secret key (also accepts |
| yes | Integration point ID (endpointId) |
| no | HTTP server port (default 3000) |
| no | HTTP bind host (default 127.0.0.1) |
| no | Bearer token for protecting |
| no | Additional allowed |
| no | Additional allowed |
| no |
|
| no | Number of retries on 429/5xx/timeout (default 3) |
| no | Base backoff delay in ms (default 500) |
| no | Timeout for a single attempt in ms (default 15000) |
Tools (6)
Tool | Description |
| Get a customer profile by email/phone/ID |
| Create an order linked to a customer |
| Get customer segments |
| Get a product list |
| Update a customer profile |
| ⚠️ Run an arbitrary Mindbox API operation (see Security) |
Security
run_operationexecutes an ARBITRARY Mindbox operation under your secret key and can modify data. In untrusted agent scenarios, this is a prompt-injection vector. Calls are logged to stderr; to disable entirely —MINDBOX_ALLOW_RAW=0.HTTP transport has no built-in authentication other than the optional
MINDBOX_HTTP_TOKEN. The server listens on127.0.0.1by default, DNS-rebinding protection is enabled (validation ofHost/Origin), CORS*is allowed only on/health. For remote access, place it behind an authenticating reverse proxy and do not expose the port externally unless necessary.The secret key is used only server-side and must never reach the browser.
Skills
Skill | Description | Trigger |
| Search for a customer in Mindbox | "Find a customer in Mindbox" |
| Segment statistics | "Segment statistics" |
Example requests
Найди клиента с email user@example.com
Создай заказ для клиента с телефоном +7900...
Какие сегменты у клиента user@example.com?
Покажи список товаров
Обнови имя клиента с ID 12345
Выполни операцию Custom.GetData с телом {"key": "value"}Troubleshooting
Symptom | Cause and solution |
|
|
| Invalid |
| The system operation name is not configured in the Mindbox project. Create an operation with a matching |
|
|
HTTP | DNS-rebinding protection triggered. Add your host to |
Development
npm install # установка + сборка (prepare)
npm run dev # stdio
npm run dev:http # HTTP на порту 3000
npm test # Vitest
npm run typecheck # tsc --noEmit
npm run lint # ESLintSee CONTRIBUTING.md.
License
MIT
Available Tools
6 toolscreate_orderB
Создание заказа в Mindbox с привязкой к клиенту.
Inputs: lines (required), order_id (required), total_price (required), operation, +3 more.
get_customerA
Получение профиля клиента из Mindbox по email, телефону или ID.
Inputs: email, phone, operation, external_id.
get_product_listC
Получение списка товаров из Mindbox.
Inputs: page, operation, page_size.
get_segmentsC
Получение сегментов клиента в Mindbox.
Inputs: email, phone, operation, external_id.
run_operationA
⚠️ ОПАСНО: выполнение ПРОИЗВОЛЬНОЙ операции Mindbox API под секретным ключом. Может изменять данные. Отключается через MINDBOX_ALLOW_RAW=0.
Inputs: operation (required), body, mode.
update_customerC
Обновление профиля клиента в Mindbox.
Inputs: email, phone, last_name, operation, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct function: customer profile retrieval/update, order creation, segments lookup, product list, and a raw operation escape hatch. No two tools seem to overlap, and the dangerous run_operation is clearly separated by its warning.
All tools follow a consistent snake_case verb_noun pattern (get_customer, create_order, get_segments, get_product_list, update_customer, run_operation). This is predictable and easy for an agent to parse.
With 6 tools, the set is well-scoped for a CRM/ecommerce integration. It covers core customer and order operations without unnecessary bloat, making it easy to navigate.
The set covers customer retrieval/update, order creation, segments, and products, but lacks explicit order retrieval or listing, and there is no direct customer creation. However, the run_operation tool provides a raw API fallback, mitigating some gaps, though it introduces risk.
Maintenance
Related MCP Connectors
Authenticated MCP access to WebMoney wallets, transactions, messages and invoices.
Mailchimp MCP Pack — manage audiences, campaigns, and members via Mailchimp Marketing API.
Send transactional email and manage domains, audiences, and broadcasts from any MCP client.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Related MCP Servers
- AlicenseCqualityBmaintenanceMCP server for MoySklad (МойСклад) warehouse and CRM management API. 21 tools covering the full order lifecycle: products, stock, counterparties, customer orders, shipments, supplies, warehouses, organizations, reports, and webhooks.6070 npm10MIT
- AlicenseNot gradedqualityDmaintenanceProvides comprehensive access to the Constant Contact API v3 for email marketing, campaign management, contact management, analytics, and automation through MCP tools.2MIT
- AlicenseNot gradedqualityCmaintenanceEnables managing Ozon Seller and Performance APIs through MCP, covering products, stocks, prices, orders, finance, analytics, advertising, reviews, and chat operations.MIT
- AlicenseAqualityCmaintenanceEnables managing Kontur.Elba data through the official Public API, including organizations, bank accounts, counterparties, products, documents, invoices, and public links via MCP tools.410 npmMIT