GA4 Analytics MCP

用于 Claude.ai 自定义连接器 的个人 Google Analytics 4 连接器。一个 Google 账户，一个 MCP 服务器，部署在 Vercel 上。

Claude.ai Custom Connector
  → https://<VERCEL_PROJECT_NAME>.vercel.app/ga4mcp
  → Vercel Streamable HTTP MCP
  → Google Analytics Data API
  → your GA4 properties

没有本地 stdio 服务器，没有 npx 要求，也没有 claude_desktop_config.json。

两个认证层保持分离：

1. Claude → MCP： MCP OAuth（CIMD / DCR / 可选的 Advanced Settings 客户端）

2. MCP → Google： 存储在 GOOGLE_REFRESH_TOKEN 中的 Google OAuth 刷新令牌

MCP 工具

本地开发

npm install
copy .env.example .env.local

填写 .env.local，然后：

npm run dev

• 应用：http://localhost:3000

• MCP：http://localhost:3000/ga4mcp

• Google OAuth：http://localhost:3000/oauth/google

• 健康检查：http://localhost:3000/health

npm test
npm run build

Claude.ai 无法访问 localhost。在添加自定义连接器之前，请先部署到 Vercel。

Google Cloud 设置

这仅用于 MCP 服务器 读取您的 GA4 数据。它不是 Claude.ai 连接器 OAuth 客户端。

1. 创建或选择一个 Google Cloud 项目。

2. 启用 Google Analytics Data API。

3. 启用 Google Analytics Admin API。

4. 配置 OAuth 同意屏幕（个人 Gmail 选择外部）。发布到生产环境，以便刷新令牌在 7 天后不会过期。

5. 创建一个 Web 应用 OAuth 客户端。

6. 授权的重定向 URI：

   • http://localhost:3000/oauth/google/callback

   • https://<VERCEL_PROJECT_NAME>.vercel.app/oauth/google/callback

7. 此应用使用的范围：

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

8. 将客户端 ID 和密钥复制到环境变量中。

然后访问 /oauth/google，输入 MCP_AUTH_TOKEN，并使用拥有您 GA4 资源的 Google 账户登录。

• 在本地，刷新令牌会写入 .env.local。

• 在 Vercel 上，将 GOOGLE_REFRESH_TOKEN 粘贴到项目环境变量中并重新部署。

环境变量

Vercel

npm i -g vercel
vercel
vercel --prod

在 Vercel 项目中添加环境变量。在生产环境上完成首次 Google OAuth 后，设置 GOOGLE_REFRESH_TOKEN 并重新部署。

在生产环境上禁用部署保护 / Vercel 身份验证。 Claude.ai 从 Anthropic 的网络（160.79.104.0/21）连接。如果 Vercel SSO 位于 /ga4mcp 之前，连接器将无法连接。

生产环境 URL：

https://<VERCEL_PROJECT_NAME>.vercel.app/ga4mcp
https://<VERCEL_PROJECT_NAME>.vercel.app/oauth/google/callback
https://<VERCEL_PROJECT_NAME>.vercel.app/health

自定义域名是可选的，稍后可添加。继续使用 APP_BASE_URL，这样无需更改代码。

Claude.ai 自定义连接器

1. 部署到 Vercel 并确认 https://<VERCEL_PROJECT_NAME>.vercel.app/health 返回 {"status":"ok"}。

2. 在 https://<VERCEL_PROJECT_NAME>.vercel.app/oauth/google 连接 Google。

3. 将 GOOGLE_REFRESH_TOKEN 放入 Vercel 环境变量并重新部署。

4. 在 Claude.ai 中打开 自定义 → 连接器 → 添加自定义连接器。

5. 名称：GA4 Analytics

6. URL：

   https://<VERCEL_PROJECT_NAME>.vercel.app/ga4mcp

7. 将高级 OAuth 客户端 ID / 密钥留空。Claude 将针对此服务器的授权端点使用 CIMD。

8. 点击 添加。

9. 在聊天 + → 连接器 菜单中启用连接器。

10. 首次 GA4 工具调用会显示一个 连接 卡片。在此应用的同意页面上输入 MCP_AUTH_TOKEN（而不是您的 Google 密码）。

11. 提问：我昨天有多少用户？

initialize 和 tools/list 是公开的，以便 Claude 可以发现工具。tools/call 返回 HTTP 401 并带有 WWW-Authenticate，直到 MCP OAuth 完成。

安全性

• 切勿记录 Google 令牌、授权码、客户端密钥或 MCP JWT。

• MCP 工具从不返回密钥。

• Google 访问令牌不存储；只有 GOOGLE_REFRESH_TOKEN 持久保存在环境变量中。

• 不要将密钥放入 Git。

日期

原样传递给 GA4：today、yesterday、7daysAgo、30daysAgo、90daysAgo 或 YYYY-MM-DD。date 维度以 YYYYMMDD 格式返回。

已知限制

• 一个 Google 账户和一个刷新令牌。

• Vercel 无法在运行时写入环境变量；粘贴 GOOGLE_REFRESH_TOKEN 并重新部署。

• Google 测试模式下的刷新令牌大约在 7 天后过期。

• 实时数据大约为最近 30 分钟。

• 报告大小限制为 10,000 行。

• 我无法从此仓库完成实时的 Claude.ai 点击流程；这需要您的 Claude 和 Vercel 账户。