Skip to main content
Glama

@theyahia/mindbox-mcp

MCP server for the Mindbox CDP API — customer profiles, orders, segments, product lists, and arbitrary operations.

npm CI License: MIT

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: 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-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

Variable

Required

Description

MINDBOX_API_KEY

yes

Mindbox API secret key (also accepts MINDBOX_SECRET_KEY)

MINDBOX_ENDPOINT_ID

yes

Integration point ID (endpointId)

PORT

no

HTTP server port (default 3000)

HOST

no

HTTP bind host (default 127.0.0.1)

MINDBOX_HTTP_TOKEN

no

Bearer token for protecting /mcp (if set — required in requests)

MINDBOX_HTTP_ALLOWED_HOSTS

no

Additional allowed Host values (comma-separated) for DNS-rebinding protection

MINDBOX_HTTP_ALLOWED_ORIGINS

no

Additional allowed Origin values (comma-separated)

MINDBOX_ALLOW_RAW

no

0/false/off/no disables run_operation

MINDBOX_MAX_RETRIES

no

Number of retries on 429/5xx/timeout (default 3)

MINDBOX_RETRY_BASE_MS

no

Base backoff delay in ms (default 500)

MINDBOX_TIMEOUT_MS

no

Timeout for a single attempt in ms (default 15000)

Tools (6)

Tool

Description

get_customer

Get a customer profile by email/phone/ID

create_order

Create an order linked to a customer

get_segments

Get customer segments

get_product_list

Get a product list

update_customer

Update a customer profile

run_operation

⚠️ Run an arbitrary Mindbox API operation (see Security)

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

Skill

Description

Trigger

skill-customer-search

Search for a customer in Mindbox

"Find a customer in Mindbox"

skill-segment-stats

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

Environment variable MINDBOX_API_KEY … is required

MINDBOX_API_KEY/MINDBOX_ENDPOINT_ID are not set. The server starts and returns the tool list without them, but any call requires the keys.

Mindbox HTTP 401/403

Invalid secretKey or endpointId, or the key lacks permissions for the operation.

Status: ProtocolError / operation not found

The system operation name is not configured in the Mindbox project. Create an operation with a matching systemName or pass a correct operation.

Mindbox: request timeout

MINDBOX_TIMEOUT_MS exceeded (15s by default). The server already retries; increase the timeout/retries if needed.

HTTP 403 Invalid Host header

DNS-rebinding protection triggered. Add your host to MINDBOX_HTTP_ALLOWED_HOSTS.

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

Available Tools

6 tools
create_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

    A3.6/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      MCP 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.
      60
      70 npm
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides comprehensive access to the Constant Contact API v3 for email marketing, campaign management, contact management, analytics, and automation through MCP tools.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables managing Kontur.Elba data through the official Public API, including organizations, bank accounts, counterparties, products, documents, invoices, and public links via MCP tools.
      4
      10 npm
      MIT