Tag Pilot GA4

Tag Pilot GA4 MCP

一个免费、只读的 Model Context Protocol 服务，用于 Google Analytics 4。向 Claude、Cursor 或任何 MCP 客户端询问 GA4 数据：报告、 漏斗、实时数据、媒体资源设置，以及 Tag Pilot 跟踪健康状况检查。

**无需设置 Google Cloud，也无需复制 API 密钥。**你不需要 GCP 项目、OAuth 客户端、 服务账号或 gcloud。添加服务，提出 GA4 问题，然后在浏览器中批准一次即可。

claude mcp add ga4 -- npx -y @tagpilot/ga4-mcp

开始使用

1. 在你的 AI 客户端中安装（见下文）。无需配置。
2. 提出问题，例如 *“我有哪些 GA4 媒体资源？”*首次使用时，会打开一个浏览器窗口 （或者你的 AI 会显示一个链接和类似 ABCD-1234 的代码）：
   • 登录你的免费 Tag Pilot 账号，或创建一个；
   • 确认代码匹配，然后批准此计算机；
   • 使用有权查看你 GA4 媒体资源的 Google 账号登录，并允许 “查看和下载你的 Google Analytics 数据”。
3. 再次提问。你已连接；这台计算机会显示在 GA4 MCP 页面的已连接设备下。

安装

客户端	方法
Claude Desktop	下载扩展并打开（无需 Node.js）
Claude Code	claude mcp add ga4 -- npx -y @tagpilot/ga4-mcp
Cursor	添加到 Cursor，或使用下方的 mcp.json
VS Code	在 VS Code 中安装
Gemini CLI	gemini extensions install https://github.com/tagpilot/ga4-mcp
其他客户端	npx -y @tagpilot/ga4-mcp（stdio）

除 Claude Desktop 扩展外，其他方式都通过 npx 运行 npm 包，因此需要 Node.js 18 或更高版本。该服务也已列入 MCP Registry，名称为 io.github.tagpilot/ga4-mcp。

Claude Desktop

下载 tagpilot-ga4-mcp.mcpb 并双击（或将其拖入“设置”→“扩展”），点击安装并启用。可选的 API 密钥字段留空。该扩展包含服务，并使用 Claude Desktop 内置的 Node.js 运行。

更喜欢配置文件？在 claude_desktop_config.json 中（“设置”→“开发者”→“编辑配置”）：

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["-y", "@tagpilot/ga4-mcp"]
    }
  }
}

Claude Code

claude mcp add ga4 -- npx -y @tagpilot/ga4-mcp

Cursor

使用添加到 Cursor，或添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["-y", "@tagpilot/ga4-mcp"]
    }
  }
}

VS Code

使用在 VS Code 中安装，或运行 MCP: Add Server → Command (stdio) 并输入 npx -y @tagpilot/ga4-mcp。

Gemini CLI

gemini extensions install https://github.com/tagpilot/ga4-mcp

其他客户端（Windsurf、Zed 等）使用相同的 command 和 args。

无头环境和 CI：改用 API 密钥

如果无法在浏览器中批准，请在 GA4 MCP 页面创建密钥，并在服务的环境中设置 TAGPILOT_API_KEY=tpk_…（例如：claude mcp add ga4 --env TAGPILOT_API_KEY=tpk_... -- npx -y @tagpilot/ga4-mcp）。 使用密钥时会跳过设备连接，只显示 Google 登录链接。

连接方式，以及 Tag Pilot 能看到什么

your machine                              Tag Pilot                          Google
──────────────────────────────────────   ───────────────────────────       ──────────────────────
ga4-mcp makes a PKCE verifier       ──►  POST /v3/public/ga4/device
(it never leaves your machine)           returns a link + code ABCD-1234
any browser, any device: app.tagpilot.io/connect: log in, check the code, approve
  → creates a ga4:mcp key for this device → Google consent (read-only) ─►  accounts.google.com
                                         …/ga4/oauth/callback  ◄──────  one-time code
ga4-mcp polls for the result        ──►  POST /v3/public/ga4/device/token
                                         returns the device key + code
ga4-mcp exchanges code + verifier   ──►  POST …/ga4/oauth/token  ──►    oauth2.googleapis.com
device key + Google tokens saved in ~/.config/tagpilot/ga4-mcp/device.json (mode 600)
GA4 API calls  ─────────────────────────────────────────────────────►  analytics*.googleapis.com

它可以在任何浏览器中使用，就像 gh auth login 一样：你的计算机上不会有任何程序监听，因此也可以通过 SSH、在容器中、在 WSL 中或在远程开发设备上使用。在任何有浏览器的地方（甚至是手机）打开链接并批准；服务会在几秒内收到通知。

