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

google-ecommerce-mcp

一个 MCP 服务，汇集线上商店决策所需的数据，可服务一家商店，也可服务多个客户端：GA4、Search Console、Merchant Center、Tag Manager、Indexing API、PageSpeed、广告平台 Google Ads、Meta Ads 和 ChatGPT Ads，以及 Meta pixel、catalog、Instagram 和 Page。默认情况下，它只读取数据，也可以准备由你批准的受控变更（暂停广告系列、更改预算、提交站点地图、在工作区中添加标签）。

向你的 AI 助手提问“我们本月获得了多少自然流量？”， “Merchant Center 中有哪些商品未获批准？”， “我的网站是否重复加载了 GA4？”，或“上个月每个广告平台分别报告了什么数据，GA4 又是怎么说的？”，它就会根据你的账号回答。开箱即用时，它只读取和报告，不会更改任何内容。如果你为某个客户端启用写入功能，助手可以提出变更计划；未经你批准，不会发送任何内容，而且任何涉及费用的操作都需要你在聊天之外的终端中批准。

由 MoonEyes 开发。这是一家规模不大的法国商店，销售 3D 打印的桌面游戏地形，因为当时没有现成的 MCP 服务能同时涵盖 GA4、Search Console 和 Merchant Center。

**写入功能默认关闭，且从未在真实账号上测试过。**此版本包含写入工具，但仅在离线环境中进行过检查，测试时使用的是根据各平台文档编写的模拟响应。启用写入功能需针对每个客户端和每个平台单独选择；创建的内容始终处于暂停状态，并且有些风险无法消除（例如，Google Ads 令牌或 ChatGPT Ads 密钥无法限制为只读）。启用前，请阅读 docs/SECURITY.md 和 docs/WRITE.md，并先在测试账号上试用。刚开始使用？请参阅 docs/QUICKSTART.md：10 分钟内创建你的第一个客户端。

**付费媒体连接器是新功能，目前仅在离线环境中测试过。**Google Ads、Meta Ads 和 ChatGPT Ads 工具使用根据各平台文档编写的模拟响应进行了检查。它们尚未在真实广告账号上运行：请将第一批数据与各平台自身界面中的数据进行比较。详情请参阅：docs/ADS.md。

文档

页面	内容
快速入门	10 分钟内创建你的第一个客户端：四条命令
多个客户端	客户端注册表 clients.json、每个客户端的密钥、隔离机制、代理机构示例
只读试点	使用一个客户端开展试点，并关闭写入功能：访问权限清单、操作步骤、如何检查写入功能已关闭、如何撤销
写入：规划、批准、应用	通过 5 个步骤开启写入功能、三个完整示例、每道锁定机制、每种拒绝情况及其解决方法
架构	组件、写入路径、逐步解析工具调用、设计选择、时序图
工具参考	所有工具（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（一个或两个商店）、Claude Code

为什么选择它

• 一个服务，一览全局。 流量和销售（GA4）、自然搜索（Search Console）、产品 Feed（Merchant Center）、跟踪配置（Tag Manager）、网站速度，以及广告平台所报告的投放效果。其他 MCP 服务通常只涵盖其中一两项。
• 支持多个客户端，彼此隔离。 代理机构只需为每个客户注册一次（ID 存在文件中，密钥存在操作系统的密钥环中）。每次调用都必须指定客户；使用其他客户的账户 ID 会被拒绝；还可以将一个服务进程固定给单个客户。
• 默认只读，按需受控写入。 读取使用各平台的允许列表，不提供写入端点。默认关闭写入；只有为每个客户和平台单独启用后，才可通过唯一流程进行写入：计划（差异、试运行、签名令牌）、由你批准（对于涉及费用、不可逆操作或个人数据的事项，需在终端中批准）、应用，并记录操作日志。目前暂停创建操作；此版本不支持启用、删除或发布。
• 妥善保管密钥。 Google 令牌存入操作系统的密钥环（Windows Credential Manager、macOS Keychain 或 Secret Service）。Google Ads 令牌单独存储在密钥环中，因为其权限范围包含写入权限。Meta 和 ChatGPT Ads 密钥通过隐藏提示输入到操作系统的密钥环中（也可以使用环境变量），绝不会放在命令行或 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	默认关闭；支持计划、审批、操作日志和回滚；从未在真实账户上测试过

适用场景：你通过一个可自托管的服务管理多个商店或客户，并希望每项更改都先以差异形式呈现，经批准后再发送。如果你只需要一种 Google 产品，或者希望使用无需安装的托管服务，上述官方服务会是更好的选择。

