Google E-commerce (GA4, Search Console, Merchant Center, Ads)

google-ecommerce-mcp

オンラインショップが判断に使うデータのための MCP サーバーです。1店舗でも複数のクライアントでも利用できます。GA4、Search Console、Merchant Center、Tag Manager、Indexing API、PageSpeed、広告プラットフォームの Google Ads、Meta Ads、ChatGPT Ads、さらに Meta のピクセル、カタログ、Instagram、ページに対応しています。デフォルトでは読み取り専用で、承認した変更を管理された形で準備することもできます（キャンペーンの一時停止、予算の変更、サイトマップの送信、ワークスペースへのタグ追加など）。

AI アシスタントに「今月のオーガニックトラフィックはどのくらいでしたか？」「Merchant Center で不承認になっている商品はどれですか？」「サイトで GA4 が二重に読み込まれていますか？」「先月、各広告プラットフォームはどんな成果を報告していて、GA4 はどう報告していますか？」と尋ねると、あなた自身のアカウントの情報に基づいて回答します。初期設定では、読み取りとレポートのみを行い、何も変更しません。クライアントの書き込みを有効にすると、アシスタントは変更をプランとして提案できます。承認するまで何も送信されず、費用が発生する操作には、チャット外のターミナルでの承認が必要です。

既存の MCP サーバーでは GA4、Search Console、Merchant Center をまとめて扱えなかったため、3D プリント製のテーブルトップゲーム用地形を販売する小さなフランスのショップ、MoonEyesが開発しました。

書き込みはデフォルトで無効であり、実際のアカウントでは一度もテストされていません。 このバージョンには書き込みツールが含まれていますが、各プラットフォームのドキュメントをもとに作成した偽の応答を使ったオフラインテストのみを実施しました。有効化はクライアントごと、プラットフォームごとのオプトイン方式です。作成されるものは常に一時停止状態で、取り除けないリスクもあります（たとえば、Google Ads のトークンや ChatGPT Ads のキーには読み取り専用の制限を設定できません）。有効にする前にdocs/SECURITY.mdとdocs/WRITE.mdを読み、まずテストアカウントでお試しください。初めての方はdocs/QUICKSTART.mdをご覧ください。10分で最初のクライアントを設定できます。

有料メディアのコネクターは新しく、オフラインテストのみ実施済みです。 Google Ads、Meta Ads、ChatGPT Ads のツールは、各プラットフォームのドキュメントをもとに作成した偽の応答を使って確認しました。実際の広告アカウントではまだ実行していません。最初の数値は各プラットフォームの画面と照らし合わせてください。詳細：docs/ADS.md。

ドキュメント

ページ	内容
クイックスタート	10 分で最初のクライアントを設定：4 つのコマンド
複数のクライアント	クライアントレジストリ clients.json、クライアントごとのシークレット、分離、代理店の例
読み取りパイロット	書き込みを無効にしたまま、1 つのクライアントで実施するパイロット：アクセスチェックリスト、手順、書き込みが無効であることの確認方法、取り消し方法
書き込み：計画、承認、適用	5 つの手順で書き込みを有効化、3 つの完全な例、すべてのロック、すべての拒否とその解決方法
アーキテクチャ	コンポーネント、書き込み経路、ツール呼び出しの手順、設計上の選択、シーケンス図
ツールリファレンス	すべてのツール（82 個）：パラメーター、出力、質問の例
セットアップ：サービスごとに順番に	必要なサービス、アクセスチェックリストとクライアント向けメールテンプレート、doctor による確認を含むインストール順序、取り消し
クライアントレポート	月次レポートの計画、KPI の計算式、report コマンドとその入力仕様
ガイド付きインストールプロンプト	手順を追って案内してもらうために Claude に貼り付けるプロンプト（フランス語）
サードパーティに関する通知	OpenGSC から移植したコード（MIT）、他のオープンソースプロジェクトから着想を得た内容（コードはコピーしていません）
広告プラットフォームの簡単セットアップガイド	Google Ads、Meta Ads、ChatGPT Ads：クライアント向けメール、番号付きの手順、ID、確認、取り消し
有料メディアガイド	Google Ads、Meta Ads、ChatGPT Ads：前提条件を順に説明、GAQL のルール、エラー、未テストの項目
Google Cloud のセットアップ	OAuth クライアント、有効にする API、各 ID の確認場所
セキュリティモデル	書き込みによる変更内容、実際のガードレール、既知の制限、スコープ、トークンの保存、取り消し方法
トラブルシューティング	これまでに発生したすべてのエラーとその解決方法
プロンプトの例	ユースケース別の、効果的な質問
クライアント設定	Claude Desktop（ショップ 1〜2 店舗）、Claude Code

このプロジェクトを選ぶ理由

