WooCommerce MCP

woocommerce-mcp

WooCommerce REST API を通じて、1 つ以上の WooCommerce ストアを操作するための Model Context Protocol サーバーです。MCP クライアントは、カタログの閲覧、注文の処理と履行、返金の実行、価格や在庫の一括調整、プロモーションの実施、顧客のセグメント分け、Webhook への対応、売上分析の確認を行えます。すべての変更は適用前にプレビューされ、監査ログに記録できます。

ローカルでは stdio 経由で、リモートサービスとしてはベアラートークンまたは OAuth 2.0 認証を使用したストリーミング可能な HTTP 経由で実行できます。また、GitHub Container Registry の Docker イメージとして提供されています。

ドキュメント： https://sadrmanesh.github.io/woocommerce-mcp/ · ツールエクスプローラー： Hugging Face Space

詳細： エージェント向けの安全な書き込みツール：WooCommerce MCP サーバーでのプレビュー、確認、監査、古くなったプレビュー（Dev.to） · プレビュー、確認、監査（LinkedIn） · 更新：読者からのフィードバックを受けた1週間：コマース向け AI ツール4つに加えた変更（Dev.to） · コマース向けの本番環境で安全な AI ツールの構築について、読者からのフィードバックで学んだこと（LinkedIn）

公式 MCP Registryでは io.github.sadrmanesh/woocommerce-mcp として、Glamaおよびmcpservers.orgにも登録されています。

目次

• 特長
• クイックスタート
• MCP クライアントの接続
• ツール、リソース、プロンプト
• 安全な書き込み
• 設定
• デプロイ
• 開発
• ドキュメント

特長

• 複数ストアに対応。 任意の数のストアを設定し、store を指定して呼び出しごとにストアを選択できます。各ストアには独自の認証情報と読み取り専用スイッチがあります。
• デフォルトで安全。 書き込みを許可するまでは、ストアは読み取り専用です。書き込みツールは、正確な REST リクエストのプレビューを返し、confirm: true を指定して再度呼び出したときにのみ適用します。プレビュー後に引数または変更の計算元となったストアデータが変更されている場合、確認は拒否されます。dryRun: true を指定すると、常にプレビューが表示されます。
• 署名付き承認（任意）。 WOOCOMMERCE_APPROVAL_SECRET を設定すると、確認にはさらに、プレビューと完全に一致する内容に対して、エージェントの手の届かない人物が署名した有効期限付きの使い捨てトークンが必要になります。たとえば、woocommerce-mcp approve <previewId> を使って署名できます。エージェントは自身の書き込みを承認できません。
• 監査ログ。 書き込みの試行ごとに、適用、プレビュー、拒否、失敗のいずれかを、ツール、ストア、引数、呼び出し元、プレビュー ID とともに JSON 形式の1行で記録します。プレビュー ID により、確認済みの各書き込みをそのプレビューに関連付けられます。
• 返金と一括操作。 一部返金または商品項目単位の返金、最大100商品の一括更新、割合または固定額による価格調整に対応します。
• 分析。 返金、平均注文額、人気商品、支払い方法を含む日、週、月ごとの売上データと、バリエーションを網羅する在庫僅少レポートを提供します。
• プロモーションと顧客。 クーポンのパフォーマンス、予約販売、VIP、リピーター、離反リスクのある顧客などのセグメントに対応します。
• フルフィルメント。 注文メモ、配送追跡、顧客にメールを送信するワンステップのフルフィルメントに対応します。
• Webhook。 ストアの Webhook を管理し、MCP リソースとして読み取り可能な署名付き配信を受信します。
• 配送と税金。 配送ゾーン、配送方法、税率、税区分を読み取ります。
• プライバシーと制御。 オプションで個人情報をマスキングでき、デプロイ単位またはストア単位でツールの許可リストと拒否リストを設定できます。
• ストアにやさしい設計。 ストアごとのレート制限、バックオフとジッターを使った再試行、オプションの読み取りキャッシュに対応します。
• リモート利用に対応。 静的ベアラートークン（フル権限または読み取り専用）または RFC 7662 のトークンイントロスペクション、RFC 9728 の保護リソースメタデータ、Host と Origin のチェック、ヘルスエンドポイントを備えた Streamable HTTP に対応します。
• MCP リソースとプロンプト。 URI で商品や注文を読み取り、売上概要や補充計画など、一般的なワークフローを開始できます。
• 可観測性。 各ツール呼び出しと WooCommerce リクエストの OpenTelemetry トレースにオプションで対応します。
• 十分なテスト。 厳密な TypeScript、すべての入力に対する Zod 検証、モックされた WooCommerce API を使ったテストを備えています。

