gmc-mcp

Google Merchant Center MCP（gmc-mcp）

Merchant API v1 を基盤とする、Google Merchant Center 向け MCP サーバーです。 126 個のツールを備え、MIT ライセンスで提供されており、pip install でインストールできます。Claude Desktop、Claude Code、または MCP 対応クライアントから自然言語で、Google Shopping のフィード、商品、在庫、レポート、プロモーション、返品、アカウント設定を操作できます。

GMC と MCP の選択肢の中での位置づけ

選択肢	種類	API	ライセンス	インストール	ツール
Adzviser / Catchr / Windsor.ai / Pipedream	有料ホスト型 SaaS	さまざま	プロプライエタリ	サインアップ	さまざま
archpeng/GMC-mcp-server	セルフホスト可能	Content API v2.1（2026-08 に非推奨化）	宣言なし	git clone	34
gmc-mcp（本パッケージ）	セルフホスト可能	Merchant API v1（将来も安心）	MIT	pip install gmc-mcp	126

将来も安心して使える API、正式な OSS ライセンス、PyPI からのインストール、多数のツール、監査ログ＋ロールバック＋ドライランによる安全性、そして認証情報がマシンの外に出ないことを重視する場合は、こちらをお選びください。

Merchant API v1（Shopping 向け Content API の後継）を基盤としており、v1beta は 2026-02-28 に提供終了しました。デフォルトで安全に使えます。すべての書き込みは before スナップショット付きの追記専用監査ログに記録され、ドライランは設定ひとつで有効にでき、破壊的な一括操作には明示的な confirm パラメーターが必要です。

開発の背景

Google Merchant Center（GMC）は、Google Shopping の商品掲載、無料リスティング、ショッピング広告、Buy on Google のチェックアウト、YouTube Shopping などを支えています。何千もの商品を含むフィードを GMC のウェブ UI から管理するのは面倒で、Merchant API の REST エンドポイントを使って一度きりの Python スクリプトを書くのは時間がかかります。

GMC 向けの既存 MCP サービスもありますが、それぞれ異なる用途に適しています。

• 有料ホスト型 SaaS（Adzviser、Catchr、Windsor.ai、Pipedream）— データは各社のサーバーを経由し、月額サブスクリプションが必要です。
• archpeng/GMC-mcp-server — 最初期のセルフホスト型 Python オプション（2026 年 2 月）ですが、Google が2026 年 8 月に廃止する、非推奨の Content API v2.1 を基盤としており、ライセンスの宣言がなく、PyPI にも登録されていません。

gmc-mcp はこのギャップを埋めるために開発されました。新しい Merchant API v1 を基盤とするセルフホスト型パッケージで、MIT ライセンス、PyPI での提供に加え、監査／ロールバック／ドライランによる安全性を備え、19 個のモジュールにわたって 126 個のツールを提供します。

このパッケージは、Claude（または任意の MCP クライアント）に Merchant API v1 の機能を直接反映した 126 個のツールを提供し、次のような操作を可能にします。

• 「不承認の商品をすべて、問題コード別にまとめて表示して。」
• 「これら 40 個の SKU の米国向け価格を 5％引き上げて。」
• 「先週、インプレッションはあったのにクリック数がゼロだった商品はどれ？」
• 「監査 ID 8fc8dc42…をロールバックして。更新で何かが壊れたみたい。」
• 「この Shopify の CSV と GMC フィードを比較して、不足しているものを教えて。」

公開されている機能

19 モジュールにまたがる 126 個のツールと、4 個のメタツール。

