@marketbasketanalysis/mcp

あらゆる AI エージェントに、Eコマースマーチャントの注文履歴に基づく実際の併買インテリジェンスとマーチャント運用ツールへのアクセスを提供する MCP サーバーです。ディスカバリー、バンドル、インサイト、補充、マーチャント運用、高度なマイニングにわたる 19 のツールを備えています。Claude Desktop、Claude Code、Cursor、Windsurf、Cline、OpenAI Agent SDK、その他 MCP stdio プロトコルを話すあらゆるホストで動作します。Shopify、BigCommerce、WooCommerce、Magento、OroCommerce のマーチャント向けに動作します。セルフホスト型バックエンドに到達できるツールについては、下の「プラットフォーム対応状況」を参照してください。

単一の npm パッケージがすべてのマーケットプレイスに対応します。サーバーはプラットフォームに依存せず、公開 REST API を介してストアの MBA バックエンドを呼び出す HTTP クライアントです。単一のスイッチ（MBA_API_BASE、下記参照）でサーバー全体を任意のストアに向け直せます。ほとんどのツールは 5 つのプラットフォームすべてで動作します。一部は、まだすべてのプラットフォームが提供していないバックエンドルートに依存します。ツールごとのマーケットプレイス対応状況は、ツールカタログ の「マーケットプレイス」列に記載されています。

存在理由

顧客が AI ショッピングエージェントに「ジム用バックパックに合うものは？」と尋ねたとき、エージェントはマーチャントの実際の注文データに基づいた本当の回答を返すべきであり、一般的な「おすすめはこちら」のような当てずっぽうであってはなりません。マーチャントが Claude に「今週は何に取り組むべき？」と尋ねたとき、エージェントはランク付けされた週次プランから引き出すべきであり、タスクをでっち上げるべきではありません。このサーバーは、その両方のフローを 1 行の設定で任意の MCP ホストに提供します。

5行インストール（Claude Desktop）

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": { "MBA_API_KEY": "mba_live_YOUR_KEY_HERE" }
    }
  }
}

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）に貼り付け、Claude Desktop を再起動すると、marketbasketanalysis サーバーが 19 個すべてのツールとともにツール一覧に表示されます。

ゼロインストール：ホステッドエンドポイント

同じサーバーが https://mcp.marketbasketanalysis.com/mcp（MCP streamable HTTP）でホスト型実行されています。インストールは不要です。環境変数ではなく Bearer ヘッダーとしてキーを送信してください：

claude mcp add --transport http marketbasketanalysis \
  https://mcp.marketbasketanalysis.com/mcp \
  --header "Authorization: Bearer mba_live_YOUR_KEY_HERE"

リモート対応の MCP クライアント（Claude Code、Cursor、Smithery、カスタムエージェント）で動作します。オプションヘッダー：X-MBA-Base は別の MBA 運営プレーンに向け直します（例：https://bigcommerce.marketbasketanalysis.com）。X-MBA-Platform は MBA_PLATFORM 環境変数をミラーリングします。セルフホスト型の WooCommerce および Magento ストアは、設計上ホステッドエンドポイントからは到達できません。MBA_API_BASE を自社サイトに向けた上記の npx インストールを使用してください。

サーバーをストアに向ける（MBA_API_BASE）

ベース URL はストアごとの設定です。デフォルトでは、サーバーは共有ホスト型バックエンド https://app.marketbasketanalysis.com と通信します。データが他の場所（BigCommerce ストア、セルフホスト型バックエンド、ステージングインスタンスなど）にある場合は、MBA_API_BASE を設定して、すべてのツールが独自のデータプレーンに到達するようにしてください：

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": {
        "MBA_API_KEY": "mba_live_YOUR_KEY_HERE",
        "MBA_API_BASE": "https://your-store-backend.example.com"
      }
    }
  }
}

MBA_API_BASE はサーバー全体を向け直す単一のスイッチであり、19 個すべてのツールがこれを経由します。値は非ローカルホストでは https:// URL である必要があります（ループバック、プライベート、リンクローカル、メタデータサービスホストは拒否されます）。localhost 上のバックエンドに対するローカル開発では、ALLOW_LOCAL_API_BASE=1 を設定して http://localhost ベースを許可してください。環境変数の変更はサーバー起動時に反映されるため、値を編集した後は MCP ホストを再起動してください。

プラットフォーム別の MBA_API_BASE

