Mindbox MCP

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

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

Возможности

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

Установка

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

По умолчанию сервер слушает 127.0.0.1 (см. раздел Безопасность). Порт — через PORT, хост — через 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

Контейнер слушает 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.

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

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

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

• `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

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

Найди клиента с email user@example.com

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

Troubleshooting

Разработка

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

См. CONTRIBUTING.md.

Лицензия

MIT

---

Часть WWmcp · Telegram: @vhodvai