モジュール	ツール
products	gmc_list_products, gmc_get_product, gmc_insert_product, gmc_update_product, gmc_delete_product, gmc_bulk_delete_products, gmc_list_disapproved_products
inventory	gmc_update_regional_inventory, gmc_update_local_inventory, gmc_list_regional_inventories, gmc_list_local_inventories
issues	gmc_list_account_issues, gmc_get_product_status, gmc_summarize_product_issues
reports	gmc_query_report, gmc_product_performance, gmc_price_competitiveness, gmc_best_sellers, gmc_zero_click_products, gmc_revenue_by_brand, gmc_category_performance, gmc_competitive_visibility_top_merchants, gmc_price_insights, gmc_demoted_products
promotions	gmc_list_promotions, gmc_get_promotion, gmc_insert_promotion
accounts	gmc_get_account, gmc_get_business_info, gmc_update_business_info, gmc_list_users, gmc_add_user, gmc_remove_user, gmc_get_shipping_settings, gmc_update_shipping_settings, gmc_list_programs, gmc_request_program_review, gmc_get_program_review
regions	gmc_list_regions, gmc_get_region, gmc_create_region, gmc_update_region, gmc_delete_region
notifications	gmc_list_subscriptions, gmc_subscribe, gmc_unsubscribe
feeds	gmc_list_datasources, gmc_get_datasource, gmc_create_supplemental_feed, gmc_create_primary_feed, gmc_delete_datasource, gmc_fetch_datasource
return_policies	gmc_list_return_policies, gmc_get_return_policy, gmc_create_return_policy, gmc_update_return_policy, gmc_delete_return_policy
homepage	gmc_get_homepage, gmc_update_homepage, gmc_claim_homepage, gmc_unclaim_homepage
account_config	gmc_get_business_identity, gmc_update_business_identity, gmc_get_checkout_settings, gmc_create_checkout_settings, gmc_update_checkout_settings, gmc_delete_checkout_settings, gmc_get_automatic_improvements, gmc_update_automatic_improvements, gmc_get_autofeed_settings, gmc_update_autofeed_settings, gmc_get_account_tax, gmc_update_account_tax, gmc_get_email_preferences, gmc_update_email_preferences, gmc_get_latest_tos, gmc_list_tos_agreement_states, gmc_accept_tos
quotas	gmc_list_quotas
reviews	gmc_list_merchant_reviews, gmc_get_merchant_review, gmc_insert_merchant_review, gmc_delete_merchant_review, gmc_list_product_reviews, gmc_get_product_review, gmc_insert_product_review, gmc_delete_product_review
conversions	gmc_list_conversion_sources, gmc_get_conversion_source, gmc_create_conversion_source, gmc_update_conversion_source, gmc_delete_conversion_source, gmc_undelete_conversion_source
omnichannel	gmc_list_omnichannel_settings, gmc_get_omnichannel_settings, gmc_create_omnichannel_settings, gmc_update_omnichannel_settings, gmc_request_inventory_verification, gmc_link_gbp_account, gmc_list_gbp_accounts
lfp	gmc_lfp_list_stores, gmc_lfp_get_store, gmc_lfp_insert_store, gmc_lfp_delete_store, gmc_lfp_insert_inventory, gmc_lfp_insert_sale, gmc_lfp_get_merchant_state
mca	gmc_list_relationships, gmc_get_relationship, gmc_update_relationship, gmc_create_aggregation, gmc_delete_aggregation, gmc_list_account_services, gmc_propose_account_service, gmc_approve_account_service, gmc_reject_account_service
bulk	gmc_bulk_update_regional_prices, gmc_bulk_set_availability
diagnostics	gmc_health_check, gmc_rollback, gmc_export_all, gmc_diff_with_shopify
meta	gmc_describe_server, gmc_audit_lookup, gmc_audit_tail, gmc_set_dry_run

CLI では、gmc-mcp run、auth-init、register-gcp、webhook、describe、version も利用できます。

インストール

pip install gmc-mcp

開発環境での利用：

git clone https://github.com/kiwoongeom/gmc-mcp
cd gmc-mcp
pip install -e ".[dev,test]"
pre-commit install

クイックスタート

1. Merchant API を有効にしてサービスアカウントを作成する

