Google Analytics + AdSense Remote MCP

在 Cloudflare Workers 上运行的、面向 GA4 与 AdSense Management API v2 的只读 Remote MCP 服务器。HTTP 路由使用 Hono，MCP transport 使用 createMcpHandler()，客户端的 OAuth 授权使用 Cloudflare Access Managed OAuth。

一个 Worker 固定对应一组 Google OAuth refresh token，处理该 Google 账号可读取的所有 GA4 媒体资源与 AdSense 账号。无法通过工具调用替换 OAuth 凭据、Google API 主机或写入操作。

一键部署到 Cloudflare

该按钮会将此公开 GitHub 仓库复制到用户自己的账号，并输入 Worker 名称及以下配置进行构建和部署。

• 非机密配置：CF_ACCESS_TEAM_DOMAIN、CF_ACCESS_AUD

• Secret：GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_REFRESH_TOKEN

请在按下按钮之前，按照后述步骤仅授权 read-only scope 并签发 GOOGLE_REFRESH_TOKEN。Cloudflare Access Application 与 Managed OAuth 的启用由用户自己在部署后完成。

Related MCP server: Google Analytics MCP server on Cloudflare Workers

端点

MCP 工具

• ga4_run_report、ga4_run_realtime_report、ga4_run_pivot_report、ga4_run_funnel_report

• ga4_get_metadata、ga4_check_compatibility

• ga4_admin_read：GA4 Admin API v1alpha 的 accountSummaries、accounts、properties 下的 GET/list 操作。

• adsense_generate_report

• adsense_read：AdSense Management API v2 的 accounts 下的 GET/list 操作。

所有工具都在 MCP 中标注为只读，输入通过 Zod 进行验证。不接受外部 URL、任意 HTTP 头、POST/PUT/PATCH/DELETE 的任意执行。Google 的原始错误不会包含在 MCP 响应中，但为了故障排查，会将完整内容输出到部署所在 Cloudflare 账号的 Worker Logs 中。

Google OAuth 的准备

1. 在 Google Cloud Project 中启用 Google Analytics Data API、Google Analytics Admin API、AdSense Management API。

2. 配置 OAuth consent screen，仅请求 GA4 的 https://www.googleapis.com/auth/analytics.readonly 和 AdSense 的 https://www.googleapis.com/auth/adsense.readonly。

3. 在 Credentials 中创建 OAuth Client ID，Application type 选择 Desktop app。AdSense 不支持 service account，需要 Installed Application flow。

4. refresh token 有时无法重新显示，请在签发时将其保管在安全的密码管理器中。不得放在仓库、Issue、CI log、wrangler.jsonc 中。

Google 会在短时间内使 access token 失效。Worker 在每次执行 MCP 工具时使用 refresh token grant 重新获取 access token，因此 Worker 无需持久保存 token。

使用 Python 签发 refresh token

仅需 Python 3.10 及以上版本即可运行，无需额外包。scripts/get_google_refresh_token.py 使用 PKCE 监听本地 callback，不会将凭据、access token、refresh token 保存到文件。

Google Cloud Console 的 redirect URI 设置

此 Worker 不会直接从 Google 接收 callback。在 Credentials 中创建的 OAuth client 必须选择 Desktop app。Desktop app 无需在 Cloud Console 中设置 Authorized redirect URIs 或 Authorized JavaScript origins。

Python 脚本在运行时选择空闲的本地端口，并向 Google 发送例如以下的 loopback redirect URI。

http://127.0.0.1:54321/callback/

这是 Google 为 Desktop app 允许的 loopback callback。不得将 https://<worker-host>/callback、https://<worker-host>/mcp、Cloudflare Access 的 URL 注册为 Google OAuth client 的 redirect URI。另外，也请避免使用 Web application 类型的 OAuth client 运行此脚本。

python scripts/get_google_refresh_token.py

系统会提示输入 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET。在浏览器中登录 Worker 所使用的 Google 账号，仅授权以下 read-only scope。

