mindbox-mcp

Mindbox CDP 用 MCP サーバー — AI で顧客プロフィール、注文、セグメントを確認

Mindbox をニューラルネットワークに接続する方法を調べていた方、顧客プロフィールを取得したい方、Excel にエクスポートせずにセグメントを確認したい方にぴったりです。6 つのツールで、プロフィールと購読、注文、セグメント、商品リスト、任意の Mindbox API 操作に対応します。「このメールアドレスの顧客は何を購入しましたか」と尋ねれば、サポートへの問い合わせではなく、購入履歴が返ってきます。

機能

• Mindbox API を操作する 6 つのツール
• トランスポート：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 でリッスンします。リバースプロキシの背後に配置する場合は、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 イベント（閲覧、カートへの追加）に使用します。mode: "async" を指定すると run_operation で利用できます。

操作のシステム名（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	いいえ	1 回の試行のタイムアウト（ミリ秒、デフォルトは 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