ベース URL はストアごとの設定です。Shopify、BigCommerce、OroCommerce のストアは共有ホスト型バックエンドが提供するため、デフォルトを使用します。WooCommerce と Magento はストアインストール内でバックエンドをローカル実行するため、サーバーをストア自身のドメインに向けてください：

プラットフォーム対応状況

サーバーは正規の /api/v1/... パスを書き出し、プラットフォームごとに書き換えます。WooCommerce と Magento はストア内でバックエンドを独自の REST 規約（それぞれ marketbasketanalysis/v1 と V1/marketbasketanalysis）で実行するためです。

19 のツールのうち 10 が WooCommerce と Magento に到達します：/recommendations から派生する 6 つ（get_recommendations、get_bundle_for_cart、score_cross_sell、analyze_basket、propose_subscription_bundle、score_return_risk）に加え、find_substitutes、get_rationale、forecast_bundle、predict_reorder です。

残りの 9 つはマーチャント運用サーフェスです：get_opportunities、triage_opportunity、get_weekly_plan、execute_weekly_plan_action、get_drift_alerts、get_forecast_alerts、explain_opportunity、explain_drift、mine_hui_itemsets。これらのエンドポイントはセルフホスト型バックエンドには存在しません。そこで呼び出すと、ネットワーク往復なしで、エンドポイント名を明示した明確な "not available on this platform" エラーが返り、不透明な 404 にはなりません。

ステップバイステップのインストール手順（OS ごとの設定ファイルの場所、API キーの発行方法、トラブルシューティング）はこちら：

• Claude Desktop: dist/mcp/claude-desktop-setup.md

• Cursor: dist/mcp/cursor-setup.md

• Windsurf: dist/mcp/windsurf-setup.md

認証

サーバーは MCP ホストが渡す環境から MBA_API_KEY を読み取り、すべてのリクエストで Bearer トークンとして送信します。キーを取得するには：

1. MarketBasketAnalysis 管理画面を開きます（Shopify のアプリドロワー、または BigCommerce / WooCommerce / Magento / OroCommerce の管理画面）。

2. 左ナビゲーションの「API keys」をクリックします。

3. 「Create key」をクリックし、名前を付けて、mba_live_ の値をコピーします（一度だけ表示されます）。

キーはショップごとで、失効・ローテーションも同じ画面から行えます。SHA-256 ハッシュのみが保存されるため、キーが漏えいした場合は再発行してください。

認証モデルはマーケットプレイスごとに異なりますが、MCP サーバーが抽象化しています。それでも知っておく価値があります：

• Shopify、BigCommerce：Bearer mba_live_... をそのまま通します。これが一般的な経路です。

• WooCommerce：WooCommerce が発行したキーに対する Bearer です。predict_reorder には customer_data スコープが必要です。