• 全体像を把握できる単一のサーバー。 トラフィックと売上（GA4）、自然検索（Search Console）、商品フィード（Merchant Center）、トラッキング設定（Tag Manager）、サイトの速度、広告プラットフォームが配信したとする実績を扱います。他のMCPサーバーがカバーするのは、これらのうち1つか2つです。
• 複数のクライアントを分離して管理。 代理店はクライアントをそれぞれ一度登録します（IDはファイルに、シークレットはOSのキーリングに保存）。すべての呼び出しでクライアントを指定し、別のアカウントIDが指定された場合は拒否されます。また、1つのサーバープロセスを特定のクライアント専用にできます。
• 読み取りはデフォルトで許可、書き込みはリクエストに応じて管理。 読み取りにはプラットフォームごとの許可リストを使い、書き込みエンドポイントはありません。書き込みは、クライアントごと、プラットフォームごとに有効化するまで無効です。有効化した後も、書き込みは1つの手順を通じてのみ実行されます。計画（差分、ドライラン、署名付きトークン）、ユーザーの承認（費用が発生するもの、取り消せないもの、個人データに関わるものはターミナルで承認）、適用、そしてジャーナル記録です。新規作成は一時停止されており、このバージョンでは有効化、削除、公開はできません。
• シークレットを安全に管理。 Google トークンはOSのキーリング（Windows Credential Manager、macOS Keychain、Secret Service）に保存されます。書き込み可能なスコープを持つGoogle Adsトークンは、別のキーリング項目として保存されます。MetaとChatGPT Adsのシークレットは、非表示のプロンプトからOSのキーリングに保存されます（環境変数も使用できます）。コマンドラインやURLに入力することはありません。
• モデルが正しく読み取れる回答。 レポートには上位の行と全体の合計、各指標の単位と定義、アカウントのタイムゾーンで解決した日付（直近の日付はまだ変わる可能性があることを示すフラグ付き）、各広告プラットフォームで使用されたアトリビューション期間が含まれます。
• 把握できないことも正直に伝えます。 広告プラットフォームごとにコンバージョンの数え方は異なります。足し合わせるべきでない数値を合算するのではなく、すべての回答でそのことを明示します。
• 第三者を介しません。 リクエストはお使いのマシンからGoogle、Meta、OpenAIへ直接送信されます。MoonEyesのサーバーを経由することはありません。

比較

各プロジェクトの公開ページを2026-10-18に確認しています。状況は頻繁に変わるため、判断する前に最新情報を確認してください。

プロジェクト	ライセンス	対象範囲	書き込み
googleanalytics/google-analytics-mcp（公式）	Apache-2.0	GA4	読み取りのみ
googleads/google-ads-mcp（公式）	Apache-2.0	Google Ads	読み取りのみ
Meta Ads MCP（公式、Metaがホスト、ベータ版）	クローズド	Meta Ads	可能（Metaがホスト）
pipeboard-co/meta-ads-mcp	BUSL	Meta Ads	可能
stape-io/google-tag-manager-mcp-server	Apache-2.0	Tag Manager	読み取りと書き込み
RoyAzran/mcp-ads	MIT	12以上の広告・分析プラットフォーム	ドキュメントを参照
このプロジェクト	MIT	GA4、Search Console、Merchant Center、Tag Manager、PageSpeed、Google Ads、Meta Ads、ChatGPT Ads	デフォルトでは無効。計画、承認、ジャーナル記録、ロールバックに対応。実アカウントでは未テスト

このプロジェクトが適しているのは、複数のショップやクライアントを1つのセルフホスト可能なサーバーから管理し、変更を差分で確認して承認してから送信したい場合です。Googleの製品を1つだけ使う場合や、インストール不要のホスト型サービスが必要な場合は、上記の公式サーバーのほうが適しています。

質問できること

各ケースでは、質問、アシスタントが通常呼び出すツール、得られる情報、それをもとに判断できることを説明します。判断するのはあなたです。デフォルトでは、サーバーはデータを表示するだけで何も変更しません。また、サーバーが変更案を準備した場合も、実行にはあなたの承認が必要です。そのまま貼り付けて使えるプロンプトは、examples/PROMPTS.md にあります。

トラフィック、検索、フィード、トラッキング

1. 訪問や売上はどこから来ていますか？ 「今月と先月のチャネル別セッション数、購入数、収益。」 ツール：ga4_report。収益を生み出すチャネルと、訪問だけをもたらすチャネルがわかります。判断できること：次の1時間や1ユーロをどこに投じるか。
2. あと少しで1ページ目に届く検索キーワードはどれですか？ 「表示回数が100回を超え、検索順位が5〜15位のクエリと、それぞれのランディングページ。」 ツール：gsc_performance。すでに表示回数を獲得しているものの、クリックが少ないページがわかります。判断できること：どのタイトル、説明文、内部リンクを最初に書き直すか。
3. 不承認の商品で、まだ訪問があるのはどれですか？ 「Merchant Center で不承認となった商品のうち、オーガニッククリックがまだあるもの。」 ツール：merchant_product_issues、gsc_performance。まだ訪問されているページに影響するフィードのエラーがわかります。判断できること：他の商品より先に修正する商品。
4. トラッキングは信頼できますか？ 「GA4 が二重に読み込まれていませんか？購入タグは1回だけ発火していますか？ワークスペースは公開中のバージョンと同じですか？」 ツール：gtm_inventory、ga4_realtime。購入やページビューが二重計上されている可能性や、未公開の変更があるかどうかがわかります。判断できること：公開するか、重複タグを削除するか、そのままにするか。
5. リニューアルの準備。 「収益とオーガニッククリックを獲得しているランディングページはどれですか？どのページに301リダイレクトが必要ですか？現在の速度の基準値はどれくらいですか？」 ツール：ga4_report（ディメンション landingPage）、gsc_performance、gsc_moves、gsc_opportunities、gsc_inspect_url、pagespeed。維持すべきURL、計画が必要なリダイレクト、変更後と比較するための変更前の数値がわかります。判断できること：リダイレクトマップと、変更してはならないもの。

有料メディア（以下のコネクターが必要です）

