@theyahia/mindbox-mcp

用于 Mindbox CDP API 的 MCP 服务器 — 客户档案、订单、细分、商品列表和任意操作。

功能特性

• 6 个用于 Mindbox API 的工具

• 传输方式：stdio（默认）和 Streamable HTTP（--http）

• 兼容 Claude Desktop、Claude Code、Cursor、Smithery

• 带退避重试和幂等性（transactionId）的重试机制，HTTP 传输保护

• 用于自动化典型场景的 Skills

Related MCP server: MoySklad MCP Server

安装

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。

环境变量

工具（6）

安全

• run_operation 使用您的密钥执行 Mindbox 的任意操作，可能修改数据。在不受信任的代理场景中，这是 prompt-injection 的载体。调用会记录到 stderr；完全禁用 — MINDBOX_ALLOW_RAW=0。

• HTTP 传输没有内置认证，除了可选的 MINDBOX_HTTP_TOKEN。服务器默认监听 127.0.0.1，已启用 DNS 重绑定防护（Host/Origin 验证），CORS * 仅允许在 /health 上。对于远程访问，请放在带认证的反向代理后面，非必要不要对外暴露端口。

• 密钥仅在服务器端使用，绝不应进入浏览器。

Skills

请求示例

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

故障排查

开发

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