可以咨询的内容

每个案例都会列出问题、助手通常会调用的工具、你能了解到的信息，以及这些信息支持的决策。最终决策由你做出：默认情况下，服务只展示数据，不做任何更改；它准备的任何更改都需要你批准。可直接粘贴使用的提示词见 examples/PROMPTS.md。

流量、搜索、Feed、追踪

1. 访客和销售额从哪里来？ “本月与上月各渠道的会话数、购买量和收入。” 工具：ga4_report。你可以了解哪些渠道带来收入，哪些渠道只带来访问量。决策：接下来的一小时或一欧元该投在哪里。
2. 哪些搜索词只差一步就能进入第一页？ “排名第 5 至第 15、展示次数超过 100 的搜索词，以及它们对应的着陆页。” 工具：gsc_performance。你可以了解哪些页面已经获得展示，却只有少量点击。决策：先改写哪些标题、描述和内部链接。
3. 哪些被拒批的商品仍然获得访问？ “Merchant Center 中被拒批、但仍获得自然点击的商品。” 工具：merchant_product_issues、gsc_performance。你可以了解哪些 Feed 错误影响了仍有人访问的页面。决策：先修复这些商品，再处理其余商品。
4. 追踪数据可靠吗？ “GA4 是否加载了两次？购买标签是否只触发一次？工作区是否与线上版本一致？” 工具：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）：需要你自行比较两者。决策：这些声称的数据放在一起是否合理。
8. 哪些广告系列花了钱，却没有记录到购买？ “有支出但没有归因购买的广告系列，以及 GA4 对相同广告系列名称的记录。” 工具：gads_performance 或 meta_insights、ga4_report（维度 sessionCampaignName）。你可以了解哪些广告系列持续花费，而平台和 GA4 都没有显示销售额。决策：暂停广告系列、修复追踪，或继续等待；这些操作由你在广告平台中完成。

平台数据为何不同。 Meta 的默认归因窗口为点击后 7 天加浏览后 1 天；按本服务默认请求设置，ChatGPT Ads 的归因窗口为点击后 30 天加浏览后 1 天；Google Ads 则使用每项转化操作各自的设置。各平台会将转化归到不同日期，独立计算同一笔订单；当访客拒绝 Cookie 时，平台还可能报告建模转化（Consent Mode）。GA4 也有自己的阈值。工具无法告诉你的信息包括：广告是否 导致 了销售（增量效果）、实际订单数量（不会读取你商店的后台），以及你的同意率。

实际发现

来自 MoonEyes 自有账户和一个匿名小型企业账户的发现。它们展示了数据揭示的问题类型，并不代表承诺的结果。每项发现都注明了时间段和测量方式。这些都是单独案例，并非基准；某项修复与更好的数字同时出现，只能说明相关性，并不能保证结果。此仓库不存储这些数字背后的原始导出数据，因此无法在此重新核查。

发现	时间段	测量方式
Merchant Center：2,544 个商品信息，112 个被拒批。224 次“重量过高”拒绝源于 Feed 中克与千克的单位错误（套装被发送为约 2 吨），现已更正。一次错误的“含酒精饮料”拒绝由商品名称引起，在重命名 3 个商品后消失。移除了 Google for WooCommerce 插件创建的重复 Feed 来源。	2026 年 6 月 1—2 日审计（MoonEyes）	Merchant Center 商品状态和 Feed 来源（与 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，已提交 708 个网址，已编入索引的网址为 0，这是一个索引处理任务的起点。	2026 年 6 月 1 日（MoonEyes）	Search Console
一个 Google Ads 账户显示 96 次转化，每次 EUR 2.16，实际预订数为 10。实际费用：EUR 207.57 / 10 = 每次预订约 EUR 20.76，是显示数值的 9.6 倍。原因：在目标 CPA 出价策略下，page_view 和一个页面事件被标记为关键事件；将关键事件仅保留为预订事件后修复。小型本地服务企业，已匿名处理。	2026 年 8 月 26 日至 9 月 22 日	Google Ads 控制台（在 Ads 界面中读取，未使用这些工具）

工具