6. 広告プラットフォームの数値は GA4 と一致していますか？ 「先月の Google Ads、Meta、ChatGPT Ads のコンバージョン数を GA4 と比較してください。」 ツール：ads_overview、ga4_report。各プラットフォームの申告値と GA4 の記録値にどれほど差があるかがわかります。判断できること：どの数値をより慎重に扱うべきか、各プラットフォームのインターフェースでどのアトリビューション設定を確認するか。
7. 各プラットフォームの ROAS を実際の収益と並べるとどう見えますか？ 「同じ日付のプラットフォーム別申告 ROAS と GA4 の収益。」 ツール：ads_overview、ga4_report。各プラットフォームが申告する価値と、GA4 が記録した収益がわかります。サーバーは全体の広告費用対効果（MER）を計算しないため、2つの値は自分で比較します。判断できること：申告値を総合的に見て妥当かどうか。
8. 購入が記録されていないのに費用が発生しているキャンペーンはどれですか？ 「費用が発生しているものの、購入がアトリビューションされていないキャンペーンと、同じキャンペーン名について GA4 に表示されている内容。」 ツール：gads_performance または meta_insights、ga4_report（ディメンション sessionCampaignName）。プラットフォームにも GA4 にも売上が表示されていないのに、費用が発生しているキャンペーンがわかります。判断できること：広告プラットフォーム上で、自分でキャンペーンを停止するか、トラッキングを修正するか、様子を見るか。

プラットフォームの数値が異なる理由。 Meta のデフォルトは7日間のクリック＋1日間のビュー、ChatGPT Ads のデフォルト（このサーバーが標準でリクエストする設定）は30日間のクリック＋1日間のビュー、Google Ads のデフォルトは各コンバージョン アクションの設定です。プラットフォームごとに異なる日付にコンバージョンを紐付け、同じ注文をそれぞれ独立してカウントし、訪問者が Cookie を拒否した場合（Consent Mode）にはモデル化されたコンバージョンを報告することがあります。GA4 にも独自のしきい値があります。ツールではわからないこと：広告が売上の原因となったかどうか（増分効果）、実際の注文数（ショップのバックオフィスは読み取りません）、同意率。

実際の調査結果

MoonEyes自身のアカウントと、匿名化した小規模事業者1社のアカウントから得られた調査結果です。データから明らかになった問題の例であり、結果を保証するものではありません。それぞれに対象期間と測定方法を記載しています。個別の事例であり、ベンチマークではありません。また、数値の改善と同時に行われた修正は相関関係を示すもので、保証ではありません。これらの数値の根拠となる生データのエクスポートはリポジトリに保存されていないため、ここから再検証することはできません。

調査結果	期間	測定方法
Merchant Center：商品リスティング2,544件のうち112件が不承認でした。「重量が大きすぎる」という不承認224件は、フィードのグラムからキログラムへの単位変換ミスが原因でした（パックが約2トンとして送信されていました）。現在は修正済みです。商品名が原因の「アルコール飲料」という誤った不承認が1件あり、商品3点の名前を変更すると解消しました。Google for WooCommerce プラグインが作成した重複フィードソースも削除しました。	2026年6月1～2日の監査（MoonEyes）	Merchant Centerの商品ステータスとフィードソース（merchant_product_issues と merchant_data_sources が返すものと同種のデータ。監査のエクスポートはこのリポジトリに保存されていません）
購入が二重にカウントされていました。同じGoogle AdsのコンバージョンIDが、WordPressのスニペットとGoogle Tag Managerの両方から送信されていました。スニペットを無効にし、GTMを唯一の送信元としました。配信されたHTML内のgtagの出現回数は、あるページで18回から12回に、別のページで6回から3回に減少しました。	2026年6月2日（MoonEyes）	配信されたHTML内のgtagの出現回数をカウント
GA4でコンバージョンが過剰にカウントされていました。電話、メール、問い合わせのクリックがキーイベントとしてマークされていたため、201セッションに対して265件のコンバージョンが記録されていました。	2026年6月1～2日の監査前28日間（MoonEyes）	GA4のコンバージョン数とセッション数（ga4_key_event_audit が自動化するチェック）
Search Console：クリック数0件、送信済みURL 708件、インデックス登録済みURL 0件。インデックス登録の作業項目に着手した時点の数値です。	2026年6月1日（MoonEyes）	Search Console
Google Adsアカウントでは、実際の予約が10件だったのに、コンバージョン96件、1件あたり2.16ユーロと表示されていました。実際の費用は207.57ユーロ ÷ 10 = 予約1件あたり約20.76ユーロで、表示値の9.6倍でした。原因は、目標CPA入札戦略のもとで page_view とページイベントがキーイベントとしてマークされていたことでした。予約イベントだけを残して修正しました。匿名化した小規模な地域サービス事業者の事例です。	2026年8月26日～9月22日	Google Adsのコンソール（Adsのインターフェースで確認。このツールは使用していません）

ツール

合計82個のツールがあります。すべてのパラメーターと出力については、docs/TOOLS.mdをご覧ください。ほとんどのツールは読み取り専用です。*_plan_* ツールは変更内容を準備しますが、何も書き込みません。書き込みを行うツールは4つだけで、書き込みが有効になっているクライアントでのみ使用できます。gads_apply、meta_apply、openai_ads_apply、google_applyです。

