ga4

mcp-ga4

用于 Google Analytics 4 的 MCP 服务——通过 Claude 运行报告、查看实时数据、自定义维度并管理媒体资源。

功能

• 提供 9 个工具，涵盖报告、实时数据、自定义维度和指标、数据流及反馈
• 支持两种配置模式：单媒体资源（环境变量）和多客户端（config.json）
• 支持服务账号和 OAuth 凭据
• 支持相对日期（today、yesterday、7daysAgo、30daysAgo、90daysAgo）
• 基于官方 Google SDK 构建，并采用弹性处理模式

快速开始

1. 获取凭据——服务账号密钥文件，或用户 OAuth 刷新令牌 （请参阅身份验证）。

2. 将服务注册到此机器上的每个 Claude 客户端：

   # service account
   npx -p mcp-ga4 mcp-ga4-setup --property-id 123456789 --credentials /path/to/service-account.json
   
   # or user OAuth: export GA4_CLIENT_ID / GA4_CLIENT_SECRET / GA4_REFRESH_TOKEN first
   npx -p mcp-ga4 mcp-ga4-setup --property-id 123456789
   

   向导会检测 Claude Desktop（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json， Windows 上的 %APPDATA%\Claude\claude_desktop_config.json）以及 Claude Code CLI（PATH 中的 claude），并将 ga4 注册到检测到的每个客户端。 Desktop 配置中的其他服务和设置会保留；如果配置文件无效，文件不会被修改，向导也会停止。可以安全地重复运行。使用 --claude-desktop-only 或 --claude-code-only 可指定单个客户端。

3. 完全退出并重新打开 Claude Desktop（Cmd+Q），或重启你的 claude 会话。

安装

npm install mcp-ga4

或者克隆此仓库：

git clone https://github.com/mharnett/mcp-ga4.git
cd mcp-ga4
npm install
npm run build

身份验证

mcp-ga4 支持两种凭据类型。凭据选择方式确定，并且仅在启动时进行一次：显式指定的密钥文件／服务账号优先，其次是用户 OAuth；如果两者均未配置，服务会退出并显示明确的引导错误，说明这两个选项。代码中没有内置任何机器本地凭据路径，也不会在运行时静默切换凭据——唯一的凭据输入来源是环境变量，以及（可选的）你自己的用户级 config.json。（因此，后续出现的 403 会作为 API 错误显示，而不会导致静默切换到另一种凭据类型。）

优先级：如果两种凭据类型均已配置，则密钥文件／ 服务账号优先于用户 OAuth。

选项 A：服务账号（推荐用于无人值守／服务器场景）

适用于所有持续运行或服务器部署场景。将 GOOGLE_APPLICATION_CREDENTIALS（或 config.json 中的 credentials_file）指向 JSON 密钥文件。服务账号必须获得 GA4 媒体资源的访问权限 （管理员 → 媒体资源访问权限管理 → 添加服务账号邮箱，并至少授予查看者权限）。无需使用刷新令牌——服务会直接将密钥文件传递给 GA4 SDK：

GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

密钥文件可以是真正的服务账号密钥，也可以是 authorized_user OAuth 令牌转储文件——两者都可通过 keyFile 选项使用。

选项 B：用户 OAuth（个人／交互式使用）

如果你希望服务以 Google 用户（你自己的 GA4 登录账号）的身份运行，请使用此选项。你需要使用自己的 Google OAuth 客户端，并生成一次刷新令牌。

1. 在 Google Cloud Console 中， 创建类型为 桌面应用 的 OAuth 2.0 客户端 ID。启用 Google Analytics Data API（如果你使用自定义维度工具，还需启用 Admin API）。

2. 导出客户端凭据并运行令牌辅助程序（使用 PKCE、打开浏览器，并将令牌打印到 stdout）：

   export GA4_CLIENT_ID=...            # from the Desktop-app client
   export GA4_CLIENT_SECRET=...
   node get-refresh-token.cjs          # or: npm run auth
   

   请勿将此命令的 stdout 重定向到共享日志——刷新令牌会按设计打印到其中。

3. 将打印出的 GA4_REFRESH_TOKEN=... 复制到环境中。运行时，服务会读取以下三个环境变量：

   GA4_CLIENT_ID=...
   GA4_CLIENT_SECRET=...
   GA4_REFRESH_TOKEN=...
   

请求的范围从 config.json 中的 oauth.scope 读取（见下文），因此辅助程序和运行中的服务不会对你授予的权限范围产生分歧。

