mindbox-mcp

Mindbox CDP MCP 服务 — 通过 AI 查询客户资料、订单和细分

如果你想知道如何将 Mindbox 接入神经网络、查询客户资料，或在不导出到 Excel 的情况下检查细分，这就是你要找的工具。包含 6 个工具：客户资料和订阅、订单、细分、商品列表，以及 Mindbox API 的任意操作。询问“这个邮箱对应的客户买过什么”，即可获得购买历史，而不必向支持团队提交工单。

功能

• 提供 6 个用于调用 Mindbox API 的工具
• 传输方式：stdio（默认）和 Streamable HTTP（--http）
• 兼容 Claude Desktop、Claude Code、Cursor 和 Smithery
• 支持带退避和幂等性（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 重绑定防护）。

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 — 即发即弃事件（浏览、添加到购物车）。run_operation 可通过 mode: "async" 使用此模式。

系统操作名（operation）需要在每个 Mindbox 项目中单独配置，并非通用的内置方法。Website.GetCustomerInfo 等默认值只是常见约定；项目管理员必须创建系统名匹配的操作，否则 Mindbox 会返回 ProtocolError。

环境变量

变量	必需	描述
MINDBOX_API_KEY	是	Mindbox API 密钥（也接受 MINDBOX_SECRET_KEY）
MINDBOX_ENDPOINT_ID	是	集成端点 ID（endpointId）
PORT	否	HTTP 服务端口（默认 3000）
HOST	否	HTTP 绑定主机（默认 127.0.0.1）
MINDBOX_HTTP_TOKEN	否	用于保护 /mcp 的 Bearer 令牌（如果设置，则请求中必须提供）
MINDBOX_HTTP_ALLOWED_HOSTS	否	DNS 重绑定防护允许的额外 Host（以逗号分隔）
MINDBOX_HTTP_ALLOWED_ORIGINS	否	额外允许的 Origin（以逗号分隔）
MINDBOX_ALLOW_RAW	否	设置为 0/false/off/no 可禁用 run_operation
MINDBOX_MAX_RETRIES	否	发生 429/5xx/超时时的重试次数（默认 3）
MINDBOX_RETRY_BASE_MS	否	退避的基础延迟（毫秒，默认 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.

Разработка

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