プラットフォーム	読み取り	変更（プラン）の準備	プランでできること（すべて WRITE.md の制約下）
すべて	server_status, clients_list, client_profile, client_check, plan_get, plan_list, audit_log, ads_overview	rollback_plan	新しいプランを作成してプランを取り消す
GA4	ga4_report, ga4_compare, ga4_key_event_audit, ga4_realtime, ga4_properties, ga4_custom_definitions, ga4_key_events	ga4_plan_key_event_create, ga4_plan_custom_dimension_create	キーイベントまたはカスタムディメンションを作成する
Search Console	gsc_performance, gsc_moves, gsc_opportunities, gsc_inspect_url, gsc_sitemaps, gsc_sites	gsc_plan_sitemap_submit	サイトマップを送信する
Merchant Center	merchant_data_sources, merchant_product_issues, merchant_report_query, merchant_products, merchant_account_issues	merchant_plan_product_patch	商品のタイトル、説明、リンク、在庫状況、価格を変更する
Tag Manager	gtm_inventory, gtm_workspace_status, gtm_get_tag, gtm_get_trigger, gtm_get_variable, gtm_versions	gtm_plan_workspace_create, gtm_plan_tag_upsert, gtm_plan_trigger_upsert, gtm_plan_variable_upsert, gtm_plan_quick_preview	デフォルト以外のワークスペースを編集する。本番環境には反映されません。バージョン作成も公開も行われません
インデックス登録、PageSpeed	indexing_status, pagespeed	なし	なし
Google Ads	gads_accounts, gads_performance, gads_query, gads_conversion_actions	gads_plan_pause_entities, gads_plan_budget_change, gads_plan_add_negatives, gads_plan_create_campaign	一時停止、1日の予算、除外キーワード、新しい検索キャンペーンを1つ作成（一時停止中）
Meta 広告	meta_ad_accounts, meta_insights, meta_campaigns, meta_adsets, meta_ads_list	meta_plan_pause, meta_plan_budget_change, meta_plan_create_campaign, meta_plan_create_adset, meta_plan_create_ad	一時停止、1日の予算、新しいキャンペーン、広告セット、広告を作成（一時停止中）
Meta ピクセル、カタログ、Instagram、ページ	meta_pixel_health, meta_dataset_quality, meta_catalog_diagnostics, meta_catalog_products, meta_ig_insights, meta_page_insights	meta_eco_plan_catalog_item_update	カタログアイテム1件の価格、セール価格、在庫状況、在庫数
ChatGPT Ads	openai_ads_account, openai_ads_insights, openai_ads_conversions, openai_ads_campaigns, openai_ads_ad_groups, openai_ads_ads	openai_ads_plan_pause, openai_ads_plan_budget_change, openai_ads_plan_create_campaign	一時停止、1日の予算、新しいキャンペーンを作成（一時停止中）

主な読み取りツールで確認できる内容：

ツール	サービス	回答できる内容
ga4_report	GA4	期間別のあらゆるレポート：チャネル、ランディングページ、購入、収益
ga4_key_event_audit	GA4	どのイベントがキーイベントか、コンバージョンを水増ししていないか（キーイベント数がセッション数を上回る、または page_view や問い合わせクリックがキーイベントに設定されているなど）
gsc_performance	Search Console	クエリ、ページ、国、デバイス、日付別のクリック数、表示回数、CTR、掲載順位
gsc_opportunities	Search Console	実際の表示回数がある5～15位のクエリやページ、および表示回数はあるもののクリックがないもの
gsc_inspect_url	Search Console	この URL がインデックス登録されているか、Google がどの canonical を選択したか、最終クロール日時
merchant_product_issues	Merchant Center	不承認や警告がある商品、すべてのページ
gtm_inventory	Tag Manager	タグ、トリガー、変数、公開中のバージョン
pagespeed	PageSpeed Insights	Lighthouse のパフォーマンスと SEO のスコア、Core Web Vitals
gads_performance	Google Ads	アカウント、キャンペーン、広告グループ別の費用、クリック数、コンバージョン数、コンバージョン値、ROAS
gads_query	Google Ads	レポート用リソースに対する読み取り専用の GAQL SELECT クエリを1つ実行
meta_insights	Meta Ads	レベル別の費用、リーチ、購入数、コンバージョン値、ROAS。内訳も指定可能
openai_ads_insights	ChatGPT Ads	表示回数、クリック数、費用、コンバージョン数、アトリビューションされた売上
ads_overview	Google Ads、Meta、ChatGPT Ads	1つの期間について3つのプラットフォームを並べて表示

有料メディアコネクター

任意です。1つ、2つ、または3つすべてを設定できます。設定していないものは not_configured を返します。表には元の読み取りツールを記載しています。プランツールを含む全リストは上記をご覧ください。

プラットフォーム	ツール	必要なもの
Google Ads	gads_accounts、gads_performance、gads_query	顧客 ID（GADS_CUSTOMER_ID）、使用する場合はマネージャー ID、そして別途認証が必要です：google-ecommerce-mcp setup-ads --client-secret client_secret.json。デベロッパー トークンは不要です（Google は 2026 年 9 月 9 日に廃止しました）
Meta Ads	meta_ad_accounts、meta_insights	ads_read のみを許可するシステムユーザートークン（google-ecommerce-mcp set-secret meta-access-token）と META_AD_ACCOUNT_ID
ChatGPT Ads	openai_ads_account、openai_ads_insights、openai_ads_conversions	Ads Manager で取得した広告主 API キー（google-ecommerce-mcp set-secret openai-ads-key）。キー1つにつきアカウント1つです
すべて	ads_overview	上記のうち少なくとも1つ

GAQL のルール、すべてのエラー、既知の制限を含む手順については、docs/ADS.mdをご覧ください。

アトリビューションに関する警告。 各プラットフォームはそれぞれ異なる期間、日付、モデルを使ってコンバージョンを個別にアトリビューションするため、同じ注文が複数のプラットフォームでカウントされることがあります。プラットフォームのコンバージョン数を合計しても重複排除されず、実際の注文数を上回ります。ads_overview はすべての回答でこの点を繰り返し伝えます。数値は「各プラットフォームが主張する数」として読み取り、GA4 と、サーバー外では実際の注文数と比較してください。