クイックスタート

Node.js 20 以降が必要です。

npm install -g @sadrmanesh/woocommerce-mcp

または、GitHub Container Registry の Docker イメージ（linux/amd64 と linux/arm64、タグは X.Y.Z、X.Y、latest）を実行します。同じイメージは Docker Hub でも sadrmanesh/woocommerce-mcp として公開されています。

docker run --rm -i -e MCP_TRANSPORT=stdio \
  -e WOOCOMMERCE_URL -e WOOCOMMERCE_CONSUMER_KEY -e WOOCOMMERCE_CONSUMER_SECRET \
  ghcr.io/sadrmanesh/woocommerce-mcp:0.6.0

npm パッケージは GitHub Packages でも公開されています。.npmrc の設定についてはインストール方法を参照してください。メインのレジストリは引き続き npmjs.com です。

チェックアウトしたリポジトリから実行する場合：

git clone https://github.com/sadrmanesh/woocommerce-mcp.git
cd woocommerce-mcp
npm install
npm run build
cp .env.example .env

WooCommerce > Settings > Advanced > REST API で REST API キーを作成します。ストアが読み取り専用の間は Read キーを使用し、書き込みを有効にする場合にのみ Read/Write キーを使用してください。WordPress のパーマリンクは「Plain」に設定しないでください。設定すると /wp-json/ が解決されません。

WOOCOMMERCE_URL=https://store.example.com \
WOOCOMMERCE_CONSUMER_KEY=ck_... \
WOOCOMMERCE_CONSUMER_SECRET=cs_... \
woocommerce-mcp

このプロセスは、標準入力と標準出力で MCP を提供します。ログは標準エラー出力に書き込まれます。チェックアウトしたリポジトリで npm start を実行すると、すでに設定されている環境変数を上書きせずに、作業ディレクトリの .env が読み込まれます。

MCP クライアントの接続

ほとんどのホストでは、以下の例のような mcpServers マップを使用できます。シークレットは args ではなく env に保管してください。Docker、Smithery、MCP Registry からのインストールについては、docs/install.md を参照してください。

stdio

{
  "mcpServers": {
    "woocommerce": {
      "command": "npx",
      "args": ["-y", "@sadrmanesh/woocommerce-mcp"],
      "env": {
        "WOOCOMMERCE_URL": "https://store.example.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_your_consumer_key",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_your_consumer_secret"
      }
    }
  }
}

チェックアウトから実行する場合は、"command": "node" と "args": ["/absolute/path/to/woocommerce-mcp/dist/index.js"] を使用します。

Streamable HTTP

MCP_TRANSPORT=http MCP_HTTP_AUTH_TOKENS="$(openssl rand -base64 32)" woocommerce-mcp

