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 商品 Feed、商品、库存、报告、促销、退货和账户配置。

它在 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、正式的开源许可证、PyPI 安装方式、更多工具、审计日志 + 回滚 + 试运行安全机制，以及始终保留在本机上的凭据，请选择它。

基于 Merchant API v1 构建（取代了 Shopping 的 Content API；v1beta 已于 2026-02-28 停用）。默认安全：每次写入都会记录到只追加的审计日志中，并保存 before 快照；只需切换一个选项即可启用试运行；执行破坏性批量操作时必须显式提供 confirm 参数。

为什么要开发它

Google Merchant Center（GMC）为 Google Shopping 商品信息、免费商品信息、Shopping Ads、Buy on Google 结账、YouTube Shopping 等提供支持。通过 GMC 网页界面管理数千件商品的 Feed 很繁琐，而针对 Merchant API REST 端点编写一次性 Python 脚本又很耗时。

目前已有一些适用于 GMC 的 MCP 服务，但各自面向不同需求：

• 付费托管 SaaS（Adzviser、Catchr、Windsor.ai、Pipedream）——你的数据会经由它们的服务端代理；需要按月订阅。
• archpeng/GMC-mcp-server——最早的可自托管 Python 方案（2026 年 2 月），但基于已弃用的 Content API v2.1 构建；Google 将于 2026 年 8 月 停用该 API。它没有声明许可证，也未发布到 PyPI。

开发 gmc-mcp 是为了填补这一空缺：一个基于全新 Merchant API v1、采用 MIT 许可证、发布在 PyPI 上的可自托管软件包，具备审计、回滚和试运行安全机制，并在 19 个模块中提供 126 个工具。

该软件包为 Claude（或任何 MCP 客户端）提供 126 个工具，可直接调用 Merchant API v1 的各项功能，因此你可以：

• “列出所有未获批准的商品，并按问题代码分组。”
• “将这些 40 个 SKU 的美国价格上调 5%。”
• “上周哪些商品有展示次数但点击次数为零？”
• “回滚审计 ID 8fc8dc42…——这次更新出了问题。”
• “将这个 Shopify CSV 与我的 GMC Feed 对比；缺少了哪些内容？”

暴露的内容

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. APIs & Services → Library → 启用 Merchant API。
3. 前往 IAM & Admin → Service Accounts → Create service account，将其命名为 gmc-mcp。
4. 打开新建的服务账号 → Keys → Add key → Create new key → JSON。将文件保存在安全的位置。

2. 将服务账号添加到 Merchant Center

1. 前往 merchants.google.com → 点击右上角的齿轮图标 → Account access → People。
2. 点击 Add user → 输入 [email protected] 邮箱 → 授予 Admin 权限。
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（桌面应用）或 ~/.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。询问：“我连接的是哪个账号？”——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") → ...]

试运行

有两种启用方式：

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, ...}]

读取操作始终会执行；仅跳过写入操作。

Reports 查询示例

粘贴到 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	二选一	—	服务账号 JSON 文件路径
GMC_OAUTH_TOKEN	二选一	—	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 — 单一的 MerchantClient，包含重试机制（最多 5 次，并加入随机抖动）、分页辅助函数和写入审计钩子。
• 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：将 Reports 查询导出到 BigQuery
• v0.4：基于规则的自动修复工具（“商品被拒登时，使用修正后的属性重试”）

贡献

请参阅 CONTRIBUTING.md。欢迎提交 PR 和问题反馈——这是首个适用于 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、面向电商的 MCP、Shopify Google Merchant Center 自动化。