デフォルトでは読み取り専用ですが、例外があります。 Google Ads の権限（adwords）では書き込みが可能で、Google は読み取り専用の権限を提供していません。書き込みを有効にしない限り、サーバーは読み取りリクエストのみを送信します。ただし、トークン自体には書き込み権限があるため、他の Google トークンとは分けて保管されます。ChatGPT Ads も読み取り専用キーについての説明がなく、同じキーで読み取りと書き込みを行います。セキュリティに関する注意をご覧ください。

オフラインで読み取りと書き込みをテストしたのみです。 すべての動作は偽のレスポンスを使って確認しました。実際のアカウントでの試用はこれからで、実アカウントに書き込みを送信したことはありません。未確認の点：time_granularity=none で ChatGPT Ads が返すタイムゾーン、Meta のより長い表示ウィンドウ（7d_view、28d_view。このツールでは指定できません）、および ChatGPT Ads キーを読み取り専用に制限できるかどうか。

クライアント向けレポート

google-ecommerce-mcp report は、ツールの JSON 結果を、クライアントのブランド（名前、ロゴ、アクセントカラー）を反映した単一の静的 HTML ファイルに変換し、PDF に印刷できるようにします。ネットワーク接続もサービスの設定も不要です。前月および前年との比較を表示し、原因を勝手に作り出すことはありません。原因が表示されるのは、原因を入力した場合のみです。

# the assistant runs the tools for each period and saves their raw JSON; you assemble report.json from them
google-ecommerce-mcp report --input report.json --output report.html --brand-name "Client name" --accent "#1F6F5B" --logo logo.png
# open report.html in a browser, then Ctrl+P > Save as PDF

計画、入力仕様、色のルール、KPI の計算式、よくある間違いについては、docs/REPORTING.md をご覧ください。すぐに使えるプロンプトは examples/PROMPTS.md にあります。現時点ではサンプルデータでのみテストしており、実際のクライアントアカウントではまだテストしていません。利益率、目標、注釈はユーザーが入力します。また、インプレッションシェア、ショッピングの商品レポート、MER などの数値には、追加の GAQL またはアシスタントによる計算が必要です。

対象ユーザー

• ショップオーナー。 6 つのダッシュボードを開かずに、何が売れたか、何に問題があるか、どの広告が無駄な出費になっているかを率直に知りたい方。インストールして、普段の言葉で質問し、自分で判断できます。
• 代理店。 複数のクライアントを担当している方。1 回のインストールと 1 つの登録情報（docs/MULTI-CLIENT.md）で、毎回同じ確認を行い、クライアントに渡す回答にアトリビューション上の注意点を記載できます。また、選択したクライアントとプラットフォームに限り、書き込みを有効にできます。
• 開発者。 シンプルで読みやすく、テスト済みのサーバーを求める方。通常の HTTP 呼び出し、プラットフォームごとの許可リスト、単一の書き込み経路、構造化エラーを備えています。プルリクエストを歓迎します（「貢献について」をご覧ください）。

対応しないこと

• 内容を確認できる計画なしに変更することはありません。 デフォルトでは何も書き込みません。クライアントの書き込みを有効にしても、一時停止中のキャンペーンの有効化、削除やアーカイブ、タグマネージャーのコンテナの公開、入札額の設定や入札戦略の選択（新しい Google Ads キャンペーンでは、入札額なしの固定手動 CPC が設定されます）、このバージョンでのコンバージョンや顧客リストのアップロードはできません。作成されるものはすべて一時停止状態です。これらの操作には、各プラットフォームのインターフェースをご利用ください。
• ターミナルでの操作なしに、費用が発生する変更を行うことはありません。 予算、新しいキャンペーン、価格変更が適用されるのは、ユーザー自身が google-ecommerce-mcp approve を実行した後に限られます。ただし、マシン上のシェルにアクセスできるアシスタントから保護されるわけではありません（docs/SECURITY.md をご覧ください）。
• 因果関係に基づくアトリビューションは行いません。 各プラットフォームと GA4 が記録した内容を報告します。広告が売上の原因になったかどうか（インクリメンタリティ）は判断できません。
• 実際の注文数はわかりません。 ショップの管理画面（WooCommerce、Shopify など）は読み取らないため、実際の注文数、利益率、返品についてはわかりません。ユーザーの同意率も把握できません。
• コンバージョンの重複排除や通貨換算は行いません。 各プラットフォームのコンバージョンを「真の」単一の数値にまとめることはなく、同じ通貨の場合に限り、広告費を合算します。

クイックインストール

まず Google OAuth クライアントを作成し（下記のステップ 1）、次にインストーラーを実行します。必要に応じて uv をインストールし、ID を尋ねてから Google の同意画面を開き、サーバーを Claude Desktop に追加します（既存の設定はバックアップされます）。リリース時と同じ正確なパッケージバージョン（google-ecommerce-mcp==0.6.0）をインストールします。

推奨：ダウンロードして、読み、実行する。 URL はブランチではなく正確なコミットを指定しているため、スクリプトが予告なく変更されることはありません。

Windows（PowerShell）：

Invoke-WebRequest https://raw.githubusercontent.com/MoonEyes/google-ecommerce-mcp/54705d4dd1a4b34b387a682c13de164210892352/install.ps1 -OutFile install.ps1
Get-Content .\install.ps1            # read it
(Get-FileHash .\install.ps1 -Algorithm SHA256).Hash   # compare with the SHA-256 below
.\install.ps1

macOS / Linux：

curl -LsSf -o install.sh https://raw.githubusercontent.com/MoonEyes/google-ecommerce-mcp/54705d4dd1a4b34b387a682c13de164210892352/install.sh
cat install.sh                       # read it
shasum -a 256 install.sh             # compare with the SHA-256 below
sh install.sh

