Google Analytics MCP Server

什么是 Google Analytics MCP Server？

Google Analytics MCP Server（google-analytics-mcp）是一个社区开发的 google analytics mcp 服务器，把 Google Analytics 4 数据接入 Claude、Cursor、VS Code 等 MCP 客户端。你可以用自然语言询问流量、渠道和转化，它会调用 GA4 Data API 运行只读报告。

该项目由 surendranb 维护，采用 MIT 许可，在 PyPI 上发布为 google-analytics-mcp，在 npm 上发布为 @surendranb/google-analytics-mcp。它在 GA4 Data API 之上增加了实时 schema 发现、服务端聚合和内置分析“skills”。它不是 Google 自己的服务器。Google 另外发布了一个实验性的官方 Google Analytics MCP 服务器。

如何使用 Google Analytics MCP Server？

前提条件： Python 3.10+（如果使用 npm 包装器则需要 Node.js）、一个有数据的 GA4 媒体资源，以及 Google Cloud 凭据。

1. 创建凭据。 在 Google Cloud Console 中选择一个项目，启用 Google Analytics Data API，创建服务账号并下载 JSON 密钥。也可以通过 gcloud auth application-default login 使用应用默认凭据（ADC）。
2. 在 GA4 中授权。 复制 JSON 密钥中的 client_email。在 Google Analytics 中进入 Admin → Property Access Management → Add users，粘贴该邮箱，选择 Viewer 角色。
3. 记下媒体资源 ID。 使用 Admin → Property details 中的数字 GA4_PROPERTY_ID，不是以 G- 开头的衡量 ID。
4. 设置两个环境变量： GA4_PROPERTY_ID，以及指向 JSON 密钥绝对路径的 GOOGLE_APPLICATION_CREDENTIALS。

README 列出了几种运行这个 ga4 mcp server 的方式：

# Universal installer (configures Claude Desktop, Cursor, Claude Code, Antigravity, VS Code, Zed, Windsurf)
curl -fsSL "https://ga4.builditwithai.xyz/install" | bash

# Or run directly
uvx google-analytics-mcp
npx -y @surendranb/google-analytics-mcp

Claude Code

claude mcp add google-analytics -- uvx google-analytics-mcp

请确保服务器进程能读到 GA4_PROPERTY_ID 和 GOOGLE_APPLICATION_CREDENTIALS。

Claude Desktop

在 claude_desktop_config.json 中添加以下内容，然后重启 Claude Desktop：

{
  "mcpServers": {
    "google-analytics": {
      "command": "uvx",
      "args": ["google-analytics-mcp"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/key.json"
      }
    }
  }
}

Cursor

在 ~/.cursor/mcp.json 或项目内的 .cursor/mcp.json 中使用相同的配置项。重新加载 Cursor，确认 google-analytics 显示为已连接。

VS Code

在 .vscode/mcp.json 中，VS Code 使用 servers 块：

{
  "servers": {
    "google-analytics": {
      "type": "stdio",
      "command": "uvx",
      "args": ["google-analytics-mcp"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/key.json"
      }
    }
  }
}

项目文档还提供了 Codex、Gemini、Copilot、Antigravity、Kiro、OpenCode 等客户端的指南。验证配置时，可以问“List my GA4 properties.”。

Google Analytics MCP Server 的主要功能

• 通过 Google Analytics Data API 生成多维度 GA4 报告，总计由 GA4 计算，并在服务端聚合
• 实时发现标准和自定义维度与指标，模型在查询前先核对字段名
• 实时报告：查询最近 30 分钟的活跃用户和事件
• 内置分析剧本（skills），如 traffic-diagnosis、channel-acquisition、ecommerce-analysis、ai-referral-analysis
• 只读访问，绝不修改你的 GA4 配置
• 通过 uvx、pip 或 npm 包装器在本地以 stdio 运行
• 匿名遥测，可用 DO_NOT_TRACK=1 或 MCP_TELEMETRY_OPT_OUT=1 关闭

Google Analytics MCP Server 工具

• 报告： get_ga4_data 按维度、指标、日期范围和行数上限运行报告。run_realtime_report 查询最近 30 分钟的数据。
• 发现： list_accounts、list_properties 和 get_property_metadata 显示凭据能访问哪些账号和媒体资源，以及某个媒体资源的完整字段 schema。客户端指南还介绍了用于查找正确字段名的 search_schema。
• Skills： skills_list、search_skills 和 skill_read 用于加载引导式分析方案，例如流量下滑时按顺序排查的清单。

Google Analytics MCP Server 的使用场景

• 诊断流量下滑：“Why did organic traffic drop in the last 7 days?”
• 渠道报告：“What were my top channels last week?”
• 找出热门内容：“Which pages earned the most engaged sessions last week, excluding bots?”
• 追踪 AI 引荐流量：把来自 ChatGPT、Claude、Perplexity 和 Gemini 的流量与搜索流量、直接流量分开。
• 查看实时流量：“How many active users are on the site right now, by country?”
• 组合数据源：搭配作者的 Google Search Console MCP，对比搜索查询与站内行为。

Google Analytics MCP Server 与替代方案对比

• 官方 Google Analytics MCP 服务器（googleanalytics/google-analytics-mcp，Google 文档）：由 Google 开发，标注为实验性，采用 Apache-2.0 许可，只读。它通过应用默认凭据调用 Admin API 和 Data API。如果你更想用 Google 自己的实现，选它。
• 这个社区版 google analytics mcp server： 增加了 schema 校验、聚合辅助、实时报告、分析剧本和多客户端安装器，更新频繁。

Google Analytics MCP Server 常见问题排查

• 提示缺少环境变量的设置错误： 在客户端的 env 块中同时设置 GA4_PROPERTY_ID（数字）和 GOOGLE_APPLICATION_CREDENTIALS（指向现有 JSON 文件的绝对路径），然后重启客户端。
• “The service account does not have Viewer access to the GA4 property”： 密钥本身有效，但服务账号没有加到媒体资源上。在 Property Access Management 中把它的 client_email 添加为 Viewer，并确认操作的媒体资源与 GA4_PROPERTY_ID 一致。
• 503 Reauthentication is needed： gcloud 应用默认凭据已过期，运行 gcloud auth application-default login。
• 400 无效的维度、指标或筛选器： 模型猜了一个 Universal Analytics 时代的名称。用 search_schema 或 get_property_metadata 找到对应的 GA4 名称后重试。
• Cursor 或 VS Code 中服务器无法连接： 在终端运行 uvx google-analytics-mcp，确认运行环境正常，检查命令拼写，然后重新加载窗口。