Google Analytics 4

影片展示的是使用示例数据的托管版 getmcpads。从创意素材库和提醒，到 Google Sheets 导出和批量发布，其 MCP Apps 均属于托管产品。本仓库提供独立的原生 API 工具。

27 个只读工具 · 专为只读而设计。

使用你自己的平台凭据，在本地运行，并搭配支持 stdio MCP 的客户端，例如 Claude Desktop、Claude Code 或 Cursor。请求会直接发送到平台。如需托管连接（包括受支持的 ChatGPT 配置），请使用托管选项。

更新内容

v2.1.1：Zod 4 安全更新 · 2026 年 10 月 26 日

• 将 zod 更新至 4.6.7。4.6.6 之前的所有 Zod 版本均受高危安全公告 GHSA-mrhx-c7xc-m3w5 影响：验证超出大小限制的集合可能耗尽内存，而且没有任何 Zod 3 版本包含此修复。npm audit --omit=dev 再次显示无漏洞。
• 保留 Zod 3 的验证行为。参数默认值仍会在使用前经过验证和补全，因此省略对象时仍须提供其必填字段。
• 参数为可选项或设有默认值时，保留该参数自身的描述。Zod 4 只会在包装后的 schema 上存储描述，否则共享的备用描述可能会取代它。
• 通过 MCP 发布的工具名称、参数和描述保持不变。server-card.json 已使用 Zod 4 的 JSON Schema 输出重新生成，其中部分约束的表述有所不同。

更早的版本

版本	日期	主要更新
2.1.0	2026 年 10 月 23 日	媒体资源允许列表和撤销令牌处理
2.0.1	2026 年 9 月 23 日	恢复公开仓库
2.0.0	2026 年 9 月 20 日	网关同步和安全修复
1.1.0	2026 年 9 月 13 日	平台能力同步和质量契约
1.0.2	2026 年 8 月 30 日	通过 MCP 声明软件包版本。
1.0.1	2026 年 8 月 30 日	为官方 MCP Registry 添加 server.json 和 mcpName，名称为 com.getmcpads/google-analytics。
1.0.0	2026 年 8 月 29 日	首次开源发布

完整更新日志 · 所有版本

源同步：SOURCE_SYNC.md。

升级说明

需要 Node.js 22.23.4、24.22.1 或 26.12.1，或这些版本系列中更新的版本。较早版本缺少 2026 年 10 月的安全修复，服务器在这些版本上启动时会向 stderr 打印警告。CI 覆盖 Node 22、24 和 26。

此版本不会对配置造成破坏性变更。现宣布一项针对 3.0.0 的变更：GA4_PROPERTY_IDS 在 2.x 中为可选项，届时将变为必填项。设置后，每个工具都只能访问所列属性，且 GA4_PROPERTY_ID 必须是其中之一。未设置时，服务器会像以前一样启动，并向 stderr 打印一行提示，建议设置该项。工具及其架构均未更改。

安装此版本

这是 GitHub 源代码版本。npm 和 MCP Registry 中的版本会单独发布。以下命令会选择此确切版本；本文后面的未固定版本 npx 示例会选择 npm 上当前可用的版本。

git clone --branch v2.1.1 --depth 1 https://github.com/get-mcp-ads/google-analytics-mcp-server.git
cd google-analytics-mcp-server
npm ci
npm run build

配置 MCP 客户端，以绝对路径运行 dist/cli.js，并使用下文说明的平台凭据运行 node。

更倾向于使用托管连接？ 通过托管服务 getmcpads 使用 Google Analytics 4。连接账号，选择助手可访问的数据，然后使用托管 MCP 连接。当前功能和方案请参阅网站。

你将获得

27 个只读工具	报告、透视表、漏斗、实时数据，以及 Admin API：属性、数据流、自定义定义、关键事件、受众群体
诊断	电子商务、BigQuery 导出、服务器端标记、受众群体导出、配额快照
51 个指标、62 个维度	附带兼容性矩阵，可在无效组合调用 API 前将其识别出来
6 项资源	模型可读取的实时目录：指标、维度、兼容性规则、12 个工作流配方
标识符脱敏	默认对访问绑定和受众群体导出中的用户、电子邮件和设备标识符进行脱敏；明确选择后方可查看
完全没有写入功能	这不是一个标志位，而是代码本身的特性。详见下文