固定されたスクリプトの SHA-256：

• install.ps1：aa697734ffcd71fd063ebb5ac6e6996a29572582ac7f18d53566082723265db0
• install.sh：3849a64501ed954ec5a79ecaaa29c8c79621bfe0c8bd20c758179feb3fc85aba

読まずに実行する場合の 1 行コマンド（同じ固定コミットを使用します。この方法では SHA-256 は検証されません）：

irm https://raw.githubusercontent.com/MoonEyes/google-ecommerce-mcp/54705d4dd1a4b34b387a682c13de164210892352/install.ps1 | iex

curl -LsSf https://raw.githubusercontent.com/MoonEyes/google-ecommerce-mcp/54705d4dd1a4b34b387a682c13de164210892352/install.sh | sh

インストーラーには任意の 有料メディア のステップ（Google Ads、Meta Ads、ChatGPT Ads）があります。--skip-ads でスキップできます。シークレットを引数として受け取ることはありません。Google Ads はブラウザーの同意画面（同じ OAuth クライアントファイルを使用し、トークンは別）を使用し、Meta トークンと ChatGPT Ads キーは、非表示のプロンプトに入力して OS のキーリングに保存します。Claude Desktop の設定に渡されるのは、シークレットではない ID のみです。シークレットではないオプションは、--gads-customer-id（正確に 10 桁。ハイフン可）、--gads-login-customer-id、--meta-account-id（3～20 桁）、--corporate-proxy（ADS_TRUST_ENV=1 を設定します。既存のエントリーに追加するだけなら、これだけで十分です）です。同意やシークレットの入力を求める前に、すべてのチェックが実行されます。値が競合する場合は終了コード 3 で停止し、何も変更されません。--force を指定すると値を置き換えますが、変数は削除されません。--yes を指定すると、渡す ID がないため ChatGPT Ads はスキップされます。対話形式で追加するには install --skip-auth を、コマンドで追加するには set-secret openai-ads-key を使用してください。PageSpeed キーは --pagespeed-key から読み取られます（推奨しません。シェルの履歴に残ります）。指定がなければ PAGESPEED_API_KEY、それもなければ非表示のプロンプトから読み取られます。

ガイド付きインストール。 手順を 1 つずつ案内してもらうには、examples/INSTALL-PROMPT.md（英語）または INSTALL-PROMPT.fr.md（フランス語）を Claude に貼り付けてください。サービスを 1 つずつインストールする方法と、クライアントのアクセスチェックリストについては、docs/SETUP.md をご覧ください。

Claude Desktop を完全に終了してから、再度開いてください。オプションを渡すには、まずスクリプトを保存します。たとえば .\install.ps1 --ga4 123456789 --gsc sc-domain:example.com --client-secret client_secret.json のように実行します。すべてのオプションを確認するには、google-ecommerce-mcp install --help を実行してください。メンテナー向け：リリースごとに両方のスクリプトのバージョンを更新し、次にこれらの URL のコミットとチェックサムを更新します（チェックサムが一致するまで tests/test_installer_scripts.py は失敗します）。

セットアップ手順

クイックインストールを使用した場合は、ステップ 1 のみ必要です。以下の手順は手動で行う場合の方法です。

1. Google Cloud（1 回、約 10 分）

クリック手順をすべて説明した詳しいガイドはこちらです：docs/SETUP-GOOGLE-CLOUD.md。簡単な手順は次のとおりです。

1. Google Cloud Console で、プロジェクトを作成するか、既存のプロジェクトを選択します。
2. 必要な API を有効にします：Google Analytics Data API、Google Analytics Admin API、Google Search Console API、Merchant API、Tag Manager API、Web Search Indexing API、PageSpeed Insights API。
3. OAuth 同意画面を設定します（外部を選択し、自分をテストユーザーとして追加します）。
4. デスクトップアプリ タイプの OAuth クライアントを作成し、その JSON ファイルをダウンロードします。
5. Merchant API のみ：Cloud プロジェクトを登録し、Merchant Center アカウントと連携します。
6. 任意：PageSpeed Insights に制限した API キーを作成します（匿名ユーザー向けの割り当ては共有されており、使い切られていることがよくあります）。

2. インストールと認証

# with uv (recommended): nothing to install, uvx fetches the package from PyPI
uvx google-ecommerce-mcp setup --client-secret path/to/client_secret.json --with-merchant
# read scopes only by default; --with-merchant / --with-indexing add the write-capable ones you need

# or with pip
pip install google-ecommerce-mcp
google-ecommerce-mcp setup --client-secret path/to/client_secret.json

最新の開発版：uvx --from git+https://github.com/MoonEyes/google-ecommerce-mcp google-ecommerce-mcp。

ブラウザーで Google の同意画面が開きます。トークンは OS のキーリングに保存されます。google-ecommerce-mcp check を実行して、すべてを確認してください。

doctor で各サービスを確認する：

google-ecommerce-mcp doctor                          # offline; without a registry: Service, Set up, Secret, Token, Status, Account; with one: Client, Platform, Ids, Read, Write, On, Status, Account, Next (plus Live with --live)
google-ecommerce-mcp doctor --only gads --live       # one service, plus one minimal read call
google-ecommerce-mcp doctor --live --json            # no secret in the output; ids masked (123***890)

