GA4 Analytics MCP

用于 Claude.ai 自定义连接器 的个人 Google Analytics 4 连接器，托管在 Google Cloud Run 上。

Claude.ai Custom Connector
  → https://ga4-mcp-xxxxx-uc.a.run.app/ga4mcp
  → Cloud Run
  → Google Analytics Data API
  → your GA4 properties

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

两个认证层保持独立：

1. Claude → MCP： MCP OAuth（CIMD / DCR）

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

MCP 工具

Related MCP server: Google Analytics MCP Server

本地开发

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。在添加自定义连接器之前，请先部署到 Cloud Run。

Google Cloud 设置（一个项目）

使用同一个 Google Cloud 项目来管理 API、OAuth 和 Cloud Run。

1. 安装并登录

1. 安装 Google Cloud SDK。

2. 运行：

gcloud auth login
gcloud auth application-default login

3. 在 Google Cloud 控制台 中创建或选择一个项目。

gcloud config set project YOUR_PROJECT_ID

2. 启用 API

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_PROJECT_ID -Region us-central1

这将启用：

• Cloud Run

• Cloud Build

• Artifact Registry

• Google Analytics Data API

• Google Analytics Admin API

或者在控制台中启用：API 和服务 → 库。

3. OAuth 同意屏幕和 Web 客户端

此 Google OAuth 客户端仅用于让 Cloud Run 读取你的 GA4 数据。它不是 Claude.ai 高级设置中的客户端。

1. 打开 API 和服务 → OAuth 同意屏幕。

2. 用户类型：对于个人 Gmail 账号，选择 外部。

3. 应用名称：GA4 MCP。

4. 如果你处于测试模式，将自己添加为测试用户。

5. 发布到 生产环境，这样刷新令牌不会在 7 天后过期。

6. 创建 OAuth 客户端 ID 凭据。

7. 应用类型：Web 应用。

8. 授权重定向 URI（添加两个）：

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

   • https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback
     （首次部署后使用真实的 Cloud Run URL）

9. 此应用使用的范围：

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

10. 复制客户端 ID 和客户端密钥。不要提交到版本控制。

你授权的 Google 账号必须已拥有 Claude 要查询的 GA4 资源的访问权限。

部署到 Cloud Run

默认服务名称：ga4-mcp。默认区域：us-central1。

.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_PROJECT_ID -Region us-central1

脚本会输出：

https://ga4-mcp-XXXXXXXX-uc.a.run.app
https://ga4-mcp-XXXXXXXX-uc.a.run.app/ga4mcp
https://ga4-mcp-XXXXXXXX-uc.a.run.app/health
https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback

服务以 允许未认证访问 的方式部署。这是必需的。Claude.ai 从 Anthropic（160.79.104.0/21）连接。认证方式为 MCP_AUTH_TOKEN / MCP OAuth，而非 Cloud Run IAM。

设置环境变量

.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_PROJECT_ID `
  -AppBaseUrl "https://ga4-mcp-XXXXXXXX-uc.a.run.app" `
  -GoogleClientId "....apps.googleusercontent.com" `
  -GoogleClientSecret "...." `
  -McpAuthToken "a-long-random-string"

然后，如果尚未添加，将 Cloud Run 回调 URL 添加到 Google OAuth 客户端。

连接 Google

1. 打开 https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google

2. 输入 MCP_AUTH_TOKEN

3. 使用你的 Google 账号登录

4. 从成功页面复制 GOOGLE_REFRESH_TOKEN

5. 设置它，并让 Cloud Run 启动一个新版本：

.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_PROJECT_ID `
  -AppBaseUrl "https://ga4-mcp-XXXXXXXX-uc.a.run.app" `
  -GoogleClientId "....apps.googleusercontent.com" `
  -GoogleClientSecret "...." `
  -McpAuthToken "a-long-random-string" `
  -GoogleRefreshToken "1//...."

Cloud Run 无法从容器内部写入环境变量。这与任何无服务器主机遵循相同的规则。

确认服务

https://ga4-mcp-XXXXXXXX-uc.a.run.app/health

必须返回：

{"status":"ok"}

环境变量

在 Cloud Run 服务上设置这些变量。不要将它们放入 Git。

可选的控制台路径：Cloud Run → ga4-mcp → 编辑并部署新版本 → 变量和密钥。

Claude.ai 自定义连接器

1. 确认 /health 返回 {"status":"ok"}。

2. 完成 Google OAuth 并设置 GOOGLE_REFRESH_TOKEN。

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

4. 名称：GA4 Analytics

5. URL：

https://ga4-mcp-XXXXXXXX-uc.a.run.app/ga4mcp

6. 将高级 OAuth 客户端 ID / 密钥留空。

7. 点击 添加。

8. 在 + → 连接器 中启用该连接器。

9. 首次调用 GA4 工具时会显示 连接。在此应用的同意页面中输入 MCP_AUTH_TOKEN（不是你的 Google 密码）。

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

手动 gcloud（如果你不想使用脚本）

gcloud artifacts repositories create ga4-mcp --repository-format=docker --location=us-central1
gcloud builds submit --config cloudbuild.yaml --substitutions=_REGION=us-central1
gcloud run services describe ga4-mcp --region us-central1 --format="value(status.url)"
gcloud run services update ga4-mcp --region us-central1 --update-env-vars APP_BASE_URL=https://...,GOOGLE_CLIENT_ID=...,GOOGLE_CLIENT_SECRET=...,GOOGLE_REDIRECT_URI=https://.../oauth/google/callback,MCP_AUTH_TOKEN=...

安全

• 绝不要记录 Google 令牌、授权码、客户端密钥或 MCP JWT。

• MCP 工具永不返回密钥。

• 只有 GOOGLE_REFRESH_TOKEN 以 Cloud Run 环境变量的形式持久化。

• Cloud Run 入口设为公开，以便 Claude 连接。请勿在 /ga4mcp 前再放置 Cloud IAP / IAM 登录。

• 生成一个长的随机 MCP_AUTH_TOKEN。

日期

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

已知限制

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

• Cloud Run 无法在运行时持久化文件或修改环境变量；请设置 GOOGLE_REFRESH_TOKEN 并部署新版本。

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

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

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

• 当 min-instances 为 0 时，冷启动会增加几秒钟。

为 Cloud Run 添加的文件