GA4 MCP 服务器

面向生产环境、多租户的 Google Analytics 4 MCP 服务器，专为 Claude 设计。

这是更大平台中的首个连接器。共享基础设施（认证、客户端、Google OAuth 令牌存储、授权、日志记录、错误处理）可复用。GA4 专属代码位于 src/connectors/ga4 和 src/mcp/ga4 下。请勿将其视为一个单一的 Google 营销 MCP。

架构

Claude
  |  MCP OAuth 2.1 + Streamable HTTP
  v
Next.js / Vercel  (/mcp)
  |-- MCP tools (ga4_*)
  |-- Authorization (client_members only)
  |-- GA4 service
  |-- Google OAuth token manager
  v
Supabase
  |-- clients
  |-- client_members   (application identity)
  |-- google_connections (Google credential, not app identity)
  |-- ga4_properties

应用程序用户是 Supabase Auth 用户。租户访问权限仅通过 client_members(user_id, client_id, role) 控制。Google 关联账户是客户端拥有的凭证，而非应用程序用户。

本地设置

npm install
cp .env.example .env.local
# fill in the values documented below
npx supabase start   # or link a remote project
npx supabase db reset --local
npm run dev

打开 http://localhost:3000，创建一个应用程序账户，创建一个客户端，然后连接 Google Analytics。

Google Cloud 设置

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

2. 启用 Google Analytics Data API 和 Google Analytics Admin API。

3. 配置 OAuth 同意屏幕（外部或内部）。

4. 创建 OAuth 2.0 客户端 ID 凭证（Web 应用程序）。

5. 授权重定向 URI：

   • 本地：http://localhost:3000/api/auth/google/callback

   • 生产环境：https://<your-domain>/api/auth/google/callback

6. 仅请求 GA4 作用域：

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

   • openid

   • email

请勿为此连接器添加 DV360 或 Google Ads 作用域。

GA4 设置

1. 使用电子邮件/密码登录此应用（应用程序身份）。

2. 创建一个客户端（您将成为 client_members 中的 owner）。

3. 可选地添加其他应用程序用户为 owner 或 member。

4. 点击连接 Google Analytics。这将把 Google 凭证附加到客户端。

5. 关联从该 Google 账户发现的一个或多个 GA4 媒体资源。

未点击“连接”的成员，只要拥有 client_members 行，仍可查询该客户端。

Supabase 设置

此仓库包含 supabase/migrations 中的 SQL 迁移。使用 CLI 创建它们；不要自行发明文件名。

本地：

npx supabase start
npx supabase db reset --local

远程：

npx supabase link --project-ref <project-ref>
npx supabase db push

服务角色密钥仅限服务器使用。切勿将 SUPABASE_SERVICE_ROLE_KEY 或 Google 刷新令牌暴露给浏览器。

环境变量

参见 .env.example。必需项：

请勿将 GA4 媒体资源 ID 放入 .env。媒体资源属于 Supabase 中的客户端。

生成令牌加密密钥：

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

MCP 设置（Claude）

远程端点：

https://<your-domain>/mcp

此服务器实现了 MCP OAuth 2.1：

• 受保护资源元数据：/.well-known/oauth-protected-resource

• 授权服务器元数据：/.well-known/oauth-authorization-server

• 授权：/oauth/authorize（应用程序登录 + 同意）

• 令牌：/oauth/token（authorization_code + refresh_token，PKCE S256）

• 注册：/oauth/register（DCR 回退）

• 已声明 CIMD（client_id_metadata_document_supported）

在 Claude 中：设置 → 连接器 → 添加自定义连接器 → 粘贴 https://<your-domain>/mcp。Claude 将运行 OAuth。您批准后，工具即可使用。

本地检查器：

npx @modelcontextprotocol/inspector

使用 Streamable HTTP 连接到 http://localhost:3000/mcp。您仍然需要来自 OAuth 流的有效 MCP Bearer 令牌。

工具

每个工具都需要 client_id。媒体资源作用域的工具还需要一个关联的 property_id。在调用 Google 之前，授权始终检查 client_members。

示例：ga4_run_report

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "date_start": "2026-08-01",
  "date_end": "2026-08-15",
  "dimensions": ["country"],
  "metrics": ["activeUsers", "sessions", "totalRevenue"],
  "limit": 10
}

示例：ga4_compare_periods

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "current_start": "2026-08-01",
  "current_end": "2026-08-15",
  "previous_start": "2026-07-17",
  "previous_end": "2026-07-31",
  "metrics": ["activeUsers", "sessions", "totalRevenue"]
}

然后 Claude 可以回答诸如以下问题：

• 昨天我们有多少用户？

• 本月排名前 10 的国家

• 将本月与上月进行比较

• 现在网站上有多少活跃用户？

测试

npm test

测试使用模拟的 Google 和 Supabase。它们从不使用生产 OAuth 令牌。

Vercel

部署 Next.js 应用并设置相同的环境变量。MCP_BASE_URL 和 GOOGLE_REDIRECT_URI 必须使用生产域名。/mcp 路由在 Node.js 运行时上运行，最大持续时间为 60 秒。

项目布局

src/
  auth/              application authentication
  authorization/     authorizeClient via client_members
  oauth/             Google OAuth + token manager
  mcp-oauth/         MCP OAuth 2.1 authorization server
  connectors/ga4/    Google Analytics APIs
  mcp/ga4/           MCP tools
  repositories/      Supabase data access
  app/mcp/           Streamable HTTP transport

未来的连接器（DV360、Google Ads）应添加 src/connectors/<name> 和 src/mcp/<name>，并复用共享核心。请勿创建一个通用的 Google API 垃圾场。