--client <name> を指定すると、レジストリ内の 1 つのクライアントに限定されます。--only には ga4,gsc,merchant,gtm,pagespeed,gads,meta,openai を指定します（カンマ区切り）。doctor は、このシェルの環境変数と Claude Desktop の設定にあるサーバーエントリーを読み取ります（別の場所を指定するには --config と --name を使用します）。表の後に「To fix」（各問題を修正するための正確なコマンド）、「Not set up」、「Result:」の行、「Next command:」が表示されます。終了コード 0 は設定済みのすべてのサービスが動作していること、1 は設定済みのサービスに不具合があること、2 は何も設定されていないことを示します。--live では PageSpeed はテストされません（ページアドレスと約 30 秒が必要なため、スキップとして表示されます）。代わりに、アシスタントに pagespeed の実行を依頼してください。

有料メディア（任意）

Google Ads は google-ecommerce-mcp setup-ads --client-secret client_secret.json（または --gads-customer-id を指定して install）、Meta は google-ecommerce-mcp set-secret meta-access-token に広告アカウント ID を追加して設定します（install --yes --skip-auth --meta-account-id <id>）。ChatGPT Ads は google-ecommerce-mcp set-secret openai-ads-key で設定します。その後、doctor --only <service> --live で各サービスを確認してください。前提条件はこちらです：docs/ADS.md。全体の手順、アクセス権のチェックリスト、クライアント向けのメールテンプレートはこちらです：docs/SETUP.md。

3. MCP クライアントに追加する

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "google-ecommerce": {
      "command": "uvx",
      "args": ["google-ecommerce-mcp"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GSC_SITE_URL": "sc-domain:example.com",
        "MERCHANT_ACCOUNT_ID": "1234567890",
        "GTM_CONTAINER_ID": "GTM-XXXXXXX",
        "PAGESPEED_API_KEY": ""
      }
    }
  }
}

Claude Code：

claude mcp add google-ecommerce -e GA4_PROPERTY_ID=123456789 -e GSC_SITE_URL=sc-domain:example.com \
  -e MERCHANT_ACCOUNT_ID=1234567890 -e GTM_CONTAINER_ID=GTM-XXXXXXX \
  -- uvx google-ecommerce-mcp

すべての変数は任意です。設定していないサービス用のツールは、単に not_configured を返します。これらの変数は1 つのショップを対象としています（レガシーモード）。複数のクライアントを使う場合は、代わりにレジストリを作成し、この設定から ID を省略してください：docs/QUICKSTART.md、docs/MULTI-CLIENT.md。レジストリが作成されると、以下の ID 変数は無視されます。広告プラットフォームの場合は、ID を設定（GADS_CUSTOMER_ID、META_AD_ACCOUNT_ID）し、シークレットは表の下にあるコマンドを使ってキーリングに保存してください。

変数	例	用途
GA4_PROPERTY_ID	123456789（数値のプロパティ ID）	GA4 ツール
GSC_SITE_URL	sc-domain:example.com または https://www.example.com/	Search Console ツール
MERCHANT_ACCOUNT_ID	1234567890	Merchant ツール
GTM_CONTAINER_ID	GTM-XXXXXXX	gtm_inventory
PAGESPEED_API_KEY	API キー	pagespeed
GOOGLE_TOKEN_FILE	~/.config/google-ecommerce-mcp/token.json	キーリングの代わりにトークンをファイルに保存
GADS_CUSTOMER_ID	1234567890	Google Ads ツール
GADS_LOGIN_CUSTOMER_ID	1234567890	アカウントへのアクセスに経由する場合に限り、管理者（MCC）ID
GADS_DEVELOPER_TOKEN		2026 年 9 月 9 日以降は不要です。設定されている場合にのみ送信されます
GADS_TOKEN_FILE	~/.config/google-ecommerce-mcp/ads-token.json	キーリングの代わりに Google Ads トークンをファイルに保存（GOOGLE_TOKEN_FILE とは異なる値を指定してください）
GADS_API_VERSION	v26（デフォルト）	Google Ads REST バージョン
GADS_ALLOW_SENSITIVE_QUERIES	1	gads_query のリソース一覧の制限を解除します（個人データが含まれる可能性があります）
META_ACCESS_TOKEN		Meta トークン（ads_read のみ）。設定に含めずに済むよう、set-secret meta-access-token を使用してください
META_AD_ACCOUNT_ID	act_1234567890 または 1234567890	meta_insights
META_API_VERSION	v26.0（デフォルト）	Graph API バージョン
OPENAI_ADS_API_KEY		ChatGPT Ads キー。set-secret openai-ads-key の使用を推奨します
ADS_TRUST_ENV	1（正確に）	Ads コネクターで HTTPS_PROXY、NO_PROXY、REQUESTS_CA_BUNDLE を使用します（企業プロキシ）
GEM_CLIENT	acme	このサーバープロセスをレジストリ内の 1 つのクライアントに固定
GEM_CLIENTS_FILE	パス	デフォルトの clients.json 以外のクライアントレジストリファイルを使用
GEM_WRITE	1（正確に）	書き込みを許可するかどうか。設定されていない場合、すべての適用処理が拒否されます。docs/WRITE.md を参照
GEM_STATE_DIR	パス	プラン、承認、ジャーナルの保存場所
GEM_LANG	fr または en	client、quickstart、install メッセージの言語（デフォルト：システム言語）
GEM_WRITE_HMAC_KEY	長いランダムな文字列	プランと承認の署名キー（CI）。それ以外の場合は、キーリングの write-hmac-master エントリ、または状態フォルダー内のファイルを使用
GEM_LIVE_TEST	1	設定すると、"sandbox": true とマークされたクライアントに対してのみ適用処理が実行されます
GEM_SECRET_<CLIENT>_<KIND>	GEM_SECRET_ACME_META	キーリングの代わりに環境変数から読み込む、クライアントのシークレット（CI）