• GA4 数据会从你的计算机直接发送到 Google。 报告、媒体资源设置以及工具读取的其他所有内容都不会经过 Tag Pilot。
• Tag Pilot 只负责协调令牌交换。 它的 API 会将 Tag Pilot 的 Google OAuth 客户端凭据添加到 Google 的令牌端点，并返回 Google 的响应。它不会存储 Google 令牌，也绝不会记录这些令牌。它只会暂存 Google 回调中的一次性登录代码，最多 10 分钟，直到你的计算机取回该代码；没有保存在你计算机上的 PKCE 验证器，该代码就毫无用处。它只会记录发生过交换以及对应的设备（即 GA4 MCP 页面上的“上次使用”时间）。
• 只读。 唯一请求的 Google 权限范围是 analytics.readonly。所有工具都无法更改 GA4 中的任何内容。
• 你的凭据会保留在你的计算机上，路径为 ~/.config/tagpilot/ga4-mcp/device.json（只有你可以读取）：包括设备自己的 Tag Pilot 密钥和 Google 刷新令牌。访问令牌大约每小时通过 Tag Pilot 刷新一次。
• 断开连接： 在 GA4 MCP 页面的已连接设备下撤销设备，以停止刷新；运行 npx -y @tagpilot/ga4-mcp logout 删除本地凭据；然后在 myaccount.google.com/permissions 移除应用的访问权限。

工具

所有工具均为只读。媒体资源 ID 是数字形式的 GA4 ID（例如 123456789），而不是 G-XXXX 衡量 ID。

工具	功能
get_account_summaries	列出你可以读取的所有 GA4 账号和媒体资源，并提供媒体资源 ID。从这里开始。
get_property_details	时区、货币、行业、标准版/360 版，以及包含衡量 ID 的数据流。
list_google_ads_links	已关联的 Google Ads 账号。
list_property_annotations	报告注释（发布、跟踪更改、营销活动）。
get_custom_dimensions_and_metrics	自定义维度/指标及其 API 名称（customEvent:…）；也可选择包含标准维度/指标，并支持搜索。
run_report	Data API 报告：维度、指标、日期范围、筛选条件、排序、分页和总计。
run_realtime_report	最近 30 分钟的数据（GA4 360 为 60 分钟）。可用于检查跟踪更改是否已生效。
run_funnel_report	根据事件步骤创建漏斗（支持参数和维度条件）、开放式或封闭式漏斗、细分、后续操作和趋势。使用 Google 的 v1alpha API。
check_duplicate_transactions	Tag Pilot 检查。 按 transaction_id 统计购买事件：重复率、重复次数最多的 ID，以及没有 ID 的购买事件。
check_traffic_attribution	Tag Pilot 检查。 按渠道组统计会话，并计算未分配、(not set) 来源、(not set) 着陆页和直接流量的占比，同时给出可能的原因。
connect	连接此计算机：返回一个链接和一个代码，供你在浏览器中批准（你的 AI 会显示这些内容；支持 MCP URL 询问的客户端会提供打开链接的选项）。明确说 “连接我的 GA4” 即可启动连接。
connection_status	返回已连接（包含设备名称）、等待批准（再次显示链接和代码）、未连接，或发生的问题。对于尚未完成的登录，最多等待 25 秒。

报告输入项

• 日期： YYYY-MM-DD、today、yesterday 或 NdaysAgo（例如 28daysAgo）。默认：最近 28 个完整日期。最多支持 4 个范围；多个范围会添加 dateRange 列。

• 维度和指标： GA4 API 名称，例如 date、eventName、sessionSourceMedium、 pagePath、sessions、activeUsers、purchaseRevenue （完整列表）。

• 筛选条件： 必须全部匹配的条件列表；{"any": [...]} 用 OR 将条件分组，"not": true 用于取反：

  [
    {"field": "eventName", "op": "exact", "value": "purchase"},
    {"field": "country", "op": "in_list", "values": ["Poland", "Germany"], "not": true},
    {"any": [
      {"field": "pagePath", "op": "begins_with", "value": "/shop"},
      {"field": "pagePath", "op": "partial_regex", "value": "product"}
    ]}
  ]
  

  运算符：exact、contains、begins_with、ends_with、full_regex、partial_regex、in_list、 eq、lt、lte、gt、gte、between（from/to）、empty。维度和指标筛选条件是分开的输入，与 GA4 API 中相同。

• 排序： [{"field": "sessions", "desc": true}]。对于看起来像数字的维度，使用 dimension_order: "numeric"。

• 输出： 行是类似 {"date": "20261026", "sessions": 321} 的对象。默认上限为 100 行；如果还有更多结果，next_offset 会告知你。阈值处理、抽样和 (other) 行会在 notes 中说明。

关于跟踪健康状况检查

这些检查是基于几次 run_report 调用制定的经验规则，每项结果都会显示其测量内容。例如， check_duplicate_transactions 会按 transactionId 分组统计 purchase 事件，check_traffic_attribution 会在未分配流量占比达到 5% 或更高时发出标记。它们消耗的 GA4 配额与对应报告相同（3–4 次报告调用）。

故障排除

“尚未连接”（显示链接和类似 ABCD-1234 的代码）： AI 会显示这些内容。在任意浏览器中打开链接（不必使用这台电脑），登录 Tag Pilot，确认代码匹配，然后批准并允许访问 Google Analytics，接着告诉 AI 你已完成：它会重试你的问题（或调用 connection_status）。服务会在后台持续检查，因此无需重启。代码有效期为 10 分钟；过期后，请再次提问（或说“连接 GA4”）以获取新代码。若要改为从终端连接（例如通过 SSH），请运行 npx -y @tagpilot/ga4-mcp login：它会显示链接、框中的代码和倒计时，并等待你批准。

