Woocommerce MCP Server

woocommerce-mcp-server

WooCommerce 向けの本番運用対応 Model Context Protocol（MCP）サーバー — Claude AI または MCP 対応クライアントを使用して、注文、商品、顧客、在庫、分析データを管理できます。

---

🎥 できること

接続したら、Claude に自然な言葉で話しかけるだけです。

「今週の処理中の注文をすべて表示して」 「在庫が少なくなっている商品はどれ？」 「SKU WOO-1234 の商品を探して」 「今月の売上はいくら？」 「新しい顧客を教えて」 「注文 #501 を完了済みにして」

WooCommerce のダッシュボードをクリックして回る必要はもうありません。AI が処理します。

---

✨ 特長

• ✅ 本番運用対応のツールを 20 個搭載 — 注文、商品、顧客、分析データを網羅
• ✅ TypeScript — 完全な型付けで、実行時の予期しない問題を防止
• ✅ リトライロジック — ネットワークエラーやレート制限時に自動で再試行
• ✅ 分かりやすいエラーメッセージ — 生の API エラーをユーザーに表示しません
• ✅ Zod による入力検証 — 不正な入力を API に送信する前に拒否
• ✅ Claude Desktop、MCP Inspector、その他の MCP 対応クライアントで動作
• ✅ npm からインストール可能 — リポジトリのクローンは不要

---

🛠️ ツール一覧

📦 注文（5 個のツール）

ツール	説明
list_orders	フィルター（ステータス、日付、顧客）を指定して注文を一覧表示
get_order	1 件の注文の詳細をすべて取得
update_order_status	注文のステータスを変更（任意でメモを追加）
get_order_notes	注文に関するすべてのメモを取得
add_order_note	社内向けまたは顧客に表示されるメモを追加

🏷️ 商品（7 個のツール）

ツール	説明
list_products	フィルターを指定して商品カタログを閲覧
get_product	1 件の商品の詳細をすべて取得
update_product	価格、在庫、ステータス、説明を更新
get_low_stock_products	在庫数がしきい値以下の商品
get_out_of_stock_products	在庫切れの商品をすべて取得
search_products_by_sku	SKU を完全一致で商品を検索
list_product_categories	商品数付きですべてのカテゴリーを取得

👥 顧客（4 個のツール）

ツール	説明
list_customers	検索しながら顧客を閲覧
get_customer	顧客プロフィールの詳細をすべて取得
get_customer_orders	顧客の注文をすべて取得
get_recent_customers	過去 N 日間の新規顧客を取得

📊 分析（4 個のツール）

ツール	説明
get_revenue_summary	期間別の売上、注文数、平均注文額
get_sales_report	税金、送料、返金を含む詳細レポート
get_top_selling_products	販売数量別の売れ筋商品
get_order_status_counts	ステータス別の注文数内訳

---

🚀 クイックセットアップ

前提条件

• Node.js 18+
• REST API にアクセスできる WooCommerce ストア
• Claude Desktop（AI 連携用）

ステップ 1 — WooCommerce API キーを生成する

1. WordPress ダッシュボードを開きます
2. WooCommerce → Settings → Advanced → REST API に移動します
3. Add Key をクリックします
4. 説明に MCP Server を設定します
5. 権限に Read/Write を設定します
6. Generate API Key をクリックします
7. Consumer Key と Consumer Secret をコピーします

ステップ 2 — npx でインストール（推奨）

インストールは不要です。Claude Desktop を直接設定します。

Claude Desktop の設定ファイルを開きます。

• Windows: C:\Users\<YourName>\AppData\Roaming\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

次の設定を追加します。

{
  "mcpServers": {
    "woocommerce": {
      "command": "npx",
      "args": ["-y", "woocommerce-mcp-server"],
      "env": {
        "WOOCOMMERCE_URL": "https://yourstore.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_your_consumer_key_here",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_your_consumer_secret_here"
      }
    }
  }
}