1. console.cloud.google.com → プロジェクトを作成／選択します。
2. API とサービス → ライブラリ → Merchant API を有効にします。
3. IAM と管理 → サービス アカウント → サービス アカウントを作成 を選択し、gmc-mcp という名前を付けます。
4. 新しいサービスアカウントを開く → 鍵 → 鍵を追加 → 新しい鍵を作成 → JSON を選択します。安全な場所に保存してください。

2. サービスアカウントを Merchant Center に追加する

1. merchants.google.com → 右上の歯車 → アカウントへのアクセス → ユーザー。
2. ユーザーを追加 → [email protected] のメールアドレスを入力 → 管理者 権限を付与します。
3. 右上に表示されている10桁の Merchant Center ID を控えておきます。

3. 設定

cp .env.example .env
# edit:
#   GMC_ACCOUNT_ID=1234567890
#   GMC_SERVICE_ACCOUNT_KEY=/abs/path/to/service-account.json

4. GCP の初回登録

新しいプロジェクトで v1 Merchant API の呼び出しを行う前に必要です。

gmc-mcp register-gcp --developer-email [email protected]

5. 動作確認

gmc-mcp describe              # prints the resolved config
python examples/quickstart.py  # makes one read against the Merchant API

6. Claude に接続する

以下を %APPDATA%/Claude/claude_desktop_config.json（Desktop）または ~/.claude/settings.json（Code）に追加します。

{
  "mcpServers": {
    "gmc": {
      "command": "gmc-mcp",
      "args": ["run"],
      "env": {
        "GMC_ACCOUNT_ID": "1234567890",
        "GMC_SERVICE_ACCOUNT_KEY": "/abs/path/to/service-account.json"
      }
    }
  }
}

Claude を再起動します。「どのアカウントに接続していますか？」と尋ねると、gmc_describe_server が呼び出されるはずです。

サービスアカウントの代わりに OAuth を使用する

エンドユーザーに代わって操作する場合（例：マルチテナント SaaS）：

# 1. In GCP, create OAuth client credentials (type: Desktop), download client_secret.json.
gmc-mcp auth-init --client-secrets ./client_secret.json
# follow the browser flow; a token JSON is saved to secrets/oauth-token.json.

# 2. Use it
export GMC_OAUTH_TOKEN=./secrets/oauth-token.json
gmc-mcp run

トランスポート

gmc-mcp run                              # stdio (Claude Desktop default)
gmc-mcp run --transport sse --port 8000  # SSE / HTTP (remote, Docker, hosted)

または Docker 経由：

docker build -t gmc-mcp .
docker run --rm -p 8000:8000 \
    -e GMC_ACCOUNT_ID=1234567890 \
    -v $PWD/secrets:/secrets \
    -e GMC_SERVICE_ACCOUNT_KEY=/secrets/service-account.json \
    gmc-mcp

監査ログとロールバック

書き込みのたびに、GMC_AUDIT_LOG（デフォルト：./logs/audit.jsonl）に JSONL エントリが記録されます。各エントリには次の内容が含まれます。

• audit_id — 検索用の UUID
• op、method、url、request_body、response_status、response_body
• before — ツールが取得した書き込み前のスナップショット（update_* と delete_* で使用）
• dry_run — リクエストが実際に送信されたかどうか

Claude 内から確認するには：

> Show me my last 5 GMC writes.
[gmc_audit_tail(limit=5) → ...]

> Look up audit ID abc123.
[gmc_audit_lookup(audit_id="abc123") → ...]

> Roll back audit ID abc123, that update was wrong.
[gmc_rollback(audit_id="abc123", confirm="ROLLBACK") → ...]

ドライラン

有効にする方法は2つあります。

GMC_DRY_RUN=true gmc-mcp run

> Set dry-run on and update the price of SKU1 to $19.99.
[gmc_set_dry_run(enabled=True) → ok]
[gmc_update_regional_inventory(...) → {"_dry_run": true, ...}]

読み取りは常に実行され、スキップされるのは書き込みのみです。