共 82 个工具。完整参数和输出见：docs/TOOLS.md。大多数工具只读取数据。*_plan_* 工具会准备变更，但不会写入任何内容。只有四个工具会写入数据，且仅适用于已启用写入权限的客户端：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	编辑非默认工作区。不会上线任何内容：不创建版本，也不发布
Indexing、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	暂停、设置每日预算、添加否定关键词、创建一个新的搜索广告系列（已暂停）
Meta ads	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	暂停、设置每日预算、创建新的广告系列、广告组和广告（均已暂停）
Meta pixel、catalog、Instagram、Page	meta_pixel_health、meta_dataset_quality、meta_catalog_diagnostics、meta_catalog_products、meta_ig_insights、meta_page_insights	meta_eco_plan_catalog_item_update	更改单个目录商品的价格、促销价、供货状态和库存
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	暂停、设置每日预算、创建新的广告系列（已暂停）

主要读取工具可以回答的问题：

工具	服务	可回答的问题
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 选择了哪个规范网址，以及上次抓取时间
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
meta_insights	Meta Ads	按层级查看支出、覆盖人数、购买量、价值和 ROAS，并支持细分
openai_ads_insights	ChatGPT Ads	展示次数、点击量、支出、转化量和归因销售额
ads_overview	Google Ads、Meta、ChatGPT Ads	并列查看某一时间段内的三个平台

付费媒体连接器

可选。可配置其中一个、两个或全部三个；未配置的连接器会返回 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）。每个密钥对应一个账号
全部	ads_overview	至少配置上述一个平台

分步说明、GAQL 规则、所有错误和已知限制：docs/ADS.md。

归因警告。 每个平台都使用自己的时间窗口、日期和模型独立归因转化，因此同一笔订单可能会被多个平台计入。各平台的转化量总和未经去重，会高估实际订单数。ads_overview 会在每个回答中重复这一点。请将这些数字理解为“各平台自称的转化量”，并与 GA4 以及本服务之外的订单数据进行比较。

默认只读，但有一项例外。 Google Ads 权限（adwords）可执行写入操作，而 Google 没有提供只读版本。未启用写入功能时，本服务只会发送读取请求，但令牌本身仍具备写入权限，因此会与其他 Google 令牌分开存储。ChatGPT Ads 的文档也没有提到只读密钥，并且同一密钥同时用于读取和写入。请参阅安全说明。

仅在离线环境中测试过读取和写入。 所有行为都已通过模拟响应进行检查；真实账号测试尚未进行，也从未向真实账号发送写入请求。尚未确认的事项：ChatGPT Ads 在使用 time_granularity=none 时返回的时区、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。目前仅在示例数据上测试过，尚未在真实客户账户上测试。利润率、目标和注释由你提供；部分数据（展示份额、Shopping 商品报告、MER）需要额外的 GAQL 查询，或由助手计算。

适用对象

• 店主。 你想要直接的答案（哪些商品卖得好、哪里出了问题、哪些广告在白白花钱），而不必打开六个仪表板。安装后，用日常语言提问，再自行决定。
• 代理商。 你为多个客户提供服务。一次安装，一个客户注册表（docs/MULTI-CLIENT.md），每次执行相同的检查，在交给客户的答复中写明归因注意事项，并且只为你选择的客户和平台开启写入功能。
• 开发者。 你想要一个小巧、易读且经过测试的服务：直接发起 HTTP 调用、按平台设置允许列表、只有一条写入路径，并提供结构化错误。欢迎提交拉取请求（参见 Contributing）。

它不会做什么

• 没有可供你查看的计划，就不会做出更改。 默认情况下，它不会写入任何内容。即使为某个客户开启了写入功能，它仍无法启用已暂停的广告系列、删除或归档任何内容、发布 Tag Manager 容器、设置出价金额或选择出价策略（新建的 Google Ads 广告系列会使用固定的手动 CPC，但不设置出价金额），也无法在此版本中上传转化数据和客户名单。它创建的所有内容都处于暂停状态。如需执行这些操作，请使用平台自带的界面。
• 不会在你不打开终端的情况下执行涉及花钱的更改。 只有在你亲自运行 google-ecommerce-mcp approve 后，预算、新广告系列和价格更改才会生效。但这无法保护你免受拥有你机器 shell 权限的助手影响（参见 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

如果你愿意不阅读就直接运行，也可以用一行命令（同一固定提交；这种方式不会检查 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 密钥则通过隐藏提示输入并存入操作系统密钥环。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 时会跳过 ChatGPT Ads（没有可提供的 ID）：可通过交互方式添加（install --skip-auth），或使用 set-secret openai-ads-key 添加。PageSpeed 密钥将依次从 --pagespeed-key（不推荐：它会留在 shell 历史记录中）、PAGESPEED_API_KEY 环境变量或隐藏提示中读取。