调用前检查兼容性

GA4 会拒绝许多指标和维度组合，而且错误信息很少说明具体是哪一对组合有问题。此服务器包含兼容性矩阵，因此模型可以通过 ga4_check_compatibility 和 ga4_validate_query 在发起调用并消耗配额令牌前验证组合。

配额在这里比在广告平台上更重要：GA4 按属性和天数收取令牌，几次不谨慎的探索性查询就可能耗尽配额。ga4_get_property_quotas_snapshot 会显示剩余配额。

---

只读，以及坚持只读的原因

这里没有写入工具，也没有任何可添加写入工具的环境变量。每个工具调用的都是 Data API 或 Admin API 的读取方法。

这不是无谓的谨慎。误读报告会导致错误答案，你还能发现问题。而误写分析属性、删除受众群体或编辑数据流，会破坏你用来判断其他一切的数据记录，而且往往不会留下明显提示。我们发布的其他服务确实提供写入工具，但都必须先经过预览。这个服务没有任何写入工具。

我们提供的、支持受保护写入操作的广告平台服务： Meta Ads · Google Ads · TikTok Ads

---

个人数据

分析数据默认并非匿名。GA4 媒体资源可能包含你自行设置的 userId、设备标识符或 Google Signals 假名 ID。MCP 对话会将工具返回的任何内容发送给模型。

只要此服务可能返回标识符，就会默认对其进行脱敏；显示这些标识符必须显式选择启用，绝非默认行为。

工具	行为
ga4_list_admin_resources	访问绑定中的用户和电子邮件标识符会被脱敏
ga4_query_audience_export	标识符列会被脱敏，并根据导出内容自身的维度元数据进行匹配
ga4_get_audience_export_diagnostics	行样本同样会被脱敏

这些工具均接受 includePersonalIdentifiers: true 以返回原始值，默认值为 false。

受众导出行采用位置索引，因此脱敏时会读取导出的维度元数据，以确定标识符列。如果缺少这些元数据，行中的每个值都会被脱敏，而不会猜测哪些列是安全的。关键在于默认拒绝。

报告行不会脱敏。 ga4_run_report 和其他报告工具会返回你请求的内容。篡改报告返回的数字，比直接返回这些数字更糟。

因此，有一项决定仍由你做出：如果你的媒体资源包含你认为属于个人信息的 userId，请勿在对话记录会离开你设备的情况下，将其请求为报告维度。

---

获取凭据

只需获取一次的三个值。

1. OAuth 客户端

在 Google Cloud 项目中启用 Google Analytics Data API 和 Google Analytics Admin API，然后在 APIs & Services → Credentials 下创建 OAuth 客户端。本地使用请选择 Desktop app。记下 client ID 和 client secret。

2. Refresh token

运行一次 OAuth 授权流程，并使用有权访问你的 GA4 媒体资源的 Google 账号登录，然后保留 refresh token。analytics.readonly 范围已足够，而且你应该只授予此范围。

📖 适用于已安装应用的 Google OAuth

Refresh token 不会过期。 它是敏感值：任何持有它的人都能无限期地获取 access token。请为此服务专门使用一个 OAuth 客户端，这样你就能单独撤销它。

3. Property ID，可选

设置 GA4_PROPERTY_ID，即可不必在每次调用时都传入该值。在 GA4 的 Admin → Property Settings 下查找，或使用 ga4_list_properties 列出。

首次调用请运行 ga4_health_check。它会验证凭据并列出你实际能够访问的媒体资源，且不会打印任何机密信息。

---

设置

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） 或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "@getmcpads/google-analytics-mcp-server"],
      "env": {
        "GA4_CLIENT_ID": "your-client-id",
        "GA4_CLIENT_SECRET": "your-client-secret",
        "GA4_REFRESH_TOKEN": "your-refresh-token",
        "GA4_PROPERTY_IDS": "123456789"
      }
    }
  }
}

重启 Claude Desktop。向它提问：“列出我的 Google Analytics 媒体资源”。

Claude Code

