mcp-server-google-analytics

你是否经常需要回答这些问题：“上个月网站流量增长了多少？”“哪个落地页的跳出率最高？”“新功能发布后，用户参与度有提升吗？”通常，你需要登录 Google Analytics，配置日期范围，选择指标，生成报告，然后将数字复制到邮件或文档里。这个过程不仅繁琐，而且在快节奏的会议中很难实时响应。

如果能让 AI 助手直接连接你的 Google Analytics 数据，并即时回答这些问题，效率将会大大提升。mcp-server-google-analytics 正是为此而生的工具。它是一个基于模型上下文协议 MCP 的服务器，专门为 Google Analytics 4 设计，让 AI 模型能够直接查询和分析你的网站分析数据。

项目基本信息

一、项目介绍

mcp-server-google-analytics 是一个 MCP 服务器，它封装了 Google Analytics 4 的 Data API，并提供了五个核心工具，让 AI 能够以自然语言的方式查询网站的核心指标。

该服务器支持查询：

• 页面浏览量：按页面路径、国家等维度细分。
• 活跃用户：日活跃用户、周活跃用户、月活跃用户等。
• 事件数据：特定事件（如“purchase”）的发生次数和用户数。
• 用户行为：会话时长、跳出率、每次会话的浏览量等。
• 自定义报告：通过 runReport 工具，你可以指定任意维度和指标的组合。

它使用服务账号进行认证，确保了数据访问的安全性。该服务器可以轻松集成到 Claude Desktop、Cursor 等客户端中。

二、核心优势

聚焦核心指标，开箱即用
服务器提供了 getPageViews、getActiveUsers、getEvents、getUserBehavior 等预定义工具，覆盖了大多数日常分析需求。你无需编写复杂的 API 调用即可获得答案。

支持自定义报告的灵活性
当内置工具不够用时，runReport 工具允许你指定任意维度和指标，返回完全定制化的数据。这几乎可以让你访问 Google Analytics Data API 的所有能力。

基于服务账号的安全认证
服务器使用 Google Cloud 服务账号进行认证，你只需要授予其“查看者”权限，符合最小权限原则。服务账号的凭证通过环境变量传递，避免了在代码中硬编码敏感信息。

多种安装方式
项目支持通过 Smithery 一键安装、全局 npm 包安装，以及直接使用 npx 运行。你可以选择最适合你环境的方式。

良好的社区基础
该项目有 72 颗星和多位贡献者，且有自动化测试和发布流程。整体上比较成熟和可靠。

三、适用场景

产品经理的日常数据查询
在晨会中，你可以直接问：“我们昨天的新用户数是多少？”或者“过去一周，Android 应用的日活跃用户对比 iOS 有什么差异？”

营销活动的效果分析
运营人员可以问：“上周的电子邮件营销活动带来的落地页浏览量是多少？”或者“这些访客中，有多少人最终完成了注册？”

开发者的问题排查
在发布新功能后，开发者可以问：“新功能 'new_checkout' 事件在过去一小时被触发了多少次？”或者“来自某个特定国家的用户，其会话时长是否有明显变化？”

数据驱动的决策
在讨论目标时，你可以让 AI 生成一份简报：“请总结过去 30 天最重要的三个趋势，并用具体数字说明。”

四、安装教程

安装 mcp-server-google-analytics 需要先完成 Google Cloud 和 Google Analytics 的配置。请按顺序操作。

第一步：准备工作（Google Cloud 和 GA4）

1. 在 Google Cloud Console 中，启用 Google Analytics Data API。
2. 创建一个服务账号，并下载其 JSON 密钥文件。记下文件中的 client_email 和 private_key。
3. 登录 Google Analytics，进入你的 GA4 属性的 Property Access Management 页面。
4. 添加该服务账号的邮箱，并授予 Viewer 角色。

第二步：安装 MCP 服务器

推荐使用 Smithery 安装到 Claude Desktop：

关闭 Claude Desktop，运行：

npx -y @smithery/cli install mcp-server-google-analytics --client claude

或者，你也可以使用全局 npm 包：

npm install -g mcp-server-google-analytics

第三步：配置环境变量

在配置 MCP 客户端时，需要设置以下三个环境变量：

• GOOGLE_CLIENT_EMAIL：服务账号的邮箱。
• GOOGLE_PRIVATE_KEY：服务账号的私钥（保留原始格式，包括换行符）。
• GA_PROPERTY_ID：你的 GA4 媒体资源 ID。

