GA4 Analytics MCP V2

面向 Claude.ai 自定义连接器 的多操作员 Google Analytics 4 连接器，托管在 Google Cloud Run 上。

这是 V2 版本。它与 V1 是独立的应用程序。请勿复用 V1 的密钥、OAuth 客户端、Cloud Run 服务或 Git 远程仓库。

Operator A or Operator B
  → same Claude Custom Connector URL
  → https://<v2-host>/mcp
  → MCP OAuth (Claude → V2)
  → Google OAuth (operator's own Google account)
  → operator credentials + active GA4 property in Firestore
  → GA4 Admin / Data APIs

没有本地 stdio 服务器，也没有 Supabase。

架构

两个 OAuth 层相互关联：

1. Claude → V2： MCP OAuth 2.1（受保护资源元数据、DCR、CIMD、PKCE）。

2. V2 → Google： Google 登录在 MCP 授权内部完成。MCP 访问令牌 sub 即 Google 账号主体（sub）。邮箱仅用于显示。

每个操作员拥有：

• 自己加密的 Google 刷新令牌

• 自己可访问的 GA4 媒体资源列表（来自 Google Admin API）

• 自己持久化的活动媒体资源

操作员 A 无法使用操作员 B 的 Google 凭据，也无法选择 Google 账号 A 无法访问的媒体资源。

MCP 工具

当省略 propertyId 时，报告工具使用存储的活动媒体资源。提供的 propertyId 仅在经过认证的 Google 账号可以访问时才被接受，并成为新的活动媒体资源。

本地开发

cd D:\MCP_Servers\Ga4McpV2
npm install
copy .env.example .env.local

使用 V2 的值填写 .env.local。请勿复制 V1 的密钥。

可选的 Firestore 模拟器：

gcloud emulators firestore start --host-port=localhost:8080

在 .env.local 中设置 FIRESTORE_EMULATOR_HOST=localhost:8080 和 FIRESTORE_PROJECT_ID。

npm run dev
npm test
npm run build

• 应用：http://localhost:3000

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

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

• Google 回调：http://localhost:3000/oauth/google/callback

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

环境变量

V2 不使用 GOOGLE_REFRESH_TOKEN 或 MCP_AUTH_TOKEN。

Google Cloud 配置

尽可能使用新的 Google Cloud 项目。如果与 V1 共享项目，仍请创建独立的 Cloud Run 服务、Artifact Registry 仓库、OAuth 客户端和密钥。

启用：

• Cloud Run

• Cloud Build

• Artifact Registry

• Firestore

• Secret Manager

• Google Analytics Admin API

• Google Analytics Data API

建议的资源名称（占位符 — 请替换为您的项目）：

• Cloud Run 服务：ga4-mcp-v2

• Artifact Registry：ga4-mcp-v2

• Firestore 集合：operators

Cloud Run 服务账号应具有：

• V2 Firestore 数据库上的 roles/datastore.user

• 仅 V2 密钥上的 roles/secretmanager.secretAccessor

请勿授予服务账号 Secret Manager 管理员权限或对 V1 密钥的访问权限。

Google OAuth 客户端（仅限 V2）

创建新的 OAuth Web 应用。请勿编辑 V1 客户端。

同意屏幕：

• 用户类型：外部（或仅限 Workspace 的内部）

• 应用名称：类似 GA4 MCP Connector V2

• 范围：

  • openid

  • email

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

• 在应用处于"测试"状态时添加测试用户

• 由于 Analytics 范围属于敏感信息，非测试用户需要发布

授权的重定向 URI：

https://<v2-cloud-run-url>/oauth/google/callback

本地：

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

Claude 自定义连接器

1. 部署 V2 并将 APP_BASE_URL 设置为 Cloud Run URL。

2. 在 Claude 中添加自定义连接器。

3. URL：https://<v2-host>/mcp

4. 每个操作员从自己的 Claude 账号完成 Google 登录。

5. 如果 Google 账号有多个 GA4 媒体资源，他们选择一个。该选择将持久化，直到他们切换。

测试

npm test

单元测试涵盖：

• MCP OAuth 元数据、DCR、PKCE 和 Google 绑定的 JWT sub

• 操作员隔离（凭据和媒体资源允许列表）

• 持久化活动媒体资源

• 令牌刷新/轮换

• 已撤销的 Google 授权

• 结构化日志脱敏

不使用实时的 V1 凭据。

部署（除非被要求，否则请勿运行）

仅作记录。V1 部署必须保持不变。

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_V2_PROJECT_ID
.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_V2_PROJECT_ID
.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_V2_PROJECT_ID `
  -AppBaseUrl https://YOUR_V2_CLOUD_RUN_URL `
  -GoogleClientId YOUR_V2_CLIENT_ID `
  -GoogleClientSecret YOUR_V2_CLIENT_SECRET `
  -McpTokenSecret YOUR_MCP_TOKEN_SECRET `
  -OauthStateSecret YOUR_OAUTH_STATE_SECRET `
  -TokenEncryptionKey YOUR_TOKEN_ENCRYPTION_KEY

在接入服务时，建议对生产密钥使用 Secret Manager 引用，而不是明文环境变量。

部署后：

1. 将 Cloud Run 回调 URI 添加到 V2 OAuth 客户端。

2. 确认 Firestore 以原生模式创建。

3. 在 Claude 中添加 https://<v2-host>/mcp。

安全注意事项

• 刷新令牌在写入 Firestore 之前使用 AES-256-GCM 加密。

• MCP 工具永远不会返回访问令牌、刷新令牌或授权码。

• 日志会脱敏令牌、密钥、cookie 和授权码。

• 来自 Claude 的媒体资源 ID 会针对该操作员与实时的 Admin API 列表进行核对。

• 如果请求未绑定操作员上下文，工具将默认失败关闭。

• 生产环境中仅使用 HTTPS cookie。

Git

此仓库仅限 V2。V1 远程仓库是 git@github.com:devopsbrandmirchi/Ga4McpServer.git，绝不能添加到此。准备发布 V2 时，请创建新的 GitHub 仓库。