# mindbox-mcp [Health: Active] **Category:** 💻 Developer Tools **Repository:** https://github.com/theYahia/mindbox-mcp **GitHub Stars:** 3 **Views:** 0 **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. ## 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"] } } ``` ## Documentation & README # MCP-сервер для Mindbox CDP — профили клиентов, заказы и сегменты через ИИ Если вы искали, как подключить Mindbox к нейросети, поднять профиль клиента или проверить сегмент без выгрузки в Excel — это оно. 6 инструментов: профили и подписки, заказы, сегменты, списки товаров и произвольные операции Mindbox API. Спрашиваете «что покупал клиент с этим email» — получаете историю, а не тикет в поддержку. [![npm](https://img.shields.io/npm/v/@theyahia/mindbox-mcp)](https://www.npmjs.com/package/@theyahia/mindbox-mcp) [![CI](https://github.com/theYahia/mindbox-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/theYahia/mindbox-mcp/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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 user@example.com Создай заказ для клиента с телефоном +7900... Какие сегменты у клиента user@example.com? Покажи список товаров Обнови имя клиента с 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 # stdio npm run dev:http # HTTP на порту 3000 npm test # Vitest npm run typecheck # tsc --noEmit npm run lint # ESLint ``` См. [CONTRIBUTING.md](https://github.com/theYahia/mindbox-mcp/blob/HEAD/CONTRIBUTING.md). ## Лицензия MIT --- Часть [WWmcp](https://github.com/theYahia/WWmcp) · Telegram: [@vhodvai](https://t.me/vhodvai)