Medusa

medusa-mcp

🇨🇿 チェコ語

Medusa v2 Admin API 用の MCP サーバーです。Claude、ChatGPT、その他の MCP クライアントから Medusa ストアを操作できます。注文、決済と返金、返品、注文の編集、下書き注文、商品とカタログ、在庫、顧客、プロモーション、価格表に加えて、売上、顧客、再入荷の分析を、チャット内のインタラクティブなダッシュボードで利用できます。

• 日々のストア管理に使える 55 個のツールと、その他の Admin API エンドポイントに対応する medusa_request
• インタラクティブなビュー（MCP Apps）— 売上ダッシュボードと再入荷プランナーを Claude と ChatGPT 内にインライン表示します
• プロンプト — すぐに使えるワークフロー（ストアの概要、フルフィルメント、返品、再入荷、月次レポートなど）をスラッシュコマンドとして提供します
• リソース — 注文、商品、顧客を、オートコンプリート付きで添付可能なコンテキストとして利用できます
• 安全対策 — 一括変更のプレビュー（ドライラン）、破壊的な操作の確認ダイアログ、すべての変更の監査ログ

次の 2 つのモードで動作します。

• stdio — Claude Desktop、Claude Code、その他の MCP クライアント向けのローカルモード
• Streamable HTTP + OAuth 2.1 — Claude（ウェブ、デスクトップ、モバイル）および ChatGPT 用のリモートコネクター

MCP Registry に io.github.trhonpavel/medusa-mcp として登録されているほか、スキルを備えた Claude Code / Cowork プラグインと、ワンクリックでインストールできる Claude Desktop 拡張機能（.mcpb）も提供しています。

ツール

読み取りと分析

ツール	機能
get_store_info	地域と通貨、販売チャネル、在庫ロケーション、配送オプションと配送プロファイル、返品と返金の理由
list_orders / get_order	全文検索、日付範囲、顧客、ステータスによる注文の検索。ID または注文番号（1042）による詳細情報（決済、返金、割引コード、返品を含む）
list_customers / get_customer	顧客（グループまたはメールアドレスによる検索にも対応）、注文履歴、累計購入額
list_customer_groups	顧客グループ
list_products / get_product	ステータス、コレクション、カテゴリー、タグによる商品検索。バリアント、オプション、価格、画像、在庫アイテム（ID またはハンドルによる検索）
list_catalog	カテゴリー（ツリー）、コレクション、タグ、商品タイプ
list_inventory	ロケーションごとの在庫。low_stock_threshold で在庫切れが近い商品を検索
list_promotions / list_price_lists	条件、使用状況、有効期間を含む割引コード。セール価格表と顧客グループ別価格表
sales_report	売上、返金後の純売上、AOV、販売数量、顧客数 — 前の期間または前年と比較、日／週／月ごとの系列、上位商品とバリアント、国、割引コード、販売チャネル · インタラクティブなダッシュボード
customer_report	新規顧客とリピーター、リピート購入率、上位顧客、再獲得が見込める休眠顧客
inventory_forecast	販売速度と在庫の比較：在庫日数、在庫切れ／即時再発注／近日中に再発注、推奨発注数量、動きの遅い商品 · インタラクティブな再入荷プランナー

書き込み（MEDUSA_READ_ONLY=true の場合は登録されません）

領域	ツール
フルフィルメント	create_fulfillment（デフォルト：残りの全商品、唯一の在庫拠点）、create_shipment（追跡番号）、mark_delivered、cancel_fulfillment
注文	update_order（メールアドレス、住所、メタデータ）、edit_order（商品の追加、変更、削除。新しい合計金額を事前にプレビューします）、complete_order、cancel_order
決済	mark_order_paid（銀行振込、代金引換。変換済みの下書き注文にも対応）、capture_payment、refund_payment（返金可能額を確認します）
返品	create_return（デフォルト：発送済みの全商品）、receive_return（商品を在庫に戻します）
下書き注文	create_draft_order（バリアントまたは SKU による商品、カスタム価格、配送）、convert_draft_order
商品	create_product（シンプルな商品、またはオプションとバリアント付きの商品を作成。初期在庫、販売チャネルと配送プロファイルのデフォルト設定にも対応）、update_product、add_product_images（URL から追加し、ショップのストレージにコピー）、delete_product
バリアント	create_variant（新しいオプション値を自動的に追加）、update_variant、delete_variant、set_variant_price（他のすべての価格を維持）
カタログ	save_category、delete_category、save_collection、delete_collection（作成または更新、商品の追加・削除）
在庫	set_stock_level（絶対値または adjust_by: +10。商品を新しい在庫拠点に追加します）
顧客	save_customer（作成・更新、住所、グループ）、save_customer_group、delete_customer_group
プロモーション	create_promotion（パーセンテージ割引、固定額割引、送料無料。商品、カテゴリー、コレクション、顧客グループ、期間、利用上限に対応）、update_promotion、delete_promotion
価格リスト	save_price_list（販売価格と B2B 価格。バリアントまたは SKU ごとに価格を登録・更新）、delete_price_list
一括操作	bulk_update_prices（パーセンテージ、金額、または 199 や 19.99 のような端数価格での固定価格）、bulk_set_stock（納品、棚卸し）、bulk_update_products（公開、カテゴリー、タグ、コレクション、販売チャネル）。すべて dry_run で事前にプレビューします

汎用

ツール	機能
medusa_request	専用ツールがない操作（予約、交換、税率など）に使用する、任意の Admin API エンドポイント（/admin/ 配下の GET、POST、DELETE）。読み取り専用モードでは GET のみ許可されます。api-keys、users、invites への書き込みは常にブロックされます。MEDUSA_RAW_API=false で無効にできます。

金額は主要通貨単位です（Medusa v2 は補助通貨単位を保存しません）。日付のみ（2026-09-01）は REPORT_TIMEZONE（デフォルトは UTC）で解釈されます。大規模なレポートでは、MCP の進行状況通知が送信されます。

ツールを絞ることで、コンテキストを節約できます。MEDUSA_TOOLSETS=orders,reports を設定すると、指定したグループ（orders、customers、products、catalog、inventory、pricing、promotions、reports、bulk、raw）のみが登録されます（get_store_info は常に有効です）。

ツールのその先

インタラクティブビュー（MCP Apps）。 sales_report と inventory_forecast には HTML ビューが付属しており、MCP Apps に対応するクライアント（Claude、ChatGPT、VS Code、Goose）ではインラインで表示されます。期間ごとの変化を示す KPI タイル、売上チャート、人気商品、割引コード、国別データのほか、ステータスフィルターや調整可能なリードタイムを備え、アシスタントに発注書の作成を依頼するボタンもある、並べ替え可能な補充テーブルが表示されます。ビューはクライアントのテーマと言語（チェコ語または英語）に従い、ツールを呼び出して期間を切り替えます。また、ビュー自体からネットワークリクエストを送信することはありません。それ以外のクライアントでは、同じデータがテキストで表示されます。

プロンプト。 store_briefing、fulfill_orders、restock_plan、handle_return、customer_overview、monthly_report、plan_promotion は、それぞれ一連のワークフローを通じてアシスタントを案内し、何かを変更する前に確認を求めます。引数は自動補完されます（注文番号、顧客のメールアドレス、月）。

リソース。 medusa://store、medusa://orders/{order}、medusa://products/{handle}、medusa://customers/{email} を使用すると、注文や商品を会話に添付できます（例：Claude Code で @ を使用）。最近の注文が一覧表示され、すべてのテンプレートで自動補完が利用できます。

確認。 取り消し、返金、決済処理、削除、一括変更、medusa_request 経由での書き込みなどの破壊的な操作では、クライアントが対応している場合（Claude Code）、MCP elicitation を通じてユーザーに直接、平易な言葉で要約を示して確認を求めます（「注文 1042 の顧客に 249 CZK を返金しますか？」）。ダイアログで拒否すると、何も変更されません。MEDUSA_CONFIRM_DESTRUCTIVE=false にすると無効にできます。ステートレスなリモートコネクターでは elicitation を利用できないため、クライアント独自のツール承認が適用されます。

1. Medusa API キーを作成する

Medusa Admin で Settings → Developer → Secret API Keys → Create を選択します。キー（sk_…）は作成者のユーザー権限で動作するため、個別に無効化できる専用の管理者ユーザーを用意することを検討してください。

2. ローカルでの使用（stdio）

Claude Code / Cowork プラグイン

claude plugin marketplace add trhonpavel/medusa-mcp
claude plugin install medusa@medusa-mcp

プラグインを有効にすると、Claude Code がバックエンド URL と API キーを尋ねます（キーはシステムのキーチェーンに保存されます）。/config で Read-only をオフにするまで、書き込みツールは無効です。サーバーのプロンプトに加えて、プラグインには次の 2 つのスキルが含まれています。

• store-briefing – 前の期間との売上比較、出荷待ちの支払い済み注文、補充が必要な商品
• fulfill-orders – 一覧を確認した後、支払い済み注文の処理と追跡番号の追加を行います

Claude Desktop 拡張機能

最新リリースから medusa-mcp-<version>.mcpb をダウンロードして開くか、Settings → Extensions にドラッグします。Claude Desktop が同じ設定を尋ね、同梱の Node.js を使ってサーバーを実行します。npm run build:mcpb で自分でビルドすることもできます。

手動設定

Claude Desktop – claude_desktop_config.json：

{
  "mcpServers": {
    "medusa": {
      "command": "npx",
      "args": ["-y", "medusa-mcp", "stdio"],
      "env": {
        "MEDUSA_BACKEND_URL": "https://api.example.com",
        "MEDUSA_API_KEY": "sk_...",
        "MEDUSA_READ_ONLY": "true"
      }
    }
  }
}

Claude Code：

claude mcp add medusa \
  -e MEDUSA_BACKEND_URL=https://api.example.com -e MEDUSA_API_KEY=sk_... \
  -- npx -y medusa-mcp stdio

3. リモートコネクター（HTTP + OAuth）

docker run -d --name medusa-mcp -p 127.0.0.1:3000:3000 -v medusa-mcp-data:/data \
  -e MEDUSA_BACKEND_URL=https://api.example.com \
  -e MEDUSA_API_KEY=sk_... \
  -e PUBLIC_URL=https://mcp.example.com \
  -e OWNER_PASSWORD="$(openssl rand -base64 24)" \
  ghcr.io/trhonpavel/medusa-mcp:latest

または、リポジトリをクローンし、.env.example を .env にコピーして、docker compose up -d --build を実行します。

サーバーは 127.0.0.1:3000 でリッスンします。TLS を使うリバースプロキシ経由で公開してください。Claude は Anthropic のサーバーからリモートコネクターに接続するため、エンドポイントは HTTPS でパブリックに到達可能である必要があります。Caddy の例：

mcp.example.com {
    reverse_proxy 127.0.0.1:3000
}

次に、Claude でカスタムコネクターを追加し、URL に https://mcp.example.com/mcp を指定します。Claude は自分自身を登録し（Dynamic Client Registration）、同意ページを開きます。OWNER_PASSWORD を入力して Allow をクリックしてください。

ChatGPT

ChatGPT の設定で developer mode をオンにし、MCP サーバーの URL https://mcp.example.com/mcp と OAuth 認証を使ってアプリ（コネクター）を作成します。ChatGPT も同じ方法で自分自身を登録し、デフォルトの ALLOWED_REDIRECT_HOSTS に含まれている chatgpt.com にリダイレクトします。サーバーは RFC 9207 の iss パラメーターを返すため、ChatGPT は安定したコールバック URL を使用します。

Claude Code

Claude Code では同じ OAuth フローを使用できます。または、MCP_STATIC_TOKEN を設定して静的トークンを使用できます。

claude mcp add --transport http medusa https://mcp.example.com/mcp \
  --header "Authorization: Bearer <MCP_STATIC_TOKEN>"

設定

変数	必須	デフォルト	説明
MEDUSA_BACKEND_URL	はい		Medusa バックエンドの URL
MEDUSA_API_KEY	はい		秘密の API キー（sk_…）
MEDUSA_READ_ONLY		false	読み取りツールとレポートツールのみを登録します
MEDUSA_RAW_API		true	汎用の medusa_request ツールを登録します（読み取り専用の場合は GET のみ）
MEDUSA_TOOLSETS		すべて	登録するツールグループをカンマ区切りで指定します。例：orders,reports
MEDUSA_CONFIRM_DESTRUCTIVE		true	破壊的な操作の前に、MCP のエリシテーションを通じて確認を求めます（対応するクライアントの場合）
AUDIT_LOG			書き込みツールの呼び出しをすべて JSON 行として記録するファイル（常に標準エラー出力にも出力されます）
REPORT_TIMEZONE		UTC	日付フィルターとレポートの区分に使用する IANA タイムゾーン
MEDUSA_TIMEOUT_MS		20000	Medusa リクエストのタイムアウト
PUBLIC_URL	HTTP		このサーバーの公開 HTTPS オリジン（/mcp を除く）
OWNER_PASSWORD	HTTP		同意ページで必要なパスワード
MCP_STATIC_TOKEN			任意の静的ベアラートークン
ALLOWED_REDIRECT_HOSTS		claude.ai,claude.com,chatgpt.com,localhost,127.0.0.1	OAuth クライアントがリダイレクト先として使用できるホスト
TRUST_PROXY		1	Express の trust proxy ― 手前にあるプロキシの数
PORT / HOST		3000 / 0.0.0.0	リッスンアドレス
DATA_DIR		./data	OAuth クライアントとトークンハッシュの保存先
ACCESS_TOKEN_TTL / REFRESH_TOKEN_TTL		3600 / 2592000	トークンの有効期間（秒）

エンドポイント

パス	用途
POST /mcp	Streamable HTTP による MCP（ステートレス）。ベアラートークンが必要です
/.well-known/oauth-protected-resource/mcp	RFC 9728 保護リソースのメタデータ
/.well-known/oauth-authorization-server	RFC 8414 認可サーバーのメタデータ
/register, /authorize, /token, /revoke	OAuth 2.1（DCR、PKCE S256）
POST /oauth/login	同意フォーム（レート制限：IP ごとに 15 分あたり 10 回）
GET /healthz	ヘルスチェック

セキュリティモデル

• Medusa API キーがサーバーの外に出ることはありません。クライアントには、それぞれ有効期間の短いトークン（アクセストークンは1時間、リフレッシュトークンはローテーション付きで30日間）が発行されます。
• 保存されるのはトークンの SHA-256 ハッシュのみで、DATA_DIR/oauth-state.json（モード600）に保存されます。このファイルを削除すると、すべてのクライアントがサインアウトします。
• 動的クライアント登録で受け付けるリダイレクト URI は、ALLOWED_REDIRECT_HOSTS に登録されたものに限られます。そのため、任意のアプリが独自のコールバックを登録してトークンをフィッシングすることはできません。
• 認可コードは1回のみ使用でき、有効期限は5分です。また、PKCE S256 が必須です。
• 同意ページは Content-Security-Policy: default-src 'none' と X-Frame-Options: DENY を送信し、パスワードを一定時間で比較します。
• 書き込みツールには readOnlyHint を設定せず、キャンセル、削除、送金を行うツールには destructiveHint を設定します。そのため、Claude などのクライアントは実行前に承認を求めます。
• medusa_request がアクセスできるのは /admin/… パスのみです。api-keys、users、invites への書き込みは行わないため、プロンプトインジェクションによって新しい認証情報が発行されることはありません。また、MEDUSA_RAW_API=false で無効にできます。
• すべての書き込みツールの呼び出しは、stderr（docker logs）に [audit] {…} として記録されます。記録内容は時刻、ツール、OAuth クライアント（例：「Claude」）、結果、引数です。AUDIT_LOG を設定した場合は、そこにも記録されます。
• クライアントが対応している場合、破壊的な操作では MCP エリシテーションを通じて確認を求めます。一括処理ツールと edit_order はデフォルトでプレビューを表示し、dry_run: false を指定して呼び出すまで変更を行いません。
• add_product_images は、パブリックな http(s) アドレスからのみダウンロードします。プライベート、ループバック、リンクローカルの宛先は、リダイレクト後も含めて拒否されるため、サーバー自身のネットワークへのアクセスには利用できません。
• 対話型ビューは、外部スクリプトやリクエストを含まない自己完結型 HTML で、クライアントによってサンドボックス化された iframe 内にレンダリングされます。
• サーバーの前段にあるリバースプロキシの数を TRUST_PROXY に設定してください。設定しない場合、レート制限で認識されるのはプロキシの IP アドレスのみです。

脆弱性の報告については、SECURITY.md をご覧ください。

開発

npm ci
npm run build   # TypeScript + the MCP Apps views (dist/apps/*.html with the ext-apps runtime inlined)
npm test        # build + tests against a mock Medusa (tools, prompts, resources, views and the full OAuth flow)
npm run smoke   # read-only check against a real Medusa – prints response shapes only, no data
npm run dev     # HTTP mode via tsx

npm run smoke の実行には MEDUSA_BACKEND_URL と MEDUSA_API_KEY が必要です。出力に含まれるのはキーと型のみなので、安心してイシューに貼り付けられます。

ライセンス

MIT