claude mcp add google-analytics --env GA4_CLIENT_ID=... --env GA4_CLIENT_SECRET=... --env GA4_REFRESH_TOKEN=... -- npx -y @getmcpads/google-analytics-mcp-server

Cursor

在项目中的 .cursor/mcp.json 文件中配置，结构与上方的 Claude Desktop 配置相同。

从源代码运行

git clone https://github.com/get-mcp-ads/google-analytics-mcp-server.git
cd google-analytics-mcp-server
npm install && npm run build
cp .env.example .env   # then fill in your credentials
npm start

配置

变量	默认值	含义
GA4_CLIENT_ID	none	必需。 OAuth 客户端 ID
GA4_CLIENT_SECRET	none	必需。 OAuth 客户端密钥
GA4_REFRESH_TOKEN	none	必需。 来自授权流程
GA4_PROPERTY_ID	none	可选默认值，省去每次调用时传入该值
GA4_PROPERTY_IDS	unset	建议设置。以逗号分隔的媒体资源 ID，所有工具都只能访问这些媒体资源。未设置时，凭据可访问的所有媒体资源均可用。3.0.0 版本中为必需项
LOG_LEVEL	info	debug、info、warn、error

你可以随时检查设置：

npm run doctor

---

工具

下方列出了所有工具。完整的参数和输出架构请参阅 server-card.json。

27 个只读工具

| 工具 | 用途 | | --- | --- | | `ga4_health_check` | 只读 GA4 健康检查。 | | `ga4_list_properties` | 列出使用当前凭据可访问的所有 GA4 媒体资源。 | | `ga4_run_report` | 通过智能查询规划运行 GA4 分析报告。 | | `ga4_run_realtime_report` | 运行只读 GA4 Data API 实时报告。 | | `ga4_get_metadata` | 获取特定 GA4 媒体资源中可用维度和指标的完整列表。 | | `ga4_get_custom_definitions` | 列出 GA4 Data API 元数据中公开的自定义维度和自定义指标。 | | `ga4_get_key_events` | 使用可识别元数据的 Data API 报告盘点 GA4 关键事件／转化。 | | `ga4_get_ecommerce_diagnostics` | 在指定日期范围内，对核心电商事件、收入指标和商品级报告进行只读电商覆盖诊断。 | | `ga4_get_event_parameters` | 根据 GA4 元数据和事件报告，尽力盘点事件参数。 | | `ga4_run_funnel_recipe` | 运行只读、可配置的漏斗配方：针对每个 `eventName`／`pagePath` 步骤运行一份 GA4 报告，并返回简单的步骤计数。 | | `ga4_get_audience_export_diagnostics` | 只读受众导出诊断。 | | `ga4_get_audience_diagnostics` | 通过 Admin API 受众、Data API 定期受众列表，以及观测到的 `audienceName` 报告回退方式，进行只读受众诊断。 | | `ga4_get_bigquery_export_diagnostics` | 检测 GA4 BigQuery 导出关联，并诊断导出模式、数据流覆盖范围、排除的事件和数据集位置。 | | `ga4_get_server_side_tagging_diagnostics` | 根据数据流、Measurement Protocol 密钥、事件规则和数据流设置，尽力进行只读服务端标记诊断。 | | `ga4_run_advanced_funnel_report` | 运行 GA4 Data API v1alpha `runFunnelReport` 端点，可选拆分／后续操作；若不可用，则回退为只读步骤计数。 | | `ga4_get_channel_groups` | 列出为 GA4 媒体资源定义的自定义渠道组。 | | `ga4_validate_query` | 在执行前验证指标／维度组合。 | | `ga4_run_pivot_report` | 运行只读 GA4 Data API 数据透视报告，支持原生筛选器、排序、配额状态、多个日期范围，以及最多 250,000 个数据透视单元格。 | | `ga4_batch_run_reports` | 在一次官方 Data API 批量请求中，为同一媒体资源运行 1-5 份相互独立的只读 GA4 核心报告。 | | `ga4_batch_run_pivot_reports` | 在一次官方 Data API 批量请求中，为同一媒体资源运行 1-5 份相互独立的只读 GA4 数据透视报告。 | | `ga4_check_compatibility` | 通过官方 GA4 Data API 查询建议的核心报告选项中哪些维度和指标兼容。 | | `ga4_get_property_quotas_snapshot` | 从官方 v1alpha 端点读取当前 GA4 Data API 媒体资源配额快照。 | | `ga4_list_accounts` | 列出经身份验证的用户可访问的原始 GA4 Analytics Admin 账号（只读，自动分页）。 | | `ga4_list_admin_resources` | 以只读模式列出允许访问的 GA4 Admin 集合：数据流、自定义定义、关键事件、受众、产品关联、注释、渠道组、扩展数据集、子媒体资源／汇总配置和访问权限绑定。 | | `ga4_get_property_configuration` | 读取 GA4 媒体资源详情及选定的单例 Admin 设置（归因、保留期限、Google Signals、报告身份或用户提供的数据设置）。 | | `ga4_list_audience_exports` | 列出现有 GA4 受众导出快照和定期受众列表，不创建新导出。 | | `ga4_query_audience_export` | 查询现有 GA4 受众导出中的行。 |

