mcp-ga4

用于 Google Analytics 4 的 MCP 服务器——通过 Claude 运行报告、实时数据、自定义维度和属性管理。

功能

• 9 个工具，涵盖报告、实时数据、自定义维度/指标、数据流和反馈

• 两种配置模式：单属性（环境变量）和多客户端（config.json）

• 支持服务账户和 OAuth 凭据

• 相对日期支持（today、yesterday、7daysAgo、30daysAgo、90daysAgo）

• 基于官方 Google SDK 构建，并带有弹性模式

Related MCP server: Google Analytics 4 MCP Server

安装

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，打开浏览器，将令牌打印到标准输出）：

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

   不要将此命令的标准输出重定向到共享日志——刷新令牌按设计打印在那里。

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

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

请求的范围从 config.json 的 oauth.scope 中读取（见下文），因此助手和运行中的服务器永远不会对您授予的内容产生分歧。

范围（最小授权）

范围位于 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）；config.json 可选地携带 credentials_file 服务账户路径，用于仅配置的 SA 设置。

{
  "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"
    }
  }
}

用法

Claude Code（.mcp.json）

单属性模式：

{
  "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 Desktop： 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。

常见查询模式

热门页面： dimensions=pagePath，metrics=screenPageViews，order_by=screenPageViews

流量来源： dimensions=sessionSource,sessionMedium，metrics=sessions,totalUsers

每日趋势： dimensions=date，metrics=sessions,totalUsers

广告系列效果： dimensions=sessionCampaignName，metrics=sessions,conversions

设备细分： dimensions=deviceCategory，metrics=sessions,totalUsers

工具

日期格式

使用 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 构建