“这台电脑已与 Tag Pilot 断开连接”： 该设备已在 GA4 MCP 页面撤销，因此已移除其保存的凭据。再次请求连接即可重新连接。

“你用于 GA4 的 Google 登录已过期或被撤销”： 已移除保存的登录信息。请再次请求并重新批准。Google 会在刷新令牌闲置 6 个月或你撤销访问权限后使其过期，也可能在密码更改后使其过期。

“已登录的 Google 账号无权访问媒体资源 …”： 该 Google 账号需要拥有 GA4 媒体资源的至少 Viewer 角色。使用 get_account_summaries 查看它可以读取哪些内容。若要使用其他 Google 账号，请运行 npx -y @tagpilot/ga4-mcp logout，然后重新连接。

“Google 尚未验证此应用”： Tag Pilot 的 Google 验证尚在等待期间（测试版）会显示此消息。点击 高级 → 前往 Tag Pilot。

配额错误： GA4 Data API 配额按媒体资源计算，并按小时和每天补充。请缩短日期范围、减少维度或降低上限，并传入 return_property_quota: true 查看剩余配额。

使用 TAGPILOT_API_KEY 时： 若出现“Tag Pilot 拒绝了 TAGPILOT_API_KEY”或“没有 ga4:mcp 范围”，表示密钥已被撤销，或是在应用的其他位置创建的；请在 GA4 MCP 页面创建一个密钥，或移除该变量以使用设备连接。随后登录时会显示“请在 … 使用 Google 完成登录，然后再次请求”。

检查设置： npx -y @tagpilot/ga4-mcp status 会显示这台电脑是否已连接（包括 Tag Pilot 密钥的开头字符）以及 Google 登录状态。日志会输出到 stderr （stdout 是 MCP 通道）；在 Claude Code 中查看 claude --debug 或 /mcp。

配置

无需配置任何内容。所有变量均为可选项：

变量
TAGPILOT_API_KEY	来自 GA4 MCP 页面、用于无头/CI 环境的 ga4:mcp 密钥（tpk_…）。跳过设备连接；登录状态按密钥保存。
TAGPILOT_API_URL	Tag Pilot API 基础 URL。默认值为 https://api.tagpilot.io。
GA4_MCP_NO_BROWSER	设为 1 时，只打印/返回链接，不打开浏览器。
GA4_MCP_BROWSER	要打开的浏览器（macOS 应用名称，或 Linux/Windows 上的命令）。
GA4_MCP_AUTH_WAIT_SECONDS	工具调用等待连接的时长，超时后返回链接（连接会在后台继续）。默认值为 45（MCP 客户端通常会在 60 秒时超时）。
GA4_MCP_CONFIG_DIR	凭据目录。默认值为 ~/.config/tagpilot/ga4-mcp。

命令：npx -y @tagpilot/ga4-mcp [serve|login|logout|status|--help|--version]。不带命令时，会通过 stdio 运行 MCP 服务。logout 会移除此计算机的连接（以及所有已保存的 TAGPILOT_API_KEY 登录）；若设置了 TAGPILOT_API_KEY，则只移除该密钥的登录。请在 GA4 MCP 页面撤销设备本身。

开发

此软件包位于 tagpilot/ga4-mcp 单体仓库中，与 @tagpilot/search-console-mcp 并列；两者共享 packages/mcp-core 中的 Tag Pilot 连接和 CLI 代码。从仓库根目录运行：

npm install
npm run check      # typecheck + lint + unit tests (all packages)
npm run build      # → packages/*/dist/index.js (esbuild bundles the shared core in)
npm run e2e        # built servers over stdio against a mock broker and mock Google
npm run mcpb       # Claude Desktop extensions → packages/*/tagpilot-<name>-<version>.mcpb
npm run mcpb:smoke # unpack each bundle, check its tools, run the e2e against it

版本信息位于 package.json、src/version.ts、server.json（MCP Registry）、 mcpb/manifest.json 和仓库根目录的 gemini-extension.json 中（Gemini CLI 会从仓库根目录安装扩展）；如果这些版本不一致，npm test 会失败。发布步骤见 Tag Pilot 仓库中的 explorations/ga4-mcp/distribution.md。

与 Tag Pilot API 的代理合约位于 Tag Pilot 仓库中的 explorations/ga4-mcp/api-contract.md。

本地测试时，将 TAGPILOT_API_URL 指向本地或 beta tc-api（http://localhost:8000、 https://beta-api.tagpilot.io）。GA4_MCP_ADMIN_API_URL 和 GA4_MCP_DATA_API_URL 用于将 GA4 调用指向模拟服务（npm run e2e 会使用）。

许可证

Apache License 2.0。版权所有 2026 Tag Concierge sp. z o.o. 许可证不涵盖 Tag Pilot 名称或徽标（见 NOTICE）。