AI导哈

GA4数据分析服务器

GA4 MCP服务器提供通过Admin API和Data API查询GA4数据的工具，支持双重认证和GTM集成，适用于数据分析和跨平台协调。

  • by wonyoungseong
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 wonyoungseong/ga4-mcp-server

使用说明

GA4 MCP服务器

用于Google Analytics 4（GA4）的模型上下文协议（MCP）服务器，提供通过管理API和数据API查询GA4数据的工具。

特性

  • 双重认证：支持OAuth Playground令牌和服务帐户凭据
  • 8 GA4工具:
    • 账户和财产管理（管理API）
    • 报表执行和实时数据（data API）
    • GTM → GA4参数验证 （跨平台编排）
  • 与Claude Desktop兼容 以及其他启用MCP的客户端
  • GTM集成：与GTM MCP服务器配合使用，进行端到端事件验证

安装

npm install
npm run build

快速入门（OAuth设置）

1.创建OAuth凭据

  1. 首选 谷歌云控制台
  2. 创建新项目或选择现有项目
  3. 启用 谷歌分析数据API 和 Google Analytics管理员API
  4. 首选 凭证 → 创建凭据 → OAuth客户端ID
  5. 选择 桌面应用程序 作为应用程序类型
  6. 下载或复制客户端ID和客户端密码

2.运行安装脚本

# Set your OAuth credentials
export GA4_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GA4_CLIENT_SECRET="your-client-secret"

# Run setup to authenticate with Google
npm run setup

这将：

  • 打开浏览器进行谷歌登录
  • 请求以只读方式访问Google Analytics
  • 将令牌保存到 ~/.ga4-mcp/tokens.json

3.使用服务器

一旦通过身份验证，您就可以将MCP服务器与Claude Desktop或其他客户端一起使用。

认证

服务器支持两种身份验证方法，按以下顺序检查：

1.OAuth游乐场令牌（建议个人使用）

设置这些环境变量：

  • GA4_ACCESS_TOKEN -OAuth访问令牌
  • GA4_REFRESH_TOKEN -OAuth刷新令牌
  • GA4_CLIENT_ID -OAuth客户端ID
  • GA4_CLIENT_SECRET -OAuth客户端密钥

或创建 ~/.ga4-mcp/tokens.json:

{
  "access_token": "your-access-token",
  "refresh_token": "your-refresh-token",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

2.服务帐户（建议用于生产）

选项（按优先级顺序）：

  1. 集 GA4_SERVICE_ACCOUNT_JSON 带有JSON字符串的环境变量
  2. 集 GOOGLE_APPLICATION_CREDENTIALS 到JSON文件路径
  3. 将JSON文件放置在 ~/.ga4-mcp/credentials.json
  4. 将JSON文件放入 ./Credential/ 文件夹

用法

Claude桌面配置

添加到您的Claude Desktop配置(~/.config/claude-desktop/config.json):

{
  "mcpServers": {
    "ga4": {
      "command": "node",
      "args": ["/path/to/ga4-mcp-server/dist/index.js"],
      "env": {
        "GA4_ACCESS_TOKEN": "your-access-token",
        "GA4_REFRESH_TOKEN": "your-refresh-token",
        "GA4_CLIENT_ID": "your-client-id",
        "GA4_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

直接执行

# With OAuth environment variables
GA4_ACCESS_TOKEN="..." GA4_REFRESH_TOKEN="..." GA4_CLIENT_ID="..." GA4_CLIENT_SECRET="..." node dist/index.js

# With Service Account
GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json" node dist/index.js

可用工具

管理API工具

工具 说明
ga4_account_summaries 列出用户有权访问的所有GA4帐户和属性
ga4_property_details 获取特定房产的详细信息
ga4_google_ads_links 列出链接到某个属性的Google Ads帐户
ga4_property_annotations 列出属性的注释（支持有限）

API数据工具

工具 说明
ga4_run_report 运行一个包含维度、指标和日期范围的标准GA4报告
ga4_run_realtime_report 运行最后30分钟的实时报告
ga4_custom_dimensions_metrics 获取为属性定义的自定义维度和指标

GTM验证工具

工具 说明
ga4_validate_gtm_params 根据GA4自定义维度和数据收集验证GTM事件参数

示例用法

获取帐户摘要

{
  "tool": "ga4_account_summaries"
}

运行报告

{
  "tool": "ga4_run_report",
  "arguments": {
    "propertyId": "123456789",
    "dateRanges": [
      {"startDate": "30daysAgo", "endDate": "yesterday"}
    ],
    "dimensions": ["country", "deviceCategory"],
    "metrics": ["activeUsers", "sessions"]
  }
}

运行实时报告

{
  "tool": "ga4_run_realtime_report",
  "arguments": {
    "propertyId": "123456789",
    "dimensions": ["country"],
    "metrics": ["activeUsers"]
  }
}

验证GTM参数

{
  "tool": "ga4_validate_gtm_params",
  "arguments": {
    "propertyId": "123456789",
    "gtmEvents": [
      {
        "eventName": "purchase",
        "parameters": ["transaction_id", "value", "currency"]
      }
    ],
    "startDate": "7daysAgo",
    "endDate": "yesterday"
  }
}

或者使用GTM导出JSON：

{
  "tool": "ga4_validate_gtm_params",
  "arguments": {
    "propertyId": "123456789",
    "gtmExportJson": { "...GTM container export data..." }
  }
}

GTM集成（克劳德代理编排）

该服务器与GTM MCP服务器协同工作，提供GA4中GTM事件参数的端到端验证。

建筑

┌─────────────────────────────────────────────────────────────────────┐
│                        Claude Agent                                 │
│                    (Orchestrator Role)                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ① GTM MCP Server                  ② GA4 MCP Server                │
│  (gtmAgent/mcp-server)             (ga4-mcp-server)                 │
│                                                                     │
│  gtm_export_full()                 ga4_validate_gtm_params()        │
│  gtm_tag().list()                  ga4_custom_dimensions_metrics()  │
│       │                            ga4_run_report()                 │
│       │                                   ▲                         │
│       └───────────────────────────────────┘                         │
│                Agent relays data                                    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

工作流程

  1. GTM提取物: gtm_export_full() → 获取GA4事件标签和参数
  2. 在GA4中验证: ga4_validate_gtm_params() → 检查登记和领取情况
  3. 获取推荐：参数未注册或未收集数据

Claude桌面配置（两台服务器）

{
  "mcpServers": {
    "gtm": {
      "command": "node",
      "args": ["/path/to/gtmAgent/mcp-server/dist/index.js"],
      "env": {}
    },
    "ga4": {
      "command": "node",
      "args": ["/path/to/ga4-mcp-server/dist/index.js"],
      "env": {
        "GA4_ACCESS_TOKEN": "your-access-token",
        "GA4_REFRESH_TOKEN": "your-refresh-token",
        "GA4_CLIENT_ID": "your-client-id",
        "GA4_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

API调用效率

场景 传统 优化 减少
5个事件×21个参数 105个呼叫 22个呼叫 79%
14个事件×32个参数 448个呼叫 33个呼叫 93%

验证工具查询元数据一次，然后为每个唯一参数而不是每个事件-参数组合调用一个API。

API文件参考

要求的Google API范围

服务器使用以下作用域：

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

许可证

麻省理工学院

相关 MCP