gconnect-mcp-all-v1

适用于 Claude.ai 自定义连接器的 True Model B Google Marketing MCP。

这不是一个仅支持 GA4 的连接器，也不是一个仅支持 Google Ads 的连接器。它是一个共享平台，目前提供两个产品适配器，并为以后扩展 DV360 预留了扩展点：

Operator
  +-- Google Connection A
  |     +-- GA4 properties
  |     +-- Google Ads customers / MCC hierarchy
  +-- Google Connection B

MCP JWT 的 sub 始终是内部的 operatorId。Google OpenID 的 sub 只存在于 google_connections.googleSubjectId 中。

Architecture

flowchart TB
  Claude["Claude.ai"]
  McpAuth["MCP OAuth 2.1"]
  Operator["operators operatorId"]
  Resolver["ConnectionResolver"]
  Ga4["GA4 adapter"]
  Ads["Google Ads adapter"]
  Dv360["DV360 future"]
  Ga4Api["GA4 APIs"]
  AdsApi["Ads REST v25"]

  Claude --> McpAuth
  McpAuth --> Operator
  Operator --> Resolver
  Resolver --> Ga4
  Resolver --> Ads
  Resolver -.-> Dv360
  Ga4 --> Ga4Api
  Ads --> AdsApi

参见 docs/architecture.md。

Related MCP server: GA4 MCP Server

Identity

• MCP 身份验证回答：谁是操作者？

• Google OAuth 回答：连接的是哪个 Google 账户？

• 唯一性由 (operatorId, googleSubjectId) 决定，绝不使用电子邮件，也绝不使用全局 Google subject。

参见 docs/identity-model.md。

Persistence

仅使用 Firestore 命名数据库 gconnect-mcp-all-v1。

不要使用 (default)（V1）或 ga4-mcp-v3（V3）。启动时会拒绝这些 ID。

参见 docs/google-connections.md。

本地开发

1. 将 .env.example 复制为 .env 并填入占位符。不要从 V3 复制密钥。

2. npm install

3. npm test

4. npm run typecheck

5. npm run dev

Claude 自定义连接器 URL 为 http://localhost:3000/mcp。健康检查地址为 GET /health。

Google Ads

使用官方 Google Ads REST v25。只读。应用开发者令牌是应用级密钥（GOOGLE_ADS_DEVELOPER_TOKEN），绝不是用户的 OAuth 凭据。

服务器会根据发现的 MCC 层级关系解析 login-customer-id。带连字符的客户 ID 会在 API 使用前进行规范化。

参见 docs/google-ads.md 和 docs/ga4.md。

部署

Cloud Run，未认证入口，Firestore 命名数据库 gconnect-mcp-all-v1。

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_PROJECT
.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_PROJECT
.\scripts\cloud-run-set-env.ps1 -ProjectId YOUR_PROJECT -AppBaseUrl https://... -GoogleClientId ... -GoogleClientSecret ... -McpTokenSecret ... -OauthStateSecret ... -TokenEncryptionKey ... -GoogleAdsDeveloperToken ...

参见 docs/deployment.md 和 docs/security.md。