一个只读的 Google Analytics 4 MCP 服务器，运行在 Cloudflare Workers 上，让团队成员无需在本地安装任何东西就能通过 Claude 查询 GA4 —— 不需要 Python，不需要 gcloud，不需要 ADC 凭据文件，而且从这个版本开始，也不需要共享密码。 接入方式就是点击“Connect”，用你自己的 Google 账户登录，然后以你自己的身份回答 GA4 问题。
它复刻了官方 googleanalytics/google-analytics-mcp stdio 服务器的工具表面，但直接调用 Google Analytics REST API，因为 Google 的客户端库无法在 Workers 运行时上运行。
请先阅读： docs/IMPLEMENTATION-NOTES.md § 已测试和未测试的内容。 实时端到端验证已经包含在内，但少数几块（v1alpha 端点、分页）仍只有 fixture 测试覆盖。
每位团队成员都用自己的 Google 账户登录。没有共享密钥，也没有大家共同依赖的单一 Google 凭据——完整设计以及它与已退役的共享密钥模式的区别，见 PRODUCTION.md § 1 和 docs/PRODUCTION-PART2.md § 8。登录限制为 @zuddl.com 的 Google 账户（wrangler.toml 中的 ALLOWED_EMAIL_DOMAIN）。
GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET 仍然必需——Google 要求每个请求用户数据的应用都必须完成注册，而这两个值就是注册本身，部署时设置一次即可。去掉的是手工签发的 refresh token，以及队友们曾经需要输入的密码。
文件 | 内容 |
从零开始讲解首次部署，不假设任何 OAuth 背景知识。包括创建 Google 应用、部署、测试、连接 Claude。从这里开始。 | |
身份模型、监控、GA4 配额、密钥轮换、本地开发、runbook、安全清单、OAuth 内部机制。大规模部署前请阅读。 | |
这个实现合理的关键点、已经测试和未测试的内容，以及运行成本。 | |
| MCP 服务器：工具、fetch 辅助函数、normalizer、router。注释详细。 |
| “sign in with Google”处理逻辑 —— |
| Worker 配置。注意 |
| 本地开发模板。复制为 |
Related MCP server: GA4 MCP Server
媒体资源 ID | 名称 | Measurement ID | 状态 |
| New zuddl website GA4 property |
| 权威（canonical），除非另有说明，请使用这一个。 |
| legacy | — | 历史资源；只查看历史数据，勿用于当前报告。 |
| legacy | — | 历史资源；只查看历史数据，勿用于当前报告。 |
这个服务是媒体资源无感知的（property-agnostic）：每个工具都接受 property_id，既可以传 314138239，也可以传 "properties/314138239"。如果不传，则回退到 wrangler.toml 里的 DEFAULT_PROPERTY_ID，默认指向上述权威媒体资源，这样队友不用记编号。调用 get_account_summaries 可以列出这些凭据实际能看到的所有内容。
工具 | 方法 + 端点 | 用途 |
| POST | 核心工具。 历史数据报告。完整参数集。 |
| POST | 最近约 30 分钟。独立、较简洁的 schema。 |
| POST | 有序步骤序列与流失分析。 |
| POST | 转化、广告支出、ROAS、归因建模。受限字段列表。 |
| GET | 自定义字段，以可查询的 |
| GET | 列出这些凭据可以读取的所有内容。无需参数。 |
| GET | 时区、货币、服务等级。时区可以解释日期不一致的问题。 |
| GET | 带日期的注释，用于解释数据尖峰与下跌。 |
| GET | 已关联的 Google Ads 账户；确认广告支出指标是否可能有数据。 |
run_report 接受完整的官方参数集: property_id、date_ranges（列表，所以一次请求即可完成周期对比）、dimensions、metrics、dimension_filter、metric_filter、order_bys、limit、offset、currency_code、return_property_quota。run_realtime_report 使用相同结构，但不含 date_ranges 和 currency_code。
工具描述是刻意写长的——它们包含了每种过滤器句式的可执行示例，也是模型学习请求格式的唯一来源。请把对这些内容的编辑视为行为变更。
端点 | 认证 | 用途 |
| OAuth bearer token | MCP 连接（Streamable HTTP）。没有 |
| — | 由 |
| — | Google 登录后的跳转入口。不要人工直接打开。 |
| 无 | 状态检查。 |
| 无 | 纯文本状态横幅，显示当前认证模式。 |
其他路径统一返回 404。
/health在 OAuth 模式下能担保的更少。 没有单一的共享凭据可供检查，所以200只说明应用注册已配置好、授权存储（OAUTH_KV）可访问，并不代表某个特定用户的登录仍然有效。某个用户的授权可能已过期或被撤销，而/health仍是绿色。这属于 per-user 认证的固有特性，不是缺陷。
Worker 会为每个 MCP 请求、每次被拒绝的认证尝试、每个工具错误以及每次健康检查失败记录一行 JSON 日志，此外还有 OAuth 专用事件（oauth_authorize_redirect、oauth_authorized、oauth_domain_rejected 等）。任何令牌（token）内容都不会被记录。所有 Google API 调用都会携带自定义 User-Agent（ga4-mcp-worker/1.0.0 (+cloudflare-workers)），以便跟踪配额来源。
以下三层相互独立，且都保持启用：
OAuth scope（授权范围） —— 每个 token，无论是旧共享的还是队友个人的，都只会请求 https://www.googleapis.com/auth/analytics.readonly，不会申请更多；OAuth 模式还会加上 openid/email（用于身份识别——见 src/google-oauth.ts，这两个 scope 不授予数据访问权限）。Google 会在服务端拒绝写操作。这才是真正的保证。 SETUP-GUIDE.md 里演示了如何通过 tokeninfo 验证这一点。
端点白名单 —— 两个 fetch 辅助函数会在发起请求前检查锚定正则。如果将来的编辑引入了写端点，会直接抛出错误而不是发送请求。
没有修改性动词 —— 代码库中不存在 PATCH、PUT 或 DELETE。全项目只有三处 fetch 调用：token 刷新（POST）、gaGet（GET）和 gaPost（POST）。
:runReport、:runRealtimeReport 和 :runFunnelReport 虽然是 HTTP POST，但都是查询——请求体携带报表定义，是因为查询串放不下而已。它们在 GA4 中不创建也不修改任何数据。
npm installnpm run typecheck && npm run dry-runnpm run deploynpm run tailcurl -s https://ga4-mcp-worker.YOUR-SUBDOMAIN.workers.dev/health部署两种认证模式都需要的那两个 secrets（请采用交互式粘贴——通过管道传入会改变值）：
npx wrangler secret put GOOGLE_CLIENT_IDnpx wrangler secret put GOOGLE_CLIENT_SECRET从 Claude Code 连接——无需 header，因为登录发生在浏览器中：
claude mcp add --transport http --scope user ga4 https://ga4-mcp-worker.YOUR-SUBDOMAIN.workers.dev/mcp然后在交互式 claude 会话中，运行 /mcp，选择 ga4，用 Google 登录即可。
陷阱、测试覆盖与运行成本： docs/IMPLEMENTATION-NOTES.md
首次部署指南： SETUP-GUIDE.md → 第 2 部分
加固、监控与 OAuth 操作手册： PRODUCTION.md → 第 2 部分
This server cannot be deployed
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
Read-only Google Analytics 4 MCP server for AI assistants.
Hosted MCP server for GA4, Google Ads and Search Console. Google OAuth, nothing to install.
Hosted MCP server for marketing agencies: connect Google Ads, GA4, Search Console, Meta, LinkedIn and more to Claude or ChatGPT. Pull reports and make changes via OAuth login, no setup.