レポートクエリの例

gmc_query_report に貼り付けます。

-- Top 50 by clicks last 7 days
SELECT offer_id, title, clicks, impressions, ctr
FROM product_performance_view
WHERE date BETWEEN '2026-04-23' AND '2026-04-30'
ORDER BY clicks DESC LIMIT 50

-- Disapproved products with reason codes
SELECT id, offer_id, title, item_issues
FROM product_view
WHERE aggregated_reporting_context_status = 'NOT_ELIGIBLE_OR_DISAPPROVED'

-- You're priced higher than the benchmark
SELECT offer_id, title, price, benchmark_price
FROM price_competitiveness_product_view
WHERE price > benchmark_price LIMIT 100

設定リファレンス

設定はすべて環境変数（または .env）で行います。CLI フラグ --transport、--host、--port、--env はこれらの設定を上書きします。

変数	必須	デフォルト	備考
GMC_ACCOUNT_ID	はい	—	10桁の Merchant Center ID
GMC_SERVICE_ACCOUNT_KEY	いずれか1つ	—	サービスアカウント JSON のパス
GMC_OAUTH_TOKEN	いずれか1つ	—	OAuth トークン JSON のパス
GMC_SUBACCOUNT_ID	いいえ	—	MCA を使用する場合
GMC_AUDIT_LOG	いいえ	./logs/audit.jsonl	追記専用 JSONL
GMC_PAGE_SIZE	いいえ	100	リストのデフォルトページサイズ
GMC_TIMEOUT	いいえ	30	リクエストごとの秒数
GMC_DRY_RUN	いいえ	false	書き込みは監査ログにのみ記録
GMC_LOG_LEVEL	いいえ	INFO	DEBUG/INFO/WARNING/ERROR
GMC_TRANSPORT	いいえ	stdio	stdio または sse
GMC_HOST	いいえ	127.0.0.1	SSE のみ
GMC_PORT	いいえ	8000	SSE のみ

アーキテクチャ

Claude (any MCP client)
    │  JSON-RPC over stdio or SSE
    ▼
gmc-mcp server  ──►  audit.jsonl
    │
    │  HTTP + Bearer token
    ▼
merchantapi.googleapis.com  ──►  Google Merchant Center

• auth.py — ServiceAccountAuth と OAuthUserAuth は共通の Auth プロトコルを実装します。
• client.py — リトライ（ジッター付きで5回）、ページネーション用ヘルパー、書き込み監査フックを備えた単一の MerchantClient。
• tools/*.py — 各モジュールは register(mcp, client) を公開し、@mcp.tool() 関数を登録します。
• audit.py — 追記専用 JSONL、ID による検索、before スナップショットをサポートします。
• cli.py — gmc-mcp run | auth-init | register-gcp | webhook | describe | version。

テスト

pytest                       # 100% offline; uses respx to mock HTTP
pytest --cov=gmc_mcp         # with coverage
ruff check src tests
mypy src/gmc_mcp

ロードマップ

• v0.3：Webhook ハンドラーのひな型（gmc_subscribe コールバックに自動応答）
• v0.3：Google がリリースした時点で、Merchant API v1 GA へネイティブ移行
• v0.4：レポートクエリの BigQuery エクスポート
• v0.4：ルールベースの自動修正ツール（「不承認の場合、修正した属性で再試行」）

貢献

CONTRIBUTING.md をご覧ください。PR や Issue を歓迎します。これは Google Merchant Center 向け初のオープンソース MCP であり、どのワークフローに専用ツールを用意すべきか、コミュニティからの意見を取り入れる余地が大いにあります。

ライセンス

MIT — LICENSEをご覧ください。

---

検索キーワード：Google Merchant Center MCP、GMC MCP、Merchant API MCP、 Google Shopping MCP、Shopping Ads MCP、free listings MCP、Claude Desktop Google Merchant Center、eコマース向けMCP、Shopify Google Merchant Center 自動化。