@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 protection

• Skills for automating common scenarios

Related MCP server: MoySklad 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-mcp

Streamable 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/health

By 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-mcp

The 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_operation via mode: "async".

System operation names (operation) are configured in each Mindbox project — they are not universal built-in methods. Defaults like Website.GetCustomerInfo are merely a common convention; the project administrator must create operations with matching system names, otherwise Mindbox will return ProtocolError.

Environment variables

Tools (6)

Security

• run_operation executes 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 on 127.0.0.1 by default, DNS-rebinding protection is enabled (validation of Host/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

Example requests

Найди клиента с email user@example.com
Создай заказ для клиента с телефоном +7900...
Какие сегменты у клиента user@example.com?
Покажи список товаров
Обнови имя клиента с ID 12345
Выполни операцию Custom.GetData с телом {"key": "value"}

Troubleshooting

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         # ESLint

See CONTRIBUTING.md.

License

MIT