Mindbox Mcp

io.github.theYahiaPublished by GitHub account theYahiav1.0.1Updated Oct 28, 2026

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

VerifiedSTDIODesktop onlyData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

MCP server for the Mindbox CDP API that lets an assistant look up customer profiles, orders, segments and product lists, and run Mindbox operations.

What you can do
  • Look up a customer profile by email, phone or ID, and update profile fields
  • Create orders linked to a customer
  • Retrieve a customer's segments and fetch product lists
  • Run an arbitrary Mindbox API operation, in sync or async mode
  • Use bundled skills for customer search and segment statistics
When to use it
Useful when you work with a Mindbox customer data platform and want an assistant to answer questions about customers, orders and segments, or to create orders and update profiles, without exporting data to spreadsheets.
Requirements
Runs locally as an npm package (npx @theyahia/mindbox-mcp) over stdio, or as a Streamable HTTP server with the --http flag. Needs a Mindbox secret key and an endpoint ID; the README uses MINDBOX_API_KEY and MINDBOX_ENDPOINT_ID, and the manifest names MINDBOX_SECRET_KEY. Network access to the Mindbox API is required. Operation system names must already exist in the Mindbox project.
Before you install
The secret key is sent to the Mindbox API and must stay server-side. The run_operation tool executes any Mindbox operation under that key and can change data; the README calls it a prompt-injection vector in untrusted agent scenarios and offers MINDBOX_ALLOW_RAW=0 to disable it. create_order and update_customer write data. The HTTP transport has no built-in authentication apart from the optional MINDBOX_HTTP_TOKEN, so keep it on localhost or behind an authenticating proxy.

Installation

In SourceWeft

  1. Open Mindbox Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

MCP-сервер для Mindbox CDP — профили клиентов, заказы и сегменты через ИИ

Если вы искали, как подключить Mindbox к нейросети, поднять профиль клиента или проверить сегмент без выгрузки в Excel — это оно. 6 инструментов: профили и подписки, заказы, сегменты, списки товаров и произвольные операции Mindbox API. Спрашиваете «что покупал клиент с этим email» — получаете историю, а не тикет в поддержку.

[npm] [CI] [License: MIT]

Возможности

  • 6 инструментов для работы с Mindbox API
  • Транспорт: stdio (по умолчанию) и Streamable HTTP (--http)
  • Совместимость с Claude Desktop, Claude Code, Cursor, Smithery
  • Повторы с backoff и идемпотентностью (transactionId), защита HTTP-транспорта
  • Skills для автоматизации типовых сценариев

Установка

Claude Desktop

json
{  "mcpServers": {    "mindbox": {      "command": "npx",      "args": ["-y", "@theyahia/mindbox-mcp"],      "env": {        "MINDBOX_API_KEY": "ваш_ключ",        "MINDBOX_ENDPOINT_ID": "ваш_endpoint_id"      }    }  }}

Claude Code

bash
claude mcp add mindbox -e MINDBOX_API_KEY=ваш_ключ -e MINDBOX_ENDPOINT_ID=ваш_endpoint_id -- npx -y @theyahia/mindbox-mcp

Streamable HTTP

bash
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

По умолчанию сервер слушает 127.0.0.1 (см. раздел Безопасность). Порт — через PORT, хост — через HOST.

Docker (HTTP)

bash
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

Контейнер слушает 0.0.0.0:3000. За обратным прокси добавьте свой хост в MINDBOX_HTTP_ALLOWED_HOSTS (DNS-rebinding защита).

Smithery

Файл smithery.yaml включён. Требуемые параметры: MINDBOX_API_KEY, MINDBOX_ENDPOINT_ID.

Авторизация и эндпоинты

Заголовок авторизации: Authorization: Mindbox secretKey="...".

Запросы идут на POST https://api.mindbox.ru/v3/operations/{sync|async}?endpointId=…&operation=…:

  • sync — операции с ответом (профиль клиента, сегменты, создание заказа, список товаров). Используется по умолчанию.
  • async — fire-and-forget события (просмотры, добавления в корзину). Доступно для run_operation через mode: "async".

