shopware-mcp

理由 · デモ · インストール · ツール · 安全性 · ドキュメント · ウェブサイト · ドイツ語

shopware-mcp のご紹介

Shopware 6 のショップでは、約二百のエンティティが一つの Admin API の背後にあります。アシスタントに「ショップの状態に問題はありませんか？」と尋ねても、正直に答えるには Criteria フィルターを使った検索が七回、技術名による三つのステートマシンの確認、いくつかの集計、そして決してあなたに返してはならない OAuth トークンが必要です。モデルを API に直接接続すれば、すべてにアクセスできてしまいます。その中には、プロンプトに書かれていたからという理由で価格を PATCH する権限まで含まれます。

Model Context Protocol によって、「モデルに実際のツールを使わせる」ことは設定を一行変更するだけで実現できるようになりました。しかし、ショップにとって優れたツールとは何かについては何も定めていません。二百のエンティティのうち火曜日の朝に重要なものは何か、「注文が停滞している」とはどういう状態なのか、在庫調整を送信する前に表示すべきことなどです。

shopware-mcp はその層です。 ホストとは MCP で、ショップとは Admin API で通信する小さなサーバーです。Shopware に精通しているため、管理画面で午後いっぱいかかっていた作業を一度の呼び出しで済ませられます。また、注文が来なくなったことにも気づき、原因を探るために顧客と同じ方法でチェックアウトを試します：

動作を見る

注文がない6時間と、その理由。 日曜日の夜。パルスは、注文が常に3～7件あった過去8回の日曜日の同じ時間帯と静けさを比較し、偶然である可能性を約170分の1と算出します。続いてエージェントは、顧客のように商品を購入しようとし、ストアフロントがメンテナンスモードであることを見つけます。注文も変更も行われていません。

顧客が見るチェックアウト。 スイスの顧客が、コードが使えないと伝えます。Shopware独自のStore APIを通じて一時的なカートを作成すると、両方の問題が一度に明らかになります。そのチャネルではスイスが対象国ではなく、コードのプロモーションは8月に終了していました。続いて検索で、商品が表示されない理由も明らかになります。

毎朝、1ページ。 shopware-mcp brief --html brief.html を実行すると、パルス、監査、直近7日間の情報を、外部から何も読み込まず、読者のダークモードにも対応した自己完結型の1ページとして出力します。cronから実行し、--slack を指定するとチャンネルに1段落の要約を投稿できます。 実物を見る。

最小権限を1つのコマンドで。 shopware-mcp setup は管理者として一度ログインし、実際のショップで測定した、ツールに必要な権限だけを持つロールと、管理者ではないインテグレーションを作成します。権限は推測ではありません。シークレットは一度だけ表示し、両方を検証して、ホスト設定を出力します。アップグレード後に再度実行すると、キーをそのまま維持しながらロールを最新の状態に更新します。

_{音声なしの30秒動画：ウェブサイトで見るか、MP4を開く。docs/video/からレンダリングされています。}

このページに掲載されている録画はすべて、デモ用データを生成したShopware 6.7.13のテストショップに対するサーバーの実際の出力を、docs/demo/内のトランスクリプトから再生したものです。ツールの呼び出しと結果は原文のまま、画面に収まるよう短縮しています。文章は、MCPホストがそれらを使って生成したものです。

質問1つ、呼び出し1回。 支払い済みの注文3件がまだ出荷待ちで、ストアフロントはメンテナンス中、夏のプロモーションは8月を過ぎても有効なままです。回答では注文番号と金額を示し、安全な次の手順を提案します。

ショップ自身が計算した数値です。 合計、チャネル、状態、月ごとの タイムライン、8か月間のトップ商品を、1回の呼び出しで取得できます。注文を 1件ずつ確認する必要はありません。Shopware の集計機能が処理します。

そのためのツールがない？ スキーマを使えます。 メーカー専用の ツールはありません。エージェントはエンティティのスキーマを読み取り、 mediaId を見つけて、それを使って絞り込みます。同じ方法で、カスタム エンティティも含め、ほかのすべてのエンティティにアクセスできます。

書き込み内容は、実行前に確認できます。 --allow-write を指定すると、 在庫修正では、実際に送信する予定のリクエストが返されます。明示的に dryRun: false を指定した場合のみショップが変更され、結果は Shopware から再取得されます。

出荷してから、その結果を確認できます。 配送ステータスの変更は2つの リクエストで行われ、送信前に表示されます。まず配送に追跡コードを設定し、 次に状態を変更します。その後、注文の履歴には変更内容、状態、実行者が記録されます。

ひとこと伝えるだけで、商品と発売コードを作成できます。 product_create は ショップのデフォルト税率を選び、正味価格を算出して、ドライランでその内容を 示します。プロモーションは無効な状態で作成されるため、確認前にコードが 公開されることはありません。

返信も含めたレビューのモデレーションです。 2件のレビューが承認待ちです。 スパムは非表示のままにし、苦情にはショップからの公開返信を添えて承認します。 モデルが管理画面を操作する必要はありません。

売上だけでなく、お客様も把握できます。 グループ別の新規アカウント数、 注文したお客様の数と再訪したお客様の数、ゲストの割合、期間内の売上に占める 割合を添えた上位のお客様を、前の期間との比較とともに確認できます。

プラグインが増えるほど、エージェントの機能も広がります。 コアツールは すぐに利用できます。拡張機能の検索はバックグラウンドで完了し、4つのツールが 追加されると、ホストにリストの更新を通知します。これでコンプライアンスに関する 質問にも回答できます。

在庫が危機に陥る前に再発注できます。 stock_forecast は1回の集計で 6か月分の注文明細を読み込み、現在の在庫と照合します。そして商品ごとに、 在庫があと何日分あるか、いつゼロになるか、どれだけ発注すべきかを示します。 このうち9商品はすでに在庫切れを起こしており、今日はまだ問題のない2商品も、 10月には在庫切れになる見込みです。

同じ監査を、ホストなしで。 shopware-mcp audit は結果を Markdown で出力し、重大な問題がある場合はゼロ以外の終了コードで終了します（--fail-on warning を指定すると、何か問題があれば終了します）。cron に登録してメールを確認することも、CI に組み込んでジョブを失敗させることもできます。数値については shopware-mcp report でも同じことができます。

運用プラグインを導入したショップには、運用エージェントを。 FroshTools は、多くの Shopware ホスティング事業者がインストールするオープンソースのツールボックスです。これがあると、プラットフォームのヘルスチェック、ワーカーを含むメッセージキュー、依存関係のアドバイザリーという3つのツールが追加されます。エージェントは、検索結果が古いのか、ワーカーが停止しているのかを見分けます。

56件の請求書を、3件ずつ。 order_documents_bulk_create は、請求書がまだ作成されていない支払い済み注文を古い順に見つけ、作成する前に実行されるリクエストを1つ表示します。各注文は書き込み予算に計上されます。次に scheduled_tasks_list が、バックログがどのように増えたのかを説明します。33件中31件のタスクが期限超過で、一度も実行されておらず、スケジューラーも動作していません。tag_assign は、その過程でタグを作成し、チーム用に注文へ割り当てます。

エージェントが気づく前に把握しましょう。 shopware-mcp doctor は、連携が読み取り可能な項目を調べ、可能な場合はロールの書き込み権限を確認し、ツールごとに不足している権限を示します。管理者にはチェックマークがずらりと並び、サポートデスクのロールには付与すべき権限が正確に示されます。

含まれるもの

対象ユーザー