引导式安装。 如需逐步引导，请将 examples/INSTALL-PROMPT.md（英语）或 INSTALL-PROMPT.fr.md（法语）粘贴到 Claude 中。一次安装一个服务；客户端的访问权限检查清单见 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（一次性设置，约 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 同意屏幕（选择 External，并将自己添加为测试用户）。
4. 创建类型为 Desktop app 的 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 同意屏幕。随后，令牌会存储在你的操作系统密钥环中。运行 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> 将检查范围限制为注册表中的一个客户端。--only 接受 ga4,gsc,merchant,gtm,pagespeed,gads,meta,openai（以逗号分隔）。doctor 会读取当前 Shell 的环境变量以及 Claude Desktop 配置中的服务条目（使用 --config 和 --name 可指定其他位置）。表格后会显示“To fix”（每个问题对应的准确修复命令）、“Not set up”、Result: 行和 Next command:。退出代码 0 表示所有已配置的服务均正常，1 表示有已配置的服务无法正常工作，2 表示没有任何服务完成配置。--live 不会测试 PageSpeed（会显示为跳过：它需要页面地址，且约需 30 秒）；请让助手改为运行 pagespeed。

付费媒体（可选）

使用 google-ecommerce-mcp setup-ads --client-secret client_secret.json 配置 Google Ads（或在 install 中使用 --gads-customer-id），使用 google-ecommerce-mcp set-secret meta-access-token 并提供广告账号 ID 配置 Meta（install --yes --skip-auth --meta-account-id <id>），使用 google-ecommerce-mcp set-secret openai-ads-key 配置 ChatGPT Ads，然后使用 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。这些变量描述一家商店（旧版模式）。如需配置多个客户端，请改用注册表，并从此配置中省略 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	将此服务进程固定到注册表中的一个客户端
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，指定允许的账户，设置预算上限，暂停创建操作，配置字段允许列表，使用绑定到确切计划的签名一次性令牌，确保日志可写；对于涉及资金、个人数据、不可逆操作或高风险的计划，还需要你在终端中批准。它绝不会激活、删除或发布内容。
• 你必须了解的限制。 终端审批无法阻止拥有你机器上的 shell 或文件访问权限的助手。Google Ads 令牌和 ChatGPT Ads 密钥无法拆分为读写权限。写入策略存储在一个你（或任何以你的身份运行的程序）可以编辑的文件中。没有任何写入操作曾在真实账户上得到验证。
• setup 只请求读取权限范围。Google 没有适用于 Merchant Center（content）或 Indexing API（indexing）的只读权限范围；只有使用 --with-merchant / --with-indexing 时才会请求这些权限。
• 付费媒体。 每个平台都有自己的允许列表（固定主机，仅含少数读取端点）。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 账号和一个容器，且无法写入。使用注册表时：可使用任意数量的客户端，每个客户端都有自己的 ID 和机密信息。
• ga4_report 受 GA4 Data API 配额限制。每个平台都有自己的配额，超限时会返回 rate_limited；不会自动重试。
• 付费媒体连接器和所有写入操作均未在真实账户上测试（仅进行了离线测试）。各平台的转化归因彼此独立，不会去重；支出金额绝不会在不同币种之间转换。
• 广告平台不断变更其 API（默认版本：Google Ads v26、Meta v26.0；两者均可设置）。如果某个调用失效，请提交 issue。
• 每个客户端只能使用一个 Google Ads 客户、一个 Meta 广告账户和一个 ChatGPT Ads 密钥。使用注册表时，读取和计划中若指定的 property_id、customer_id 或 account_id 不属于该客户端，将被拒绝（id_not_owned）；只有在旧版模式（无注册表）下，这些参数才会读取凭据可访问的任何账户。
• 自 0.5.0 起支持写入：出价会被拒绝（因此某些创建操作会被阻止，例如目标需要出价上限的 Meta 广告组；新的 Google Ads 广告系列会使用固定的手动 CPC，且不设置出价金额）；不支持激活、删除和发布操作，且 max_plan_budget_micros 不可用。

贡献

请参阅 CONTRIBUTING.md。安全问题报告请参阅 SECURITY.md。

开发

pip install -e ".[dev]"
pytest

测试使用模拟 HTTP 会话离线运行；无需 Google、Meta 或 OpenAI 帐户。维护者请参阅 docs/RELEASING.md。

许可证

MIT，详见 LICENSE。