6 个资源

| URI | 内容 | |---|---| | `ga4://manifest` | 此服务提供的内容，以及首先应运行的工具 | | `ga4://metrics` | 全部 51 个指标及其类别和格式 | | `ga4://dimensions` | 全部 62 个维度及其适用范围 | | `ga4://compatibility` | 兼容性矩阵 | | `ga4://recipes` | 12 个分步工作流 | | `ga4://p2-diagnostics` | 诊断手册 |

---

安全

• 客户端密钥和刷新令牌绝不会被记录，无论日志级别如何，也不会写入磁盘。
• 已撤销的刷新令牌只会报告一次。 当 Google 返回 invalid_grant 时，之后的每次调用都会返回相同的消息和重新授权步骤；在服务重启前，不会再向 Google 请求令牌。
• 可以限制可用属性。 设置 GA4_PROPERTY_IDS 后，若调用指定了其他属性，系统会在发出任何请求前拒绝该调用，且发现结果只会列出允许的属性。
• 只会联系三个主机，且仅限这三个：analyticsdata.googleapis.com、analyticsadmin.googleapis.com 和 oauth2.googleapis.com。如果源码中出现第四个主机，测试会导致构建失败。
• 不会跟随重定向发起请求。 每个出站调用都会设置 redirect: "error"，因此重定向无法将持有者令牌或客户端密钥转发到其他主机。如果任何 fetch 未设置此选项，测试会导致构建失败。
• 不进行遥测。 除 Google 之外，服务不会发起任何网络调用。

完整政策（包括个人数据的处理方式）：SECURITY.md。

---

想要托管的多平台版本？

如果你想使用此源而无需运行本地服务，试用托管版 GA4。 getmcpads 还可通过一个 MCP URL 连接广告、Search Console 和 GA4。 网站列出了源的可用情况和套餐限制；仍需连接账号。

1. 按照 GA4 连接指南操作。
2. 选择助手可读取的账号或属性。
3. 连接 Claude、ChatGPT 或 Codex。
4. 尝试进行只读检查：“比较获客渠道、着陆页和已配置的关键事件。指出缺失的数据，不要进行任何更改。”

在选择付费套餐前，请查看当前托管工具目录和定价。 此 Apache 2.0 适配器使用你自己的凭据时仍可独立发挥作用。

---

贡献

欢迎提交问题和拉取请求。请参阅 CONTRIBUTING.md。 报告任何安全相关问题前，请阅读 SECURITY.md。

许可证

Apache License 2.0。另请参阅 NOTICE。

Google、Google Analytics 和 GA4 是 Google LLC 的商标。 本项目与 Google LLC 无关，也未获其认可或赞助。 这是一个独立的公共 API 客户端。

MCP 合约和桌面端套件

每个工具都声明读写注解、参数说明和结构化输出架构。成功调用会将有效负载作为 structuredContent.result 暴露；错误会保留 isError: true。生成的服务卡仅包含定义。

运行 npm run bundle -- /path/to/output，即可根据当前目录构建 .mcpb 桌面套件。安装时在本地输入凭据。此服务仍为只读。

More from getmcpads

Meta Ads · Google Ads · Google Search Console · TikTok Ads · Pinterest Ads · X Ads

Maintained by Emmanuel at getmcpads. Questions: [email protected].