如需撤销浏览器授权，请在监听中的终端按 Ctrl+C。将关闭本地 callback listener，不保存 token 直接退出。

• https://www.googleapis.com/auth/analytics.readonly

• https://www.googleapis.com/auth/adsense.readonly

复制成功时显示的仅一行内容，输入到 Deploy Button 的 GOOGLE_REFRESH_TOKEN Secret 栏，或以下交互命令中。

pnpm wrangler secret put GOOGLE_REFRESH_TOKEN

如果 Client ID / secret 也未设置，请同样进行设置。

pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET

如果 Google OAuth consent screen 仍为 External + Testing，refresh token 通常会在 7 天后失效。在持续使用之前，请迁移到 Production 并完成 Google 要求的 verification。如果发生 invalid_grant，请在 Google 账号中撤销本应用的访问权限后重新运行此脚本，并更新 Worker Secret。

本地开发

要求：Node.js 20 及以上、Corepack、可使用 Cloudflare Zero Trust 的 Cloudflare 账号。

corepack enable
pnpm install
Copy-Item .dev.vars.example .dev.vars
pnpm check
pnpm dev --local

在 .dev.vars 中设置真实的 Google 凭据。此文件不会添加到 Git。

部署到 Cloudflare

1. 将 wrangler.jsonc 中的 name、CF_ACCESS_TEAM_DOMAIN、CF_ACCESS_AUD 修改为你的 Cloudflare Access 配置值。

2. 逐个设置 Secret。

pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET
pnpm wrangler secret put GOOGLE_REFRESH_TOKEN
pnpm run deploy

3. 在 Cloudflare Zero Trust Dashboard 中，针对 Worker 的 https://<worker-host>/mcp 创建 MCP server application。

4. 创建允许指定邮箱或 ID group 的 Access Policy，并拒绝范围外的用户。

5. 在 Advanced settings 中启用 Managed OAuth。确认 Application Audience tag 和 Team Domain 与 Worker 配置值一致。

Cloudflare Access 负责 OAuth discovery、Dynamic Client Registration、Authorization Code Flow、PKCE、Access token 的更新。请勿在 Worker 内添加自定义的 /authorize、/token、/register。

MCP 客户端连接

MCP endpoint 为 https://<worker-host>/mcp。首次连接时会打开 Cloudflare Access 的登录和授权页面。

• Inspector：启动 npx @modelcontextprotocol/inspector@latest 并连接 endpoint，通过 Scan / List Tools 查看所有工具。

• Codex 等：将 endpoint 注册到支持 OAuth 的 Remote MCP 配置中。

• ChatGPT：在 Developer mode 的 Custom MCP app / connector 中注册 endpoint，完成 OAuth 授权后执行 Tool Scan。ChatGPT 的可用性取决于订阅计划、Workspace 设置和地区。

验证

pnpm check

check 会依次执行 ESLint、TypeScript、Vitest、Worker binding 类型同步、wrangler deploy --dry-run。不会自动测试对真实 Google 账号的查询。部署后，请通过 Access 在 Inspector 和所使用的 MCP 客户端中，各执行一次 GA4 report 和 AdSense report。

Google API 的故障排查

Google API 失败时，Worker 会向 Cloudflare Workers Logs 输出 JSON 格式的诊断事件。会不省略地输出 Google 的 HTTP 响应正文、请求 URL 和正文、异常名称、消息、堆栈跟踪。这是仅供部署所在 Cloudflare 账号的日志查看者查看的调试配置。如需将日志外部转发、共享或公开，请事先禁用此详细日志。MCP 响应中仍不会包含这些内容。

pnpm wrangler tail --format json

示例：{"event":"google_request_failed","tool":"ga4_run_report","category":"google_api","upstreamStatus":403,"error":{"request":{"url":"..."},"responseBody":"...","stack":"..."}}。oauth_refresh 表示 refresh token 更新失败，google_api 表示 GA4 / AdSense API 被拒绝，unexpected 表示网络等意外失败。

许可证

MIT License