• ショップを運営していて、管理画面をクリックして回る代わりに、質問で情報を得たい方。滞留中の注文、在庫僅少、先月の数値などを、それぞれ1つのプロンプトで確認できます。
• 代理店を運営していて、多くのショップを担当している方。ここで提供する基本機能は、1サーバーあたり1ショップに対応します。複数ショップ対応で監査機能を備えたホスト版は、作者がクライアント向けに構築しています（オープンコアを参照）。
• Shopware プラグインを開発していて、カスタムエンティティを今すぐエージェントから利用できるようにし、後から独自のツールを登録したい方。前者はentity_searchで、後者はsrc/extensions/内にファイルを1つ追加することで実現できます。
• エージェントを開発していて、適切に動作する MCP サーバーを求める方。簡潔な出力、正確な合計値、ドライラン、スキーマに予期しない変更がないことを重視する方。

60秒で始める

1. setupでインテグレーションを作成します。管理者として一度ログインします（パスワードは保存されません）。ツールに必要な権限だけを持つ読み取り専用ロールと、そのロールを使うインテグレーションを作成し、両方を検証して、ホスト設定を表示または書き込みます。

npx shopware-mcp setup --url https://shop.example.com --user admin --for claude-desktop --write

書き込みツールには--allow-writeを、shop_settingsには--settingsを追加します。--dry-runを指定すると、ロールの権限が最初に表示されます。アップグレード後は同じコマンドを再実行してください。ロールが更新され、キーはそのまま維持されます。自分で操作する場合は、設定 → システム → インテグレーションでインテグレーションを作成し、ロールを割り当てて（権限を参照）、手順2に進んでください。

2. または、ウィザードで既存の認証情報をテストし、ホスト設定を書き込むこともできます。

npx shopware-mcp init                  # asks for URL, key and secret, tests them, prints the config
npx shopware-mcp init --for claude-desktop --write   # or merges it into the host's config file
npx shopware-mcp doctor                # which tools can this integration use, and what is missing
npx shopware-mcp audit --fail-on warning   # the shop audit as Markdown, exit 1 when something is off
npx shopware-mcp report --interval week    # the sales report of the last 30 days as Markdown
npx shopware-mcp brief --html brief.html   # pulse, audit and the last 7 days as one HTML page

または、サーバーを手動で実行します。

export SHOPWARE_URL=https://shop.example.com
export SHOPWARE_CLIENT_ID=SWIA...
export SHOPWARE_CLIENT_SECRET=...

npx shopware-mcp                       # stdio (default)
npx shopware-mcp --http --port 3333    # Streamable HTTP on http://127.0.0.1:3333/mcp
npx shopware-mcp --allow-write         # also register the guarded write tools

3. ホストに接続します（またはinit --writeに任せます）。

{
  "mcpServers": {
    "shopware": {
      "command": "npx",
      "args": ["-y", "shopware-mcp"],
      "env": {
        "SHOPWARE_URL": "https://shop.example.com",
        "SHOPWARE_CLIENT_ID": "SWIA...",
        "SHOPWARE_CLIENT_SECRET": "..."
      }
    }
  }
}

claude mcp add shopware \
  -e SHOPWARE_URL=https://shop.example.com \
  -e SHOPWARE_CLIENT_ID=SWIA... \
  -e SHOPWARE_CLIENT_SECRET=... \
  -- npx -y shopware-mcp

{
  "mcpServers": {
    "shopware": {
      "command": "npx",
      "args": ["-y", "shopware-mcp"],
      "env": {
        "SHOPWARE_URL": "https://shop.example.com",
        "SHOPWARE_CLIENT_ID": "SWIA...",
        "SHOPWARE_CLIENT_SECRET": "..."
      }
    }
  }
}

docker run --rm -p 3333:3333 \
  -e SHOPWARE_URL=https://shop.example.com \
  -e SHOPWARE_CLIENT_ID=SWIA... -e SHOPWARE_CLIENT_SECRET=... \
  ghcr.io/bnymndev/shopware-mcp

4. 質問してみましょう。最初に役立つ質問は、通常「ショップは問題なく運営されていますか？」です。

何でも聞いてください

フィルターをひと目で確認

すべての検索ツールで同じ filter 配列を使用します。各要素は Shopware の Criteria フィルターです。

{ "type": "equals",    "field": "active",                                    "value": true }
{ "type": "range",     "field": "stock",                                     "value": { "lt": 5 } }
{ "type": "range",     "field": "orderDateTime",                             "value": { "gte": "2026-06-01" } }
{ "type": "equals",    "field": "transactions.stateMachineState.technicalName", "value": "paid" }
{ "type": "contains",  "field": "name",                                      "value": "shirt" }
{ "type": "equalsAny", "field": "id",                                        "value": ["…", "…"] }
{ "type": "equals",    "field": "manufacturer.name",                         "value": "Acme" }

Admin API でフィルターできる項目は、関連付けも含めてすべてここでもフィルターできます。customFields、ean、weight など、コンパクトな出力に含まれない生のフィールドが必要ですか？fields: ["customFields", "ean"] を渡すと、すべての項目に追加されます。別の言語でショップを閲覧しますか？SHOPWARE_LANGUAGE_ID を設定してください。詳しくはチートシートをご覧ください。

ツール

リソース：shopware://shop、shopware://sales-channels、shopware://order/{orderNumber}、 shopware://product/{productNumber}。プロンプト：order_summary、low_stock_report、weekly_review。

プラグイン対応ツール

サーバーは起動時に、バックグラウンドでショップにインストール済みかつ有効な拡張機能を問い合わせ、認識している拡張機能向けのツールを追加登録します。応答しないショップでは、コアツールのみがそのまま利用されます。--no-extensions を指定すると、この仕組み全体が無効になります。

現在、2 つのパックが提供されています。オープンソースの運用プラグインである FroshTools は、frosh_health（プラットフォームの健全性とパフォーマンスのチェック）、frosh_queue（メッセージキューのトランスポート、待機中のメッセージ、ワーカー）、frosh_composer_audit（依存関係のアドバイザリ）を追加します。いずれも読み取り専用で、プラグイン独自のメンテナンス操作は呼び出しません。Merqo は、merqo_health、merqo_einvoice_inbox、merqo_returns_search、merqo_abandoned_carts を追加します。プラグインを導入していないショップにそのツールが表示されることはなく、コアツールにも影響はありません。他のベンダーの拡張機能への対応は、インストール済みのプラグインに対してテストしたうえで、src/extensions/ にファイルを 1 つ追加するだけです。各パックには、プラグインのルートに必要な ACL 権限が記載されており、そのプラグインがインストールされていれば、shopware-mcp setup が権限を付与します。プルリクエストを歓迎します。

安全性

• デフォルトでは読み取り専用です。 --allow-write（または SHOPWARE_MCP_ALLOW_WRITE=true）を指定しない限り、書き込みツールは登録されません。エージェントは、呼び出せないツールを見つけることはできません。
• すべての書き込みは、まずドライランで実行されます。 stock_set から tag_assign まで、15 個すべての書き込みツールはデフォルトで dryRun: true となり、{ dryRun: true, wouldSend: { method, url, body } } を返します。1 回の呼び出しで複数のリクエストが必要な場合は、リストを返します。実際に書き込んだ場合は、再取得したエンティティを返します。
• 書き込み予算があります。 SHOPWARE_MCP_MAX_WRITES=20 を設定すると、プロセス内で 21 回目の実書き込みが WRITE_BUDGET_EXHAUSTED により拒否されます。ドライランは予算を消費しません。どのプロンプトでも上限を引き上げることはできません。
• 書き込み範囲は限定されています。 product_update が変更するのは、名前、説明、有効状態、および 1 つの通貨の価格です。product_create が作成するのはシンプルな商品だけです。product_cover_set は画像を 1 枚追加します（JPEG、PNG、WebP、GIF、AVIF に対応し、SVG には対応しません）。画像はショップ自体がダウンロードします。promotion_create はカート割引を 1 つ作成し、指定がなければ無効状態になります。customer_update が変更するのは有効フラグとグループです。状態遷移ツールは状態マシンを進めるだけで、金銭が移動することはありません。ドキュメントは Shopware 独自のジェネレーターで作成され、このサーバーから送信されることはありません。order_documents_bulk_create は 1 回の呼び出しで最大 50 件を作成し、注文 1 件につき書き込み予算を 1 回だけ消費します。tag_assign は名前でタグを追加または削除し、レコードのそれ以外の部分には触れません。削除は行いません。これ以外の書き込みはできません。
• カートのシミュレーションは注文ではありません。 checkout_simulate と storefront_search は、Shopware 独自の管理プロキシ経由で Store API を呼び出し、訪問者が保持していないランダムなコンテキストトークンを使用します。注文ルートは呼び出されず、カートはその後削除されます。残るのは、Shopware が自動的に期限切れにするコンテキスト行のみです。顧客としてシミュレーションしても、その顧客自身のセッションや保存済みカートには影響しません。放棄されたカートのメール通知など、保存済みカートに反応する拡張機能には、シミュレーションしたカートもその顧客のカートとして認識されます。そのため、実在する顧客としてシミュレーションするのは、その動作に問題がない場合に限ってください。
• デフォルトで最小権限です。 shopware-mcp setup は、ほかの権限を何も持たないロールに対して各ツールが必要と測定された権限だけを付与し、管理者権限は付与しません。ツールの範囲を超える権限が 2 つあり、要求しない限り付与されません。システム設定全体の読み取り（--settings。SMTP パスワードや決済キーを含みます）と、拡張機能のインストール（--plugin-updates）です。セットアップが変更するのは自身で作成したロールのみで、追加または削除する権限をすべて明示し、ほかの処理で失敗する可能性が生じる前に新しいシークレットを表示します。管理者パスワードは、https 経由で 1 回ログインするために使用するか、このマシンに限って plain http で使用し、保存されることはありません。
• 読み取り結果から機密情報を除去します。 entity_search はすべてのペイロードからパスワード、キー、トークン、ハッシュを除去し、認証情報やシステム内部情報を保持するためのエンティティ（ユーザー、インテグレーション、ACL ロール、アプリ、システム設定）へのアクセスを拒否します。
• シークレットはどこにも出力されません。 認証情報が出力、ログ、エラーメッセージに含まれることはありません。ログは stderr にのみ出力され、より詳細なログを要求しない限り、レベルは error です。
• テレメトリはありません。 サーバーが通信する相手は、ショップとホストのみです。それ以外との通信はありません。
• HTTP トランスポート。 SHOPWARE_MCP_HTTP_TOKEN を設定すると、/mcp へのすべての呼び出しにベアラートークンが必要になり、定時間比較で照合されます。トークンを設定しない場合は、localhost（デフォルト）にバインドするか、認証を行うリバースプロキシの背後に配置してください。トークンなしでサーバーに外部から到達できる場合、警告が表示されます。
• リクエストにはタイムアウトがあります。 ショップから応答がなくなった場合でも、セッション全体ではなく 1 リクエストあたり 30 秒でタイムアウトします（SHOPWARE_MCP_TIMEOUT_MS）。

問題を見つけましたか？ SECURITY.md をご覧ください。

設定

CLI フラグは環境変数より優先されます：--allow-write、--max-writes <n>、--no-extensions、--http、--port <n>、--host <addr>、--log-level <level>。コマンドは setup、doctor、init、brief、audit、report です。npx shopware-mcp --help で各コマンドのオプションを確認できます。

インテグレーションには、ツールが操作するエンティティへの読み取り権限と、書き込みツールへの書き込み権限が必要です。shopware-mcp setup は必要な権限のみを付与します。開発用ショップでは Administrator が手早い方法です （必要な権限）。

設計原則