{
  "mcpServers": {
    "woocommerce": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

認証がない場合、HTTP エンドポイントはループバックにのみバインドされます。トークン、スコープ、OAuth のイントロスペクションについては、docs/security.md を参照してください。

ツール、リソース、プロンプト

woocommerce_list_stores 以外のすべてのツールは、オプションの store ID を受け取ります。指定しない場合は、デフォルトのストアが使用されます。

すべてのツールの完全な入力スキーマを確認し、ブラウザーで tools/call リクエストを作成するには、Hugging Face のツールエクスプローラーを開いてください。

領域	読み取りツール	書き込みツール
ストア	list_stores
商品	list_products、search_products、get_product	create_product、update_product、bulk_update_products、bulk_adjust_prices
注文	list_orders、get_order、list_order_notes	update_order_status、add_order_note、delete_order_note
フルフィルメント	get_order_tracking	fulfill_order
返金	list_refunds、get_refund	create_refund
顧客	list_customers、get_customer、customer_orders、customer_segments	update_customer
在庫	get_stock、low_stock_report	update_stock
クーポンとセール	list_coupons、get_coupon、coupon_performance	create_coupon、update_coupon、delete_coupon、schedule_sale、end_sale
Webhook	list_webhooks、get_webhook、list_webhook_events	create_webhook、update_webhook、delete_webhook
配送と税金	list_shipping_zones、list_shipping_methods、list_tax_rates、list_tax_classes
アナリティクス	get_store_summary、sales_analytics

すべての名前は woocommerce_ で始まります。たとえば、woocommerce_customer_segments です。ツールは合計 47 個で、読み取りが 28 個、書き込みが 19 個です。

リソース

URI	内容
woocommerce://stores	設定済みのストア
woocommerce://stores/{store}/products/{id}	1 つの商品
woocommerce://stores/{store}/orders/{id}	1 つの注文
woocommerce://stores/{store}/events	最近の Webhook 配信
woocommerce://stores/{store}/events/{id}	ペイロードを含む 1 件の Webhook 配信

プロンプト： sales_briefing、restock_plan、order_triage、price_change_review。

引数とレスポンスの詳細は、docs/tools.md を参照してください。

安全な書き込み

1. 読み取り専用ストア。 ストアへの書き込みは、WOOCOMMERCE_READ_ONLY=false（単一ストアの場合）または "readOnly": false（ストアリストの場合）のときにのみ受け付けられます。それ以外の場合、書き込みツールはストアに接続する前に read_only エラーで失敗します。

2. 確認。 WOOCOMMERCE_REQUIRE_CONFIRMATION=true（デフォルト）の場合、最初の呼び出しでは予定されているリクエストが返され、何も変更されません。

   {
     "status": "confirmation_required",
     "store": "default",
     "previewId": "pv_4f1c9a2e7b3d0856",
     "message": "The change was NOT applied. ...",
     "request": { "method": "PUT", "path": "orders/1015", "query": {}, "body": { "status": "completed" } }
   }
   

   同じ引数でツールをもう一度呼び出し、confirm: true を指定すると変更が適用されます。dryRun: true は、確認がオフの場合でも常にプレビューを表示します。すべてのプレビューには previewId が含まれます。これを confirm: true とともに送り返すと、プレビュー後に引数が変更されていた場合、サーバーは preview_mismatch エラーで呼び出しを拒否します。

   10％の値上げなど、ストアのデータをもとに書き込み内容を計算するツールは、プレビュー時に内容を確定します。プレビューの preconditions には、読み取った各レコードと、現在の値（before）、書き込みで設定する絶対値（after）が一覧表示されます。また、previewId の第2の部分には、そのデータのフィンガープリントが含まれます。確認時にサーバーは同じデータを再度読み取り、たとえば途中で価格が編集されて変更されていた場合、stale_preview エラーで呼び出しを拒否し、何も送信しません。対象となる内容と対象外の内容については、古くなったプレビューを参照してください。

3. スコープ。 認証済み HTTP では、書き込みツールに woocommerce:write スコープも必要です。読み取り専用トークンでストアを変更することはできません。

4. 監査。 WOOCOMMERCE_AUDIT_LOG にファイルパスまたは stderr を設定します。

   {"time":"2026-10-30T14:02:11.120Z","tool":"woocommerce_update_order_status","store":"default","outcome":"applied","arguments":{"id":1015,"status":"completed"},"client":"static:3f9a1c2b7d10","previewId":"pv_4f1c9a2e7b3d0856","previewMatch":true}
   

5. 署名付き承認（任意）。 プレビュー ID は「何を」確認するかを紐付けますが、「誰が」確認したかは紐付けません。デフォルトでは、エージェントはプレビューをリクエストし、同じターン内に確認できます。各確認に approval トークンを必須にするには、WOOCOMMERCE_APPROVAL_SECRET を設定します。このトークンは、正確な previewId（状態部分を含む）、ツール、ストア、有効期限を対象とする HMAC-SHA256 署名であり、別の引数や変更されたストアには再利用できません。トークンは一度だけ使用でき、デフォルトでは10分後に期限切れになります。担当者はプレビューを確認した後、次のように署名します。

   woocommerce-mcp approve pv_e2a742fe51c807fc_a3510d17b8a51b93 --by "Naser"
   

   このコマンドは監査ログからプレビューされた変更を表示し、「はい」と答えるよう求めた後、トークンを出力します。エージェントはそのトークンを confirm: true とともに approval として送り返します。トークンがない場合、無効な場合、期限切れの場合、不一致の場合、または再使用された場合は、approval_required、approval_invalid、approval_expired、approval_mismatch、approval_replayed エラーで拒否されます。トークン形式は公開されているため、承認ページやウェブフックでも署名できます。

   この仕組みでできないこと：シークレットを持っている人は誰でも承認できるため、MCP クライアントの設定、プロンプト、エージェントがシェルを実行できるホストにはシークレットを置かないでください。使用済みトークンはプロセスごとにメモリ上で追跡されます。シークレットがない場合の動作は、0.5.0 とまったく同じです。署名付き承認を参照してください。

woocommerce_create_refund で作成された返金は、apiRefund: true を指定して決済ゲートウェイに返金を依頼しない限り、手動返金として記録されます。

設定

よく使用される設定を以下に示します。マルチストアのファイル形式を含むすべての変数については、docs/configuration.md と .env.example をご覧ください。

変数	デフォルト	説明
WOOCOMMERCE_URL		/wp-json を含まないストアのオリジン
WOOCOMMERCE_CONSUMER_KEY / _SECRET		REST API 認証情報
WOOCOMMERCE_READ_ONLY	true	単一ストアへの書き込みを許可します
WOOCOMMERCE_STORES_FILE / WOOCOMMERCE_STORES		JSON ファイルまたはインライン JSON で複数のストアを指定します
WOOCOMMERCE_DEFAULT_STORE	first store	呼び出しで store が省略された場合に使用するストア
WOOCOMMERCE_REQUIRE_CONFIRMATION	true	confirm: true が指定されるまで書き込みをプレビューします
WOOCOMMERCE_AUDIT_LOG	off	ファイルパスまたは stderr
WOOCOMMERCE_APPROVAL_SECRET	off	確認済みのすべての書き込みに署名付き承認トークンを必須にします。エージェントから遠ざけて保管してください
WOOCOMMERCE_APPROVAL_TTL_SECONDS	600	サーバーが受け付ける承認トークンの最長有効期間
MCP_TRANSPORT	stdio	stdio または http
MCP_HTTP_HOST / _PORT / _PATH	127.0.0.1 / 3000 / /mcp	HTTP リスナー
MCP_HTTP_AUTH_TOKENS		フルアクセスのベアラートークン
MCP_HTTP_AUTH_READ_TOKENS		読み取り専用のベアラートークン
WOOCOMMERCE_REDACT_PII	false	結果内の名前、メールアドレス、電話番号、住所をマスキングします
WOOCOMMERCE_TOOLS_ALLOW / _DENY		公開または非表示にするツール名または * パターン
WOOCOMMERCE_WEBHOOK_SECRET		ストアの Webhook レシーバーを有効にします
WOOCOMMERCE_RATE_LIMIT / _BURST	5 / 10	ストアごとの秒間リクエスト数とバースト数
WOOCOMMERCE_CACHE_TTL_MS	0 (off)	読み取りレスポンスをキャッシュします
WOOCOMMERCE_OTEL_ENABLED	false	OpenTelemetry トレースをエクスポートします

マルチストアの例（stores.json）：

{
  "defaultStore": "eu",
  "stores": [
    { "id": "eu", "label": "EU shop", "url": "https://eu.example.com", "consumerKeyEnv": "EU_KEY", "consumerSecretEnv": "EU_SECRET" },
    { "id": "us", "url": "https://us.example.com", "consumerKeyEnv": "US_KEY", "consumerSecretEnv": "US_SECRET", "readOnly": false }
  ]
}

デプロイ

cp .env.example .env    # add store credentials and MCP_HTTP_AUTH_TOKENS
docker compose up -d --build
curl http://127.0.0.1:3000/healthz

イメージは非 root ユーザーとして実行され、ポート 3000 でリッスンし、ヘルスチェックを備えています。リモートで使用する場合は、TLS を終端するリバースプロキシの背後に配置してください。docs/deployment.md をご覧ください。

開発

npm install
npm run check   # lint, typecheck, tests, build

テストはモックの WooCommerce API に対して実行され、実際のストアには接続しません。CONTRIBUTING.md をご覧ください。

ドキュメント

ドキュメントサイトの全内容は https://sadrmanesh.github.io/woocommerce-mcp/ にあります。同じガイドはこのリポジトリにもあります。

• インストール方法
• 設定
• ツールリファレンス
• Webhook
• プライバシー
• パフォーマンス
• セキュリティと認証
• デプロイ
• オブザーバビリティ
• 変更履歴

技術レポート

技術レポート：WooCommerce Model Context Protocol Server - E コマースにおける自律型 AI エージェントのためのマルチストア対応・プレビュー可能な安全な書き込みアーキテクチャ。M. N. Sadrmanesh、Zenodo、2026年。https://doi.org/10.5281/zenodo.23897615 ResearchGate と Academia.edu にも掲載されています。

@techreport{sadrmanesh2026woocommercemcp,
  author      = {Sadrmanesh, Mohammad Naser},
  title       = {Technical Report: WooCommerce Model Context Protocol Server - A Multi-Store, Previewed Safe-Write Architecture for Autonomous AI Agents in E-Commerce},
  institution = {Zenodo},
  year        = {2026},
  version     = {1.0},
  doi         = {10.5281/zenodo.23897615},
  url         = {https://doi.org/10.5281/zenodo.23897615}
}

ライセンス

MIT。Copyright (c) 2026 Naser Sadrmanesh。LICENSE をご覧ください。

著者

Naser Sadrmanesh：https://github.com/sadrmanesh · https://sadrmanesh.github.io · [email protected]