• Magento：ツールは Magento REST サーフェス（/V1/marketbasketanalysis/* と /V1/mba/*）経由でストアに到達します。一部のルートはストア側で admin トークン / ACL スコープに制限されています。

• OroCommerce：/api/ ルートではストアがプラットフォームの OAuth2 ファイアウォールの背後にあります。シンクライアントがプロキシするホスト型バックエンドを MCP サーバーが実際に呼び出すため、mba_live_ キーが引き続き適用されます。

ツールカタログ

19 のツールは、4 つの Basket AI エージェント ロールと 2 つの運用グループに分類されます。マーケットプレイス列は、ツールが呼び出すルートを提供しているバックエンドを示しています。これは、このサーバーが現在到達できるバックエンドとは異なります。「プラットフォーム対応状況」を参照してください。「All five」は Shopify、BigCommerce、WooCommerce、Magento、OroCommerce を意味します。

ディスカバリー

バンドル

これらはすべて /recommendations から派生します（サーバーがバンドル/スコアリングロジックをクライアントサイドで構成します）。そのため、追加のバックエンドルートは不要で、どこでも動作します。

インサイト

これらも /recommendations から派生するため、すべてのプラットフォームで動作します。

補充と予測

マーチャントオペレーション

これらは、現在 BigCommerce で提供されている Bearer /api/v1 ルートを呼び出します。Shopify は、機会、ドリフト、週次プランを /api/v1 ルートではなく埋め込み管理ビューを通じて提供するため、これらのツールは BigCommerce バックエンドに対して解決されます。唯一の例外は /explain-opportunity で、現在 BigCommerce と Shopify の両方で提供されています。/explain-drift は BigCommerce のみのままです。これらのツールは、そのルートを持たないプラットフォームでは明確なアップストリーム 404 を返します。

高度なマイニング

ツールごとのプロンプト例

サーバーを接続した後、これらのいずれかを Claude Desktop / Claude Code / Cursor のチャットに貼り付けてください:

• get_recommendations: "marketbasketanalysis を使って、ジム用バックパック（商品 8472918765）と一緒に顧客がよく購入するものを調べてください。"

• find_substitutes: "DSLR ボディが在庫切れです。 良い代替品はありますか？"

• get_rationale: "ジム用バックパックと一緒にウォーターボトルが推奨される理由は？"

• get_bundle_for_cart: "カートにカメラボディ、32GB SDカード、 三脚があります。完全なキットにするために不足していそうなものは 何ですか？"

• propose_subscription_bundle: "顧客 9876 向けの毎月のサブスクリプションキットを組み立ててください。"

• score_cross_sell: "クリーニングキットは DSLR カメラボディの良いクロスセルですか？"

• score_return_risk: *"カメラ + レンズの返品リスクは？

  • 三脚 + バッグのバンドル？"*

• analyze_basket: "カメラ + レンズ + SDカード + バッグを バンドルしようと考えています。実際の顧客データに基づくと、 それは強いバンドルですか？"

• predict_reorder: "Acme Corp（顧客 7654321）は今週 何を再発注する予定ですか？"

• forecast_bundle: "バンドル b-camera-kit の今後 12 週間を予測し、購入数量を推奨してください。"

• get_weekly_plan: "今週のプランは何ですか？"

• execute_weekly_plan_action: "週次プランからアクション a-42 を実行してください。確認済みです。"

• get_opportunities: "提案された機会の上位 3 件を 表示してください。"

• explain_opportunity: "機会 opp-17 がなぜ良いクロスセルなのですか？"

• triage_opportunity: "機会 opp-17 をアクティブ化してください。確認済みです。"

• get_drift_alerts: "いずれかのルールがドリフトしていますか？"

• explain_drift: "ドリフトアラート alert-7 のペアは なぜドリフトしたのですか？"

• get_forecast_alerts: "在庫切れのリスクがあるバンドルはどれですか？"

• mine_hui_itemsets: "この 90 日間の注文ペイロードから 上位 20 件の高ユーティリティアイテムセットをマイニングしてください。" (Plus / Enterprise ティア)

ツール別の説明ドキュメントは cookbook にあります。

環境変数

開発

git clone https://github.com/48x-ai/marketbasketanalysis-mcp
cd marketbasketanalysis-mcp
npm install
npm run typecheck
npm test
npm run dev    # tsx-based local run
npm run build  # emit ./dist

新しいツールの追加

各ツールは src/tools/ 配下の自己完結型モジュールです。追加するには:

1. definition と handler をエクスポートする src/tools/myNewTool.ts を作成します。単純な GET の場合は src/tools/getRecommendations.ts、confirm ゲート付き POST の場合は src/tools/triageOpportunity.ts の構造を参考にしてください。

2. src/tools/index.ts で、モジュールをインポートして allModules 配列に追加することで登録します。

3. src/tools/myNewTool.test.ts にテストを追加します。カバー内容: キー欠落時の応答、ハッピーパス、そして少なくとも 1 つの上流エラーパス。src/tools/findSubstitutes.test.ts を参考にしてください。

4. 上記の表と dist/mcp/smithery.yaml にドキュメントを記載します。

配布物

モノレポルートの dist/mcp/ ディレクトリには、インストールサンプル（Claude Desktop、Cursor、Windsurf）、Smithery YAML、Anthropic マーケットプレイス提出用コンテンツが含まれています。完全なレイアウトは dist/mcp/README.md を参照してください。

公開

package.json のバージョンを引き上げ（server.json と src/index.ts の同期を維持）、main にマージしてから、mcp-v タグを付けてプッシュします。ワークフローは型チェック、テスト、ビルド、タグ/バージョンの一致チェックを実行し、その後 NPM_TOKEN リポジトリシークレットを使用して npm publish --access public --provenance を実行します。レスキュー実行用に workflow_dispatch の手動トリガーも利用できます。

一度だけ必要な NPM_TOKEN の設定や、CI を使わない手動公開のフォールバックを含む、完全なオペレーター向けチェックリストは docs/RELEASE.md にあります。

トラブルシューティング

より詳細な診断については、dist/mcp/ 配下の IDE 別セットアップドキュメントを参照してください。

ライセンス

UNLICENSED、プロプライエタリ。