Claude Desktop を再起動します。🔌 プラグアイコンが表示されれば、WooCommerce ストアが接続されています。

---

代替方法 — クローンしてローカルで実行

git clone https://github.com/arbazex/woocommerce-mcp-server.git
cd woocommerce-mcp-server
npm install

.env ファイルを作成します。

WOOCOMMERCE_URL=https://yourstore.com
WOOCOMMERCE_CONSUMER_KEY=ck_your_key_here
WOOCOMMERCE_CONSUMER_SECRET=cs_your_secret_here

ビルドして実行します。

npm run build
node build/index.js

次に、Claude Desktop の設定を更新し、ローカルビルドを指定します。

{
  "mcpServers": {
    "woocommerce": {
      "command": "node",
      "args": ["C:\\path\\to\\woocommerce-mcp-server\\build\\index.js"],
      "env": {
        "WOOCOMMERCE_URL": "https://yourstore.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_your_key_here",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_your_secret_here"
      }
    }
  }
}

---

🧪 MCP Inspector でテスト

Claude Desktop を使わずに、ブラウザーでツールをテストできます。

npx @modelcontextprotocol/inspector build/index.js

最初に環境変数を設定します。

# Windows PowerShell
$env:WOOCOMMERCE_URL="https://yourstore.com"
$env:WOOCOMMERCE_CONSUMER_KEY="ck_your_key"
$env:WOOCOMMERCE_CONSUMER_SECRET="cs_your_secret"

# macOS/Linux
export WOOCOMMERCE_URL="https://yourstore.com"
export WOOCOMMERCE_CONSUMER_KEY="ck_your_key"
export WOOCOMMERCE_CONSUMER_SECRET="cs_your_secret"

---

🔑 API キーの権限

機能	必要な権限
注文、商品、顧客、分析データの読み取り	読み取り
注文ステータスの更新、メモの追加、商品の更新	読み取り／書き込み

⚠️ 書き込み権限がない場合、更新ツールは認証エラーを返します。すべての機能を利用するには、読み取り／書き込みキーを生成してください。

---

📁 プロジェクト構成

woocommerce-mcp-server/
├── src/
│   ├── index.ts          # Entry point (stdio transport)
│   ├── server.ts         # MCP server setup
│   ├── woo-client.ts     # WooCommerce API client (retry + error handling)
│   ├── types/
│   │   └── woo-types.ts  # Full TypeScript type definitions
│   └── tools/
│       ├── orders.ts     # Order management tools
│       ├── products.ts   # Product management tools
│       ├── customers.ts  # Customer management tools
│       └── analytics.ts  # Reporting and analytics tools
├── build/                # Compiled output (generated)
├── package.json
├── tsconfig.json
└── .env.example

---

🔒 セキュリティ

• API 認証情報は環境変数経由で渡されます。ハードコードされることはありません
• API を呼び出す前に、すべての入力を Zod で検証します
• レート制限エラーには、自動再試行とバックオフで適切に対処します
• 認証情報は stdout に出力されません（デバッグメッセージは stderr のみ）

---

🛠️ 開発

# Install dependencies
npm install

# Watch mode (auto-rebuild on save)
npm run dev

# Build once
npm run build

# Open MCP Inspector
npm run inspect

---

🤝 コントリビューション

コントリビューションを歓迎します。新しいツールのアイデアがある場合や、バグを見つけた場合は、次の手順に従ってください。

1. リポジトリをフォークします
2. ブランチを作成します：git checkout -b feature/your-tool-name
3. 変更を加えます
4. プルリクエストを作成します

---

📋 ロードマップ

• 注文作成ツール
• クーポン管理ツール
• Webhook 管理
• 商品バリエーションのサポート
• ホスト型デプロイ向けリモート HTTP（Streamable HTTP）トランスポート
• 一括操作のサポート

---

📄 ライセンス

MIT © Arbaz

---

Arbaz が ❤️ を込めて作成