对于 Claude Desktop，编辑配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json；Windows: %AppData%\Claude\claude_desktop_config.json），添加如下内容：

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "mcp-server-google-analytics"],
      "env": {
        "GOOGLE_CLIENT_EMAIL": "your-service-account@your-project.iam.gserviceaccount.com",
        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY_HERE\n-----END PRIVATE KEY-----\n",
        "GA_PROPERTY_ID": "你的GA4媒体资源ID"
      }
    }
  }
}

请注意：私钥中的 \n 需要保留。如果复制时丢失了，请手动添加。

第四步：重启客户端

保存配置文件，完全退出并重启 Claude Desktop。

五、使用示例

以下是在配置好服务器后，与 Claude 的自然语言对话示例。

示例1：查询活跃用户

用户输入：过去七天，我们网站的日活跃用户分别是多少？

Claude 会调用 getActiveUsers 工具，按照日期维度返回每日的新用户数或总活跃用户数。

示例2：分析特定页面的浏览量

用户输入：上个月，落地页 /landing-page 被浏览了多少次？主要的流量来源国家是哪些？

Claude 会调用 getPageViews 工具，指定 dimensions: ["page", "country"] 和日期范围，然后返回按国家分组的浏览量。

示例3：跟踪事件

用户输入：从 3 月 1 日到现在，'purchase' 事件总共发生了多少次？

Claude 会调用 getEvents 工具，参数为 eventName: "purchase"，返回事件的总次数和用户数。

示例4：用户行为分析

用户输入：最近一个月，我们网站的平均会话时长和跳出率是多少？

Claude 会调用 getUserBehavior 工具，返回会话时长、跳出率等指标。

示例5：自定义报告

用户输入：我想看看过去 30 天，各浏览器（Chrome、Safari、Firefox）带来的活跃用户数和转化率。

Claude 会使用 runReport 工具，维度为 "browser"，指标为 "activeUsers" 和 "conversions"。

六、常见问题

问题1：启动服务器时提示“Google Analytics Data API 未启用”或认证错误。

解决方案：请确保在 Google Cloud Console 中正确启用了 “Google Analytics Data API”。同时，检查服务账号的私钥是否完整，特别是换行符 \n。如果私钥在 JSON 文件中是带有 \n 字面量的字符串，请保持原样。

问题2：查询返回“没有数据”或空结果，但我确信网站有流量。

解决方案：

1. 确认你的 GA4 媒体资源 ID 正确无误。
2. 确认服务账号在 Google Analytics 中被授予了 Viewer 角色。
3. 检查日期范围是否正确。例如，今天是 2026 年 4 月 26 日，如果查询“明天”的数据，自然为空。
4. 注意时区。Google Analytics 数据以媒体资源的时区为准。

问题3：getEvents 工具查询特定事件时，返回事件列表包含不相关的内部事件。

解决方案：Google Analytics 会自动收集一些增强型测量事件（如 page_view、scroll）。如果你只想看自定义事件，可以在查询条件中加上过滤器：eventName: "your_custom_event"。getEvents 工具本身支持通过 eventName 参数进行过滤。

问题4：runReport 工具的参数比较复杂，如何构造？

解决方案：该工具的参数直接对应 GA4 Data API 的 RunReportRequest。建议先使用内置的简化工具（如 getPageViews）获取灵感。完整参数可以参考 Google Analytics Data API 文档。一个简单的例子是：

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "dimensions": [{ "name": "country" }],
  "metrics": [{ "name": "activeUsers" }]
}

七、总结

mcp-server-google-analytics 是一个非常实用且成熟的 MCP 服务器。它将企业级分析平台 Google Analytics 的数据触角延伸到了对话 AI 中，让数据分析这件事变得前所未有的直接和高效。

该项目的亮点包括：

• 易用性：内置了多个高频分析工具，开箱即用。
• 灵活性：runReport 工具满足了高级用户的自定义需求。
• 安全性：基于服务账号的认证方式符合企业安全实践。
• 生态整合：与 Claude Desktop、Cursor 等工具的深度集成，让数据查询与日常工作流无缝结合。

对于任何依赖网站数据做决策的团队来说，这个服务器都能节省团队大量时间，并降低数据访问的门槛。营销人员、产品经理和开发者都可以通过自然语言直接与数据对话，更快地获得洞察。