Scopes（最低授权）

Scopes 位于 config.json 的 oauth.scope 下。已提交的默认值为：

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

analytics.edit 是必需的，因为 ga4_create_custom_dimension 会通过 Admin API 修改媒体资源。如果你只需要读取权限，请在自己的 config.json 中将 oauth.scope 覆盖为仅 analytics.readonly，然后重新运行辅助工具。

配置

**安全提示：**切勿分享 .mcp.json 文件或将其提交到 git 中——它可能包含 API 凭据。请将 .mcp.json 添加到 .gitignore。

模式 1：单个媒体资源（环境变量）

设置媒体资源 ID 和上述任一身份验证方式：

GA4_PROPERTY_ID=123456789
# then EITHER the OAuth trio (GA4_CLIENT_ID/SECRET/REFRESH_TOKEN)
# OR a service account: GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

模式 2：多客户端（config.json）

在项目根目录中创建 config.json，将多个 GA4 媒体资源映射到项目目录。服务会根据调用方的工作目录自动检测要使用的媒体资源。凭据从环境变量中获取（上述选项 A/B）；对于仅通过配置文件设置 SA 的情况，也可以选择在 config.json 中填写服务账号路径 credentials_file。

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/analytics.readonly https://www.googleapis.com/auth/analytics.edit"
  },
  "clients": {
    "client-a": {
      "name": "Client A",
      "folder": "/path/to/client-a/project",
      "property_id": "123456789"
    },
    "client-b": {
      "name": "Client B",
      "folder": "/path/to/client-b/project",
      "property_id": "987654321"
    }
  }
}

用法

手动配置

mcp-ga4-setup（参见快速开始）会为你写入此配置。若要手动管理条目，单媒体资源配置格式如下：

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["mcp-ga4"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

多客户端模式：

{
  "mcpServers": {
    "ga4": {
      "command": "node",
      "args": ["/path/to/mcp-ga4/dist/index.js"]
    }
  }
}

Claude Code 项目配置和 Claude Desktop 的 claude_desktop_config.json 使用相同的 mcpServers 格式。

常见查询模式

热门网页： 维度=pagePath，指标=screenPageViews，排序依据=screenPageViews

流量来源： 维度=sessionSource,sessionMedium，指标=sessions,totalUsers

每日趋势： 维度=date，指标=sessions,totalUsers

广告系列效果： 维度=sessionCampaignName，指标=sessions,conversions

设备细分： 维度=deviceCategory，指标=sessions,totalUsers

工具

工具	描述
ga4_get_client_context	返回当前 GA4 媒体资源 ID 和客户端名称
ga4_run_report	根据维度、指标、日期范围和筛选条件运行标准 GA4 报告
ga4_realtime_report	查询实时数据（最近 30 分钟）
ga4_list_custom_dimensions	列出媒体资源的所有自定义维度
ga4_create_custom_dimension	创建新的自定义维度
ga4_list_custom_metrics	列出媒体资源的所有自定义指标
ga4_list_data_streams	列出网页/应用数据流及其衡量 ID
ga4_send_feedback	提交对查询结果的反馈
ga4_suggest_improvement	建议新的查询模式或改进方案

日期格式

绝对日期请使用 YYYY-MM-DD，也可以使用以下相对日期快捷格式：

• today
• yesterday
• 7daysAgo
• 30daysAgo
• 90daysAgo

常见维度和指标

**维度：**date、dateHour、eventName、pagePath、pageTitle、sessionSource、sessionMedium、sessionCampaignName、country、city、deviceCategory、browser、operatingSystem、landingPage、pageReferrer、newVsReturning、firstUserSource、firstUserMedium、firstUserCampaignName

**指标：**sessions、totalUsers、newUsers、activeUsers、screenPageViews、eventCount、conversions、engagedSessions、engagementRate、averageSessionDuration、bounceRate、sessionsPerUser、screenPageViewsPerSession、userEngagementDuration

数据新鲜度

• 标准报告：延迟 24-48 小时
• 实时报告：仅提供最近 30 分钟的数据

架构

基于以下组件构建：

• @google-analytics/data -- 用于报告的 GA4 Data API
• @google-analytics/admin -- 用于媒体资源管理的 GA4 Admin API
• cockatiel -- 弹性机制（重试、断路器）
• pino -- 结构化日志

许可证

MIT

作者

由 Mark Harnett / drak-marketing 构建