クライアントレポートのコマンド：google-ecommerce-mcp report --input report.json --output report.html [--lang fr|en] [--brand-name NAME] [--accent #RRGGBB] [--logo FILE] [--force]（docs/REPORTING.md を参照）。

有料メディアコネクターのコマンド（詳細は docs/ADS.md を参照）：

google-ecommerce-mcp setup-ads --client-secret path/to/client_secret.json [--token-file path]   # Google Ads only, separate token
google-ecommerce-mcp set-secret meta-access-token      # hidden prompt, stored in the OS keyring
google-ecommerce-mcp set-secret openai-ads-key         # hidden prompt, stored in the OS keyring

呼び出しの仕組み

セキュリティに関する注意事項

詳細、ガードレールの全一覧、既知の制限事項については、docs/SECURITY.md をご覧ください。

• 読み取りは読み取り専用として強制されます。 すべての読み取りリクエストは送信前に許可リストと照合され、ツールがリスト外のエンドポイントを呼び出そうとすると CI が失敗します。readOnlyHint はあくまでヒントです。
• 書き込みはデフォルトで無効であり、オプトインが必要です。 GEM_WRITE=1、クライアントとプラットフォームでの enabled 設定、許可されたアカウント、予算上限、作成の一時停止、フィールド許可リスト、正確なプランに紐付けられた署名済みの単回使用トークン、書き込み可能なジャーナルが必要です。また、金銭、個人データ、取り消し不能、または高リスクのプランでは、ターミナルでの承認も必要です。有効化、削除、公開は行いません。
• 把握しておくべき制限事項です。 ターミナルでの承認があっても、マシン上のシェルまたはファイルにアクセスできるアシスタントを止めることはできません。Google Ads トークンと ChatGPT Ads キーは、読み取り用と書き込み用に分割できません。書き込みポリシーは、あなた（またはあなたとして実行されるもの）が編集できるファイルです。実アカウントで書き込みが検証されたことは一度もありません。
• setup では読み取りスコープのみが要求されます。Google には Merchant Center（content）または Indexing API（indexing）向けの読み取り専用スコープがないため、これらは --with-merchant / --with-indexing を指定した場合にのみ要求されます。GA4、Tag Manager、Search Console、Merchant Center の書き込みスコープは、setup --client <name> --write で作成する別のトークンに保存されます。
• 有料メディアです。 各広告プラットフォームには独自の許可リスト（ホストを固定し、読み取りエンドポイントを少数に限定）があります。Google Ads のクエリは送信前に GAQL バリデーターを通過します。リダイレクトは追跡されず、応答サイズは 20 MB に制限され、すべてのエラーでシークレットがマスキングされます。環境のプロキシは、ADS_TRUST_ENV=1 を設定した場合にのみ使用されます。
• Google Ads のスコープに関する注意点です。 setup-ads では、書き込みが可能で制限できない adwords スコープが要求されます。これは Google の読み取りトークンとは別のキーリングエントリに保存されます。ChatGPT Ads には読み取り専用キーがなく、Meta のシステムユーザートークンは有効期間が長いため、各認証情報をこのサーバー専用にし、使用をやめる際は失効させてください。
• すべての結果には fetched_at と freshness が含まれます。レポートツールは、データのタイムゾーンで解決された照会対象の date_range と data_complete を返します。
• Google アカウントの権限から、いつでもアクセスを取り消せます。

制限事項

• Merchant API は新しく、Google は仕様を変更し続けています。旧 Content API for Shopping は終了しているため、Merchant API のみを使用します。呼び出しで問題が起きた場合は、issue を作成してください。
• クライアントレジストリがない場合（レガシーモード）：サーバーインスタンスごとにサイト、Merchant アカウント、コンテナはそれぞれ 1 つで、書き込みは利用できません。レジストリがある場合：任意の数のクライアントを登録でき、それぞれが独自の ID とシークレットを持ちます。
• ga4_report には GA4 Data API の割り当て制限が適用されます。各広告プラットフォームには独自の割り当て制限があり、制限に達すると rate_limited が返されます。自動再試行は行われません。
• 有料メディアコネクターも書き込み機能も、実アカウントではテストされていません（オフラインテストのみです）。プラットフォームごとのコンバージョンは個別にアトリビューションされ、重複排除されません。支出額の通貨換算も行われません。
• 広告プラットフォームは API を頻繁に変更します（デフォルト：Google Ads v26、Meta v26.0。どちらも設定可能です）。呼び出しで問題が起きた場合は、issue を作成してください。
• クライアントごとに、Google Ads の顧客、Meta の広告アカウント、ChatGPT Ads のキーはそれぞれ 1 つです。レジストリがある場合、クライアント自身のものではない property_id、customer_id、account_id は、読み取りとプランの両方で拒否されます（id_not_owned）。レガシーモード（レジストリなし）の場合に限り、これらのパラメーターを使って、認証情報からアクセス可能な任意のアカウントを読み取れます。
• 0.5.0 以降の書き込みでは、入札は拒否されます（一部の作成もできません。たとえば、入札上限が必要な目標を設定した Meta 広告セットや、入札額を指定しない固定の手動 CPC を使用する新しい Google Ads キャンペーンなど）。有効化、削除、公開の機能はなく、max_plan_budget_micros も使用できません。

コントリビューション

CONTRIBUTING.mdをご覧ください。セキュリティに関する報告：SECURITY.md。

開発

pip install -e ".[dev]"
pytest

テストは偽の HTTP セッションを使用してオフラインで実行でき、Google、Meta、OpenAI のアカウントは必要ありません。メンテナーはdocs/RELEASING.mdをご覧ください。

ライセンス

MIT。詳細はLICENSEをご覧ください。