Bigcommerce Api Mcp

BigCommerce MCP サーバー

BigCommerce REST API 用の MCP サーバーです。AI アシスタントがカタログ、顧客、注文を読み取れるようにします。また、有効にすると、それらを変更することもできます。

ツール

読み取り

ツール	機能
get_all_products	フィルタリング、並べ替え、ページネーションを使って商品を一覧表示します
get_product	ID で商品を 1 件取得します。オプションでバリエーションや画像も含められます
get_all_customers	ID、メールアドレス、名前、会社名、期間で顧客を一覧表示します
get_all_orders	顧客、ステータス、期間、合計金額で注文を一覧表示します
get_order	ID で注文を 1 件取得します
get_order_products	注文の明細項目（実際に購入された商品）を取得します
list_categories	商品フィルターで必要となる ID にカテゴリ名を対応付けます
list_brands	商品フィルターで必要となる ID にブランド名を対応付けます

書き込み — BIGCOMMERCE_ENABLE_WRITES=true が必要です

ツール	機能
create_product	カタログに商品を作成します
update_product	価格、在庫、公開状態、カテゴリなどを更新します
create_customer	顧客レコードを作成します
update_customer	顧客情報を更新します
update_order	ステータス、スタッフ用メモ、顧客向けメッセージを変更します

書き込みツールは有効にしない限り登録されないため、デフォルトのデプロイでは、誰かがエンドポイントにアクセスできてもストアを変更できません。

npm run list-tools を実行すると、現在設定されているツールとパラメーターが表示されます。

セットアップ

Node 20 以降が必要です。

git clone https://github.com/isaacgounton/bigcommerce-api-mcp.git
cd bigcommerce-api-mcp
npm install
cp .env.example .env

次に、.env に入力します。

BIGCOMMERCE_STORE_HASH=your_store_hash_here
BIGCOMMERCE_API_KEY=your_api_key_here

どちらも BigCommerce 管理画面 → Settings → API accounts → Create API account から取得します。Products、Orders、Customers の権限を付与してください。書き込みを有効にする予定がなければ、読み取り専用にします。.env.example に、サポートされているすべての変数が記載されています。

実行

npm start          # stdio — Claude Desktop, Cline, local clients
npm run start:http # streamable HTTP — remote clients and agent runtimes

HTTP モードでは POST /mcp に加えて、認証不要の GET /health と GET /info を提供します。

SSE トランスポートは、MCP 仕様で置き換えられた Streamable HTTP に移行するため廃止されました。引き続き /sse を使用しているクライアントは、接続先を /mcp に変更してください。

Claude Desktop

claude_desktop_config.json で設定します（絶対パスを使用してください。which node で確認できます）。

{
  "mcpServers": {
    "bigcommerce": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/bigcommerce-api-mcp/mcpServer.js"],
      "env": {
        "BIGCOMMERCE_STORE_HASH": "your_store_hash",
        "BIGCOMMERCE_API_KEY": "your_api_key"
      }
    }
  }
}

HTTP 経由

curl -X POST http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

セキュリティ

/mcp を呼び出せるユーザーは、ストアの API 認証情報を使って操作できます。

• HOST — デフォルトでは 127.0.0.1 にバインドされます。公開する意図がある場合に限り 0.0.0.0 に設定し、その場合はプロキシまたはファイアウォールの背後に配置してください。
• MCP_AUTH_TOKEN — 設定すると、すべての /mcp リクエストに Authorization: Bearer <token> が必要です。比較にはタイミングセーフな処理を使用します。サーバーが localhost の外部からアクセス可能な場合は、必ず設定してください。
• ALLOWED_ORIGINS — Origin ヘッダーを含むリクエストは、ここに記載されていない限り拒否されます。これにより、アクセスしたページからローカルサーバーを操作する DNS リバインディング攻撃を防げます。ブラウザー以外のクライアントは Origin を送信しないため、影響を受けません。
• BIGCOMMERCE_ENABLE_WRITES — アシスタントが読み取りのみを行う場合は、無効のままにしてください。
• スコープ — API アカウントには、動作に必要な最小限のスコープを付与してください。読み取り専用トークンは、このサーバーのバグによって書き込み可能になることはありません。

Docker

docker build -t bigcommerce-mcp .
docker run --rm -p 3000:3000 --env-file .env bigcommerce-mcp

イメージでは HOST=0.0.0.0 が設定されるため、公開ポートにアクセスできます。コンテナを公開する前に MCP_AUTH_TOKEN を設定してください。

開発

npm test           # protocol, auth, origin, discovery and spec conformance — no credentials needed
npm run test:live  # smoke-test read tools against a real store (needs .env)
npm run sync-spec  # refresh the query-parameter fixture from BigCommerce's OpenAPI specs

npm test では、ツールが宣言するすべてのクエリパラメーターを、BigCommerce が公開している仕様と照合します。BigCommerce は不明なクエリパラメーターを拒否せず無視するため、これは重要です。存在しないフィルターを指定すると、エラーになる代わりにフィルターなしのデータが黙って返され、より深刻な問題になります。

ツールを追加するには、tools/bigcommerce/<group>/ に apiTool をエクスポートするファイルを追加します。自動的に検出されます。lib/bigcommerce.js が認証情報、クエリの構築、エラー処理、解析を担当するため、通常、ツールに必要なのはパスとスキーマだけです。tools/bigcommerce/catalog/list-brands.js をコピーしてください。ストアを変更するツールには writes: true を設定します。

MIT