@theyahia/mindbox-mcp

Mindbox CDP API 用のMCPサーバー — 顧客プロフィール、注文、セグメント、商品リスト、および任意の操作。

機能

• Mindbox API を操作するための6つのツール

• トランスポート: stdio（デフォルト）および Streamable HTTP（--http）

• Claude Desktop、Claude Code、Cursor、Smithery との互換性

• backoff と冪等性（transactionId）を備えたリトライ、HTTPトランスポートの保護

• 一般的なシナリオを自動化するためのスキル

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 をリッスンします。リバースプロキシの背後に配置する場合は、DNSリバインディング保護のため、MINDBOX_HTTP_ALLOWED_HOSTS に自分のホストを追加してください。

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 の 任意の 操作を実行し、データを変更する可能性があります。信頼できないエージェントシナリオでは、これはプロンプトインジェクションのベクトルとなります。呼び出しは stderr にログ記録されます。完全に無効化するには MINDBOX_ALLOW_RAW=0 を設定します。

• HTTPトランスポート には、オプションの MINDBOX_HTTP_TOKEN を除き、組み込みの認証はありません。サーバーはデフォルトで 127.0.0.1 をリッスンし、DNSリバインディング保護（Host/Origin の検証）が有効で、CORS * は /health でのみ許可されています。リモートアクセスには、認証付きリバースプロキシの背後に配置し、必要がない限りポートを外部に公開しないでください。

• シークレットキーはサーバー側でのみ使用され、ブラウザに渡してはなりません。

スキル

リクエスト例

Найди клиента с 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