1. 独自の用語ではなく、Shopware の用語を使います。 フィルター、フィールドパス、状態名、エンティティ名には Shopware のものを使います。ツール呼び出しは実行される Admin API リクエストと同じように読めるため、Shopware の開発者が別の用語集を参照する必要はありません。
2. デフォルトではコンパクトに、必要に応じて完全な情報を返します。 アイテムには、モデルが推論やページングに必要な情報が含まれます。生のフィールドは fields で、追加の行は page で取得でき、長いテキストはそのまま出力せず切り詰めます。
3. 読み取りは自由に、書き込みは明示的にします。 書き込みツールは要求された場合にのみ使え、デフォルトではドライランを実行して、正確なリクエストを返します。ショップに変更が反映される前に、モデルはその結果を確認できます。
4. 計算はショップに任せます。 合計、時系列、売上上位商品は、ページをまたいでクライアント側で合算するのではなく、正確な件数を含む Shopware の集計結果を使います。
5. ベンダーに依存しないコア。 拡張パックはそれぞれ独立したファイルに置かれ、ショップに該当する拡張機能がある場合にのみ登録されます。また、コアツールの動作を変更することはありません。テレメトリーも、外部への情報送信もありません。

個々の選択の理由については、docs/decisions.md を参照してください。

ドキュメント

オープンコア

このリポジトリのすべては MIT ライセンスであり、今後もそのままです。対象は、1 つのショップ、1 人の運営者、対話形式での利用です。

同じ作者が、EU コンプライアンスと日々の運用に対応する Shopware 拡張機能の商用スイートである Merqo も開発しています。このサーバーはそれらを検出して対応するツールを追加しますが、利用に必須ではなく、コアツールの動作も変わりません。

大規模に運用する代理店やマーチャントには、通常、さらに多くの機能が必要です。そこで、クライアント向けに以下の開発と運用を行っています。

• マルチショップ：ショップごとの認証情報と権限を使い、1 つの MCP エンドポイントから数十のショップに振り分けます
• 監査証跡付きホスティング：すべてのツール呼び出しについて、実行者、内容、日時を記録し、ロールベースのアクセス制御と SLA を提供します
• 一括操作と移行：価格と在庫の一括更新、カタログのインポート、安全なロールバック
• カスタムエージェントと Shopware プラグイン：お使いの ERP、PIM、またはサポートデスクに合わせたワークフロー

ご興味があれば、consulting ラベルを付けて Issue を作成するか、github.com/bnymnDev からご連絡ください。shopware-mcp を本番環境で利用していて、今後もメンテナンスを続けてほしい場合は、スポンサーになることで支援できます。

ソースからのビルド

pnpm install
pnpm dev          # stdio server via tsx
pnpm test         # vitest + msw-mocked Admin API
pnpm build        # tsup → dist/ (npm) and dist/bundle/ (self-contained)
pnpm pack:mcpb    # Claude Desktop bundle → shopware-mcp.mcpb
pnpm inspect      # MCP Inspector against dist/
pnpm docs:tools   # regenerate docs/tools.md and the tool tables in both READMEs
pnpm docs:demos   # re-render the recordings in docs/demo/ from their transcripts

実際の Shopware（dockware/dev、または任意のショップ）に対するエンドツーエンドテストは、pnpm test:e2e で実行できます。CONTRIBUTING.md を参照してください。

ステータス

v0.8。このページに記載されている機能はすべて実装済みで、モックの Admin API レスポンスを使ったユニットテストでカバーされ、実際の Shopware に対するエンドツーエンドテストも毎晩実行されています。上記の録画は Shopware 6.7.13 でのもので、6.6 もサポートしています。

意図的に含めていない機能：HTTP トランスポートのユーザー管理（静的トークン 1 つ、またはプロキシ）、マルチショップへの振り分けと監査証跡（商用機能）、およびサポートデスクやショップマネージャーが通常の日に必要とする 15 個を超える書き込みツール。

追加案として適しているもの：拡張パックの追加、カートのエラーをわかりやすい言葉で説明する機能の追加、products_search の使用例ギャラリーなどです。最初の Issue におすすめから始めるのもよいでしょう。

ライセンス

MIT

_{shopware-mcp が管理画面では答えられなかった質問に答えてくれたなら、スターを付けると、次のショップがこのプロジェクトを見つけやすくなります。}