Системные имена операций (operation) настраиваются в каждом проекте Mindbox — это не универсальные встроенные методы. Дефолты вроде Website.GetCustomerInfo — лишь распространённая конвенция; администратор проекта должен создать операции с совпадающими системными именами, иначе Mindbox вернёт ProtocolError.

Переменные окружения

ПеременнаяОбязательнаОписание
MINDBOX_API_KEYдаСекретный ключ API Mindbox (также принимается MINDBOX_SECRET_KEY)
MINDBOX_ENDPOINT_IDдаID точки интеграции (endpointId)
PORTнетПорт HTTP-сервера (по умолчанию 3000)
HOSTнетХост привязки HTTP (по умолчанию 127.0.0.1)
MINDBOX_HTTP_TOKENнетBearer-токен для защиты /mcp (если задан — обязателен в запросах)
MINDBOX_HTTP_ALLOWED_HOSTSнетДоп. разрешённые Host (через запятую) для DNS-rebinding защиты
MINDBOX_HTTP_ALLOWED_ORIGINSнетДоп. разрешённые Origin (через запятую)
MINDBOX_ALLOW_RAWнет0/false/off/no отключает run_operation
MINDBOX_MAX_RETRIESнетЧисло повторов при 429/5xx/таймауте (по умолчанию 3)
MINDBOX_RETRY_BASE_MSнетБазовая задержка backoff в мс (по умолчанию 500)
MINDBOX_TIMEOUT_MSнетТаймаут одной попытки в мс (по умолчанию 15000)

Инструменты (6)

ИнструментОписание
get_customerПолучение профиля клиента по email/телефону/ID
create_orderСоздание заказа с привязкой к клиенту
get_segmentsПолучение сегментов клиента
get_product_listПолучение списка товаров
update_customerОбновление профиля клиента
run_operation⚠️ Выполнение произвольной операции Mindbox API (см. Безопасность)

Безопасность

  • run_operation выполняет ПРОИЗВОЛЬНУЮ операцию Mindbox под вашим секретным ключом и может изменять данные. В недоверенных агентских сценариях это вектор prompt-injection. Вызовы логируются в stderr; полностью отключить — MINDBOX_ALLOW_RAW=0.
  • HTTP-транспорт не имеет встроенной аутентификации, кроме опционального MINDBOX_HTTP_TOKEN. Сервер по умолчанию слушает 127.0.0.1, включена DNS-rebinding защита (валидация Host/Origin), CORS * разрешён только на /health. Для удалённого доступа ставьте за аутентифицирующим обратным прокси и не открывайте порт наружу без необходимости.
  • Секретный ключ используется только на стороне сервера и никогда не должен попадать в браузер.

Skills

СкиллОписаниеТриггер
skill-customer-searchПоиск клиента в Mindbox"Найди клиента в Mindbox"
skill-segment-statsСтатистика сегментов"Статистика сегментов"

Примеры запросов

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

Troubleshooting

СимптомПричина и решение
Переменная окружения MINDBOX_API_KEY … обязательнаНе заданы MINDBOX_API_KEY/MINDBOX_ENDPOINT_ID. Сервер стартует и отдаёт список инструментов без них, но любой вызов требует ключи.
Mindbox HTTP 401/403Неверный secretKey или endpointId, либо ключ не имеет прав на операцию.
Статус: ProtocolError / операция не найденаСистемное имя операции не настроено в проекте Mindbox. Создайте операцию с совпадающим systemName или передайте корректный operation.
Mindbox: таймаут запросаПревышен MINDBOX_TIMEOUT_MS (15с по умолчанию). Сервер уже делает повторы; увеличьте таймаут/повторы при необходимости.
HTTP 403 Invalid Host headerСработала DNS-rebinding защита. Добавьте свой хост в MINDBOX_HTTP_ALLOWED_HOSTS.

Разработка

bash
npm install          # установка + сборка (prepare)npm run dev          # stdionpm run dev:http     # HTTP на порту 3000npm test             # Vitestnpm run typecheck    # tsc --noEmitnpm run lint         # ESLint

См. CONTRIBUTING.md.

Лицензия

MIT

Часть WWmcp · Telegram: @vhodvai

Source: README.md at commit 7ebe297

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts