Google Analytics 4 MCP

Google Analytics 4 MCP

适用于 Google Analytics 4 的只读 MCP 服务。17 个工具涵盖 Data API 和 Admin API 的所有读取功能：标准、批量、透视、实时和漏斗报告；元数据目录和兼容性检查；以及属性、数据流、自定义维度和指标、关键事件、受众群体、Google Ads 链接、注释和访问报告的管理列表。我们在生产环境中为所有分析客户端运行此服务。

安装

Claude Code：

claude mcp add ga4 -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json -- uvx scalably-ga4-mcp

Codex：

codex mcp add ga4 --env GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json -- uvx scalably-ga4-mcp

Claude Desktop：从最新的 GitHub 发布版本下载 ga4-mcp.mcpb 并打开。

设置

1. 在 Google Cloud 中创建或选择一个项目，并在其中启用 Google Analytics Data API 和 Google Analytics Admin API（“API 和服务”中的“库”）。
2. 在该项目中创建一个服务账号，并下载其 JSON 密钥。
3. 在每个要查询的 GA4 属性中，将服务账号的电子邮件地址添加为 Viewer（“管理”中的“属性访问权限管理”）。

无需 OAuth 同意屏幕；此服务使用 analytics.readonly 范围，以服务账号身份进行身份验证。一个服务账号可以读取授予其访问权限的任何属性，因此除上述第 3 步外，无需针对每个客户端单独配置。

首先调用 ga4_list_account_summaries，以发现服务账号可访问的 property_id 值，然后将其中一个传入报告或管理工具。

工具（17 个）

工具	功能
ga4_list_account_summaries	列出此服务账号可访问的所有 GA4 账号及其子属性
ga4_get_property_details	获取单个 GA4 属性的完整元数据
ga4_list_data_streams	列出 GA4 属性上的所有数据流（Web、iOS、Android）
ga4_list_custom_dimensions	列出 GA4 属性上配置的自定义维度
ga4_list_custom_metrics	列出 GA4 属性上配置的自定义指标
ga4_list_key_events	列出 GA4 属性上的关键事件（以前称为转化）
ga4_list_audiences	列出 GA4 属性上定义的受众群体
ga4_list_google_ads_links	列出关联到 GA4 属性的 Google Ads 链接
ga4_list_property_annotations	列出 GA4 属性上的报告注释
ga4_run_access_report	审计日志：查看过去 12 个月内谁读取了 GA4 属性中的哪些内容
ga4_get_metadata	获取某个属性完整的 GA4 维度和指标目录
ga4_run_report	运行 GA4 标准报告，是核心工具
ga4_batch_run_reports	在一次往返中最多运行 5 份 GA4 报告
ga4_run_pivot_report	运行 GA4 透视报告
ga4_run_realtime_report	运行涵盖过去 30 分钟的 GA4 实时报告
ga4_check_compatibility	验证某个维度和指标组合能否一起查询
ga4_run_funnel_report	运行 GA4 漏斗报告（v1alpha，流失分析）

配置

变量	必需	用途
GOOGLE_APPLICATION_CREDENTIALS	是	Google 服务账号 JSON 文件的路径，该文件需具有 analytics.readonly 范围；将每个属性共享给服务账号电子邮件地址
GA4_LOG_LEVEL	否	INFO（默认值）或 DEBUG

过滤表达式格式

每个接受 dimension_filter / metric_filter 的工具都接收一个 dict：

{"filter": {"field_name": "country", "string_filter": {"value": "US"}}}

使用布尔组组合：

{"and_group": {"expressions": [
  {"filter": {"field_name": "country", "string_filter": {"value": "US"}}},
  {"filter": {"field_name": "deviceCategory", "string_filter": {"value": "mobile"}}}
]}}

原始 {"field_name": ..., "string_filter": ...} 会自动包装为 {"filter": {...}}。

回复格式

每个工具都会返回 JSON，其中包含 status（succeeded、partial、no_op）、operation、summary、target、result、proof、warnings、recovery。失败时会返回工具错误，错误文本为 ga4_request_failed: <message> <hint>。当状态为 partial 时，proof.nextOffset 表示应从该偏移量继续。proof.propertyQuota 包含该属性剩余的 Data API 配额，调用方可据此自行控制请求频率。当响应经过抽样、阈值处理，或将高基数行合并到 (other) 时，proof.dataQualityLimited 为 true；此类结果适合用于判断趋势，而非精确分析。

限制

每次 Data API 响应最多返回 250,000 行（服务器会限制客户端提供的更高上限）。批量报告：每次调用最多 5 个。漏斗报告：最多 10 个步骤。实时报告使用单独且规模较小的维度和指标目录，仅覆盖最近 30 分钟；非实时数据通常会延迟 24 到 48 小时。漏斗报告目前处于 v1alpha 阶段，其结构可能会在上游发生变化。每个配额桶（核心报告、实时报告、漏斗报告）每个项目、每个属性每小时约允许使用 14,000 个配额令牌（复杂查询可能消耗多个令牌）；360 属性可获得 10 倍额度。在依据具体数字作出判断前，请重新查看 Google 当前的配额页面。

验证

每个版本都会在 CHANGELOG.md 中列出软件包版本、.mcpb 的 sha256，以及该版本所基于的生产提交。每次推送时，CI 都会运行测试，并对构建出的 wheel 执行全新安装。

隐私政策

此服务在你的机器上本地运行，并使用你自己的凭据。它不收集个人数据、不包含遥测、不持久存储任何内容，并且只与其封装的供应商 API 通信。包括 Scalably 在内的任何第三方都不会收到你的数据。联系邮箱：[email protected]。规范版本：https://scalably.io/connector-privacy.html

许可证

MIT。版权归 Scalably 所有。