{
  "markdown": "# MCP-сервер для Mindbox CDP — профили клиентов, заказы и сегменты через ИИ\n\nЕсли вы искали, как подключить Mindbox к нейросети, поднять профиль клиента или проверить сегмент без выгрузки в Excel — это оно. 6 инструментов: профили и подписки, заказы, сегменты, списки товаров и произвольные операции Mindbox API. Спрашиваете «что покупал клиент с этим email» — получаете историю, а не тикет в поддержку.\n\n[![npm](https://img.shields.io/npm/v/@theyahia/mindbox-mcp)](https://www.npmjs.com/package/@theyahia/mindbox-mcp)\n[![CI](https://github.com/theYahia/mindbox-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/theYahia/mindbox-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Возможности\n\n- 6 инструментов для работы с Mindbox API\n- Транспорт: stdio (по умолчанию) и Streamable HTTP (`--http`)\n- Совместимость с Claude Desktop, Claude Code, Cursor, Smithery\n- Повторы с backoff и идемпотентностью (`transactionId`), защита HTTP-транспорта\n- Skills для автоматизации типовых сценариев\n\n## Установка\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"mindbox\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@theyahia/mindbox-mcp\"],\n      \"env\": {\n        \"MINDBOX_API_KEY\": \"ваш_ключ\",\n        \"MINDBOX_ENDPOINT_ID\": \"ваш_endpoint_id\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add mindbox -e MINDBOX_API_KEY=ваш_ключ -e MINDBOX_ENDPOINT_ID=ваш_endpoint_id -- npx -y @theyahia/mindbox-mcp\n```\n\n### Streamable HTTP\n\n```bash\nMINDBOX_API_KEY=ваш_ключ MINDBOX_ENDPOINT_ID=ваш_endpoint_id npx @theyahia/mindbox-mcp --http\n# MCP endpoint: http://127.0.0.1:3000/mcp\n# Health check: http://127.0.0.1:3000/health\n```\n\nПо умолчанию сервер слушает `127.0.0.1` (см. раздел [Безопасность](#безопасность)). Порт — через `PORT`, хост — через `HOST`.\n\n### Docker (HTTP)\n\n```bash\ndocker build -t mindbox-mcp .\ndocker run --rm -p 3000:3000 \\\n  -e MINDBOX_API_KEY=ваш_ключ -e MINDBOX_ENDPOINT_ID=ваш_endpoint_id \\\n  -e MINDBOX_HTTP_ALLOWED_HOSTS=ваш-домен:3000 \\\n  mindbox-mcp\n```\n\nКонтейнер слушает `0.0.0.0:3000`. За обратным прокси добавьте свой хост в `MINDBOX_HTTP_ALLOWED_HOSTS` (DNS-rebinding защита).\n\n### Smithery\n\nФайл `smithery.yaml` включён. Требуемые параметры: `MINDBOX_API_KEY`, `MINDBOX_ENDPOINT_ID`.\n\n## Авторизация и эндпоинты\n\nЗаголовок авторизации: `Authorization: Mindbox secretKey=\"...\"`.\n\nЗапросы идут на `POST https://api.mindbox.ru/v3/operations/{sync|async}?endpointId=…&operation=…`:\n\n- **sync** — операции с ответом (профиль клиента, сегменты, создание заказа, список товаров). Используется по умолчанию.\n- **async** — fire-and-forget события (просмотры, добавления в корзину). Доступно для `run_operation` через `mode: \"async\"`.\n\n> Системные имена операций (`operation`) настраиваются **в каждом проекте Mindbox** — это не универсальные встроенные методы. Дефолты вроде `Website.GetCustomerInfo` — лишь распространённая конвенция; администратор проекта должен создать операции с совпадающими системными именами, иначе Mindbox вернёт `ProtocolError`.\n\n## Переменные окружения\n\n| Переменная                     | Обязательна | Описание                                                            |\n| ------------------------------ | :---------: | ------------------------------------------------------------------- |\n| `MINDBOX_API_KEY`              |     да      | Секретный ключ API Mindbox (также принимается `MINDBOX_SECRET_KEY`) |\n| `MINDBOX_ENDPOINT_ID`          |     да      | ID точки интеграции (endpointId)                                    |\n| `PORT`                         |     нет     | Порт HTTP-сервера (по умолчанию 3000)                               |\n| `HOST`                         |     нет     | Хост привязки HTTP (по умолчанию 127.0.0.1)                         |\n| `MINDBOX_HTTP_TOKEN`           |     нет     | Bearer-токен для защиты `/mcp` (если задан — обязателен в запросах) |\n| `MINDBOX_HTTP_ALLOWED_HOSTS`   |     нет     | Доп. разрешённые `Host` (через запятую) для DNS-rebinding защиты    |\n| `MINDBOX_HTTP_ALLOWED_ORIGINS` |     нет     | Доп. разрешённые `Origin` (через запятую)                           |\n| `MINDBOX_ALLOW_RAW`            |     нет     | `0`/`false`/`off`/`no` отключает `run_operation`                    |\n| `MINDBOX_MAX_RETRIES`          |     нет     | Число повторов при 429/5xx/таймауте (по умолчанию 3)                |\n| `MINDBOX_RETRY_BASE_MS`        |     нет     | Базовая задержка backoff в мс (по умолчанию 500)                    |\n| `MINDBOX_TIMEOUT_MS`           |     нет     | Таймаут одной попытки в мс (по умолчанию 15000)                     |\n\n## Инструменты (6)\n\n| Инструмент         | Описание                                                                            |\n| ------------------ | ----------------------------------------------------------------------------------- |\n| `get_customer`     | Получение профиля клиента по email/телефону/ID                                      |\n| `create_order`     | Создание заказа с привязкой к клиенту                                               |\n| `get_segments`     | Получение сегментов клиента                                                         |\n| `get_product_list` | Получение списка товаров                                                            |\n| `update_customer`  | Обновление профиля клиента                                                          |\n| `run_operation`    | ⚠️ Выполнение произвольной операции Mindbox API (см. [Безопасность](#безопасность)) |\n\n## Безопасность\n\n- **`run_operation`** выполняет ПРОИЗВОЛЬНУЮ операцию Mindbox под вашим секретным ключом и может изменять данные. В недоверенных агентских сценариях это вектор prompt-injection. Вызовы логируются в stderr; полностью отключить — `MINDBOX_ALLOW_RAW=0`.\n- **HTTP-транспорт** не имеет встроенной аутентификации, кроме опционального `MINDBOX_HTTP_TOKEN`. Сервер по умолчанию слушает `127.0.0.1`, включена DNS-rebinding защита (валидация `Host`/`Origin`), CORS `*` разрешён только на `/health`. Для удалённого доступа ставьте за аутентифицирующим обратным прокси и не открывайте порт наружу без необходимости.\n- Секретный ключ используется только на стороне сервера и никогда не должен попадать в браузер.\n\n## Skills\n\n| Скилл                   | Описание                | Триггер                   |\n| ----------------------- | ----------------------- | ------------------------- |\n| `skill-customer-search` | Поиск клиента в Mindbox | \"Найди клиента в Mindbox\" |\n| `skill-segment-stats`   | Статистика сегментов    | \"Статистика сегментов\"    |\n\n## Примеры запросов\n\n```\nНайди клиента с email user@example.com\nСоздай заказ для клиента с телефоном +7900...\nКакие сегменты у клиента user@example.com?\nПокажи список товаров\nОбнови имя клиента с ID 12345\nВыполни операцию Custom.GetData с телом {\"key\": \"value\"}\n```\n\n## Troubleshooting\n\n| Симптом                                              | Причина и решение                                                                                                                         |\n| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `Переменная окружения MINDBOX_API_KEY … обязательна` | Не заданы `MINDBOX_API_KEY`/`MINDBOX_ENDPOINT_ID`. Сервер стартует и отдаёт список инструментов без них, но любой вызов требует ключи.    |\n| `Mindbox HTTP 401/403`                               | Неверный `secretKey` или `endpointId`, либо ключ не имеет прав на операцию.                                                               |\n| `Статус: ProtocolError` / операция не найдена        | Системное имя операции не настроено в проекте Mindbox. Создайте операцию с совпадающим `systemName` или передайте корректный `operation`. |\n| `Mindbox: таймаут запроса`                           | Превышен `MINDBOX_TIMEOUT_MS` (15с по умолчанию). Сервер уже делает повторы; увеличьте таймаут/повторы при необходимости.                 |\n| HTTP `403 Invalid Host header`                       | Сработала DNS-rebinding защита. Добавьте свой хост в `MINDBOX_HTTP_ALLOWED_HOSTS`.                                                        |\n\n## Разработка\n\n```bash\nnpm install          # установка + сборка (prepare)\nnpm run dev          # stdio\nnpm run dev:http     # HTTP на порту 3000\nnpm test             # Vitest\nnpm run typecheck    # tsc --noEmit\nnpm run lint         # ESLint\n```\n\nСм. [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Лицензия\n\nMIT\n\n---\n\nЧасть [WWmcp](https://github.com/theYahia/WWmcp) · Telegram: [@vhodvai](https://t.me/vhodvai)\n",
  "bytes": 8685,
  "sha": "aea4573efe9b7370c28bb41d7a36eac005eb2e2a662c7b7b0dc4d3afe06c6f7f",
  "repo_slug": "theyahia/mindbox-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_theyahia_mindbox_mcp_34cb23a0/readme"
}