ga4-mcp-worker

一个只读的 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 测试覆盖。

认证模式：每用户 OAuth

每位团队成员都用自己的 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，以及队友们曾经需要输入的密码。

文档

Related MCP server: GA4 MCP Server

我们的 GA4 媒体资源

这个服务是媒体资源无感知的（property-agnostic）：每个工具都接受 property_id，既可以传 314138239，也可以传 "properties/314138239"。如果不传，则回退到 wrangler.toml 里的 DEFAULT_PROPERTY_ID，默认指向上述权威媒体资源，这样队友不用记编号。调用 get_account_summaries 可以列出这些凭据实际能看到的所有内容。

工具（9 个）

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。

工具描述是刻意写长的——它们包含了每种过滤器句式的可执行示例，也是模型学习请求格式的唯一来源。请把对这些内容的编辑视为行为变更。

端点

其他路径统一返回 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)），以便跟踪配额来源。

只读保障

以下三层相互独立，且都保持启用：

1. OAuth scope（授权范围） —— 每个 token，无论是旧共享的还是队友个人的，都只会请求 https://www.googleapis.com/auth/analytics.readonly，不会申请更多；OAuth 模式还会加上 openid/email（用于身份识别——见 src/google-oauth.ts，这两个 scope 不授予数据访问权限）。Google 会在服务端拒绝写操作。这才是真正的保证。 SETUP-GUIDE.md 里演示了如何通过 tokeninfo 验证这一点。

2. 端点白名单 —— 两个 fetch 辅助函数会在发起请求前检查锚定正则。如果将来的编辑引入了写端点，会直接抛出错误而不是发送请求。

3. 没有修改性动词 —— 代码库中不存在 PATCH、PUT 或 DELETE。全项目只有三处 fetch 调用：token 刷新（POST）、gaGet（GET）和 gaPost（POST）。

:runReport、:runRealtimeReport 和 :runFunnelReport 虽然是 HTTP POST，但都是查询——请求体携带报表定义，是因为查询串放不下而已。它们在 GA4 中不创建也不修改任何数据。

快速命令

npm install

npm run typecheck && npm run dry-run

npm run deploy

npm run tail

curl -s https://ga4-mcp-worker.YOUR-SUBDOMAIN.workers.dev/health

部署两种认证模式都需要的那两个 secrets（请采用交互式粘贴——通过管道传入会改变值）：

npx wrangler secret put GOOGLE_CLIENT_ID

npx 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 部分