# mindbox-mcp [Health: Active]

**Category:** 👤 Customer Data Platforms  
**Repository:** https://github.com/theYahia/mindbox-mcp  
**GitHub Stars:** 4  
**npm Downloads (last month):** 125  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mindbox-mcp

## Description
MCP server for Mindbox CDP API — customer profiles, orders, segments. 3 tools.

## Tools
Capabilities this server exposes over MCP:

- **get_customer** — Получение профиля клиента из Mindbox по email, телефону или ID.
- **create_order** — Создание заказа в Mindbox с привязкой к клиенту.
- **get_segments** — Получение сегментов клиента в Mindbox.
- **get_product_list** — Получение списка товаров из Mindbox.
- **update_customer** — Обновление профиля клиента в Mindbox.
- **run_operation** — ⚠️ ОПАСНО: выполнение ПРОИЗВОЛЬНОЙ операции Mindbox API под секретным ключом. Может изменять данные. Отключается через MINDBOX_ALLOW_RAW=0.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mindbox-mcp": {
    "command": "npx",
    "args": ["-y","@theyahia/mindbox-mcp"],
    "env": {
      "MINDBOX_API_KEY": "",
      "MINDBOX_ENDPOINT_ID": ""
    }
  }
}
```

**Requires environment variables:** `MINDBOX_API_KEY`, `MINDBOX_ENDPOINT_ID` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What mindbox-mcp MCP server does

The mindbox-mcp MCP server gives an AI client access to selected Mindbox CDP actions without requiring a separate export or custom chat integration. Its tool set covers customer lookup, customer updates, order creation, segment retrieval, product-list retrieval, and execution of an arbitrary Mindbox operation.

Customer lookup accepts an email address, phone number, or customer ID. Orders can be associated with an existing customer, and profile updates can modify customer data. Segment and product tools retrieve information from the connected Mindbox project. The raw operation tool accepts a Mindbox operation and request body, which makes it useful for project-specific APIs that are not represented by the dedicated tools.

Two included skills describe common workflows: searching for a customer and obtaining segment statistics.

## How it works

The server authenticates requests with a Mindbox secret key and sends them to Mindbox’s v3 operation endpoints. Operations are normally synchronous, so tools can return a response such as a profile or segment result. The raw operation tool can also use asynchronous mode for fire-and-forget events such as views or cart additions.

Mindbox operation names are configured per project. Names shown in examples are conventions rather than universal built-in methods, so the matching operation must exist in the target project. If it does not, Mindbox can return a protocol error.

Requests that receive rate-limit responses, server errors, or timeouts are retried with backoff. The implementation also supports transaction IDs for idempotency. For HTTP use, the default endpoint is `/mcp` on port 3000, with a `/health` endpoint for health checks.

## Setup and configuration

For local stdio use, run the npm package with `npx` and provide `MINDBOX_API_KEY` and `MINDBOX_ENDPOINT_ID`. Claude Desktop and Claude Code examples in the README show these values in their MCP configuration. The package can also run with `--http`; `PORT` and `HOST` control the listener, which defaults to `127.0.0.1:3000`.

Docker deployment is supported. The container listens on port 3000 and can receive the same Mindbox credentials through environment variables. HTTP deployments may set `MINDBOX_HTTP_TOKEN`, allowed hosts, and allowed origins. Retry count, base backoff, and request timeout are configurable with `MINDBOX_MAX_RETRIES`, `MINDBOX_RETRY_BASE_MS`, and `MINDBOX_TIMEOUT_MS`.

## Tools and capabilities

The six tools are:

- `get_customer` searches for a customer by email, phone, or ID.
- `create_order` creates an order linked to a customer.
- `get_segments` retrieves a customer’s segments.
- `get_product_list` retrieves a product list.
- `update_customer` changes a customer profile.
- `run_operation` sends a custom Mindbox operation and can use asynchronous mode.

The mindbox-mcp MCP server also includes the `skill-customer-search` and `skill-segment-stats` workflow skills for the triggers documented in the repository.

## Limitations and notes

The raw operation tool can perform data-changing actions under the configured secret key. Disable it by setting `MINDBOX_ALLOW_RAW` to `0`, `false`, `off`, or `no` when agents should not have arbitrary operation access. Calls to this tool are written to stderr.

HTTP transport does not provide built-in authentication unless `MINDBOX_HTTP_TOKEN` is configured. Keep the service behind an authenticating reverse proxy for remote access, and avoid exposing the port unnecessarily. Host and origin checks provide DNS-rebinding protection, while the secret key remains server-side.

The server may start without credentials and list its tools, but tool calls require the Mindbox API key and endpoint ID. A valid key alone is not sufficient if it lacks permission for the requested operation or if the project has not configured the required operation name.

_Full upstream README: https://allmcps.com/mcp/mindbox-mcp/readme_