mcp-google-analytics

MCP Google Analytics 服务

一个适用于 Google Analytics 4 的模型上下文协议（MCP）服务，可全面集成 Google Analytics Data API（用于读取报告）和 Measurement Protocol v2（用于发送事件）。

既能读取又能写入的 GA4 MCP。 大多数 GA4 MCP 服务（包括 Google 官方服务）都只能读取数据。此服务为你的 AI Agent 提供完整闭环：运行报告和漏斗、审查设置（自定义维度、关键事件、兼容性检查）、在服务器端发送电商和转化事件，并在实时报告中验证——只需一条 npx 命令，即可使用 26 个工具。

也适用于代理机构：每个读取工具都接受可选的 propertyId，因此一次对话即可查询所有客户的媒体资源，无需在客户之间重新配置。请参阅多媒体资源模式。

⚡ 一键安装

开始使用只需要两个值（与其他 GA4 MCP 相同）：服务账号 JSON 和媒体资源 ID。发送事件是可选的额外功能。

点击 Install in Cursor，然后粘贴：

1. GA_SERVICE_ACCOUNT_JSON — 已下载密钥文件的路径，或 JSON 内容本身
2. GA_PROPERTY_ID — GA4 管理 → 媒体资源设置中的数字 ID（例如 123456789）

这样就足以询问“本周按国家/地区划分的用户数”。如需发送事件，之后再添加另外两个键（请参阅发送事件（可选））。

💡 保持报告精简

报告可能会很大。本服务在设计时考虑了令牌优化：

• 所有读取工具默认返回 10 条结果 — 根据需要调整 limit 参数
• 使用具体的日期范围 — 避免一次查询多年的数据
• 仅选择所需维度和指标 — 不要请求所有数据
• 查看 TOKEN_OPTIMIZATION.md，了解详细的最佳实践

请参阅专门的令牌优化指南，了解如何尽量减少令牌用量。

🚀 快速开始

请参阅 QUICKSTART.md，查看 5 分钟设置指南，或按照下方的安装步骤操作。

📦 安装

选项 1：通过 npm 全局安装

npm install -g mcp-google-analytics

选项 2：通过 npx 使用（无需安装）

npx mcp-google-analytics

🔧 配置

从两个值开始。 这就能启用报告、漏斗、实时数据和媒体资源审查——满足大多数人的所有需求，设置方式也与其他 GA4 MCP 相同。

1. 服务账号密钥

1. 在 Google Cloud Console 中启用 Google Analytics Data API。
2. IAM 和管理 → 服务账号 → 创建。下载 JSON 密钥。
3. 在 GA4 中：管理 → 媒体资源访问权限管理 → 将服务账号电子邮件地址添加为查看者。

使用文件路径，或将 JSON 粘贴到 GA_SERVICE_ACCOUNT_JSON 中。

2. 媒体资源 ID

GA4 管理 → 媒体资源设置 → 媒体资源 ID（仅数字，例如 123456789）。

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "mcp-google-analytics"],
      "env": {
        "GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json",
        "GA_PROPERTY_ID": "123456789"
      }
    }
  }
}

现在可以询问：“显示本周按国家/地区划分的活跃用户数。”

发送事件（可选）

仅当你希望 Agent 记录事件（购买、注册、自定义事件）时才需要。大多数 GA4 MCP 都无法执行此操作；这是额外功能，并非必需。

1. GA4 Admin → Data Streams → 你的数据流 → 复制 Measurement ID（G-XXXXXXXXXX）。
2. Measurement Protocol API secrets → Create → 复制密钥。

将它们添加到你已有的两个值旁边：

"GA_MEASUREMENT_ID": "G-XXXXXXXXXX",
"GA_API_SECRET": "your-api-secret"

🏢 多资源模式（代理机构）

每个读取工具都接受可选的 propertyId 参数，该参数会覆盖配置的 GA_PROPERTY_ID，因此，单次对话即可查询服务账号有权访问的任意资源，无需在不同客户端之间重新配置。

1. 在每个客户的 GA4 资源（或账号级别）授予你的服务账号“Viewer”访问权限。
2. 仅设置 GA_SERVICE_ACCOUNT_JSON（GA_PROPERTY_ID 变为可选项；如果已设置，则作为默认值）。
3. 发现资源，然后查询其中任意一个：

Show me all my accounts and properties          → ga_get_account_summaries
Compare last week's active users between the    → ga_run_report with propertyId "111111"
Acme property and the Globex property             and again with propertyId "222222"

propertyId 可接受 123456789 和 properties/123456789 两种格式。事件发送（Measurement Protocol）仍与已配置的 GA_MEASUREMENT_ID/GA_API_SECRET 绑定，因为每个数据流都有自己的密钥。

🔌 与 Claude Desktop 集成

将以下内容添加到 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-google-analytics"],
      "env": {
        "GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json",
        "GA_PROPERTY_ID": "123456789"
      }
    }
  }
}

或者，如果是全局安装：

{
  "mcpServers": {
    "google-analytics": {
      "command": "mcp-google-analytics",
      "env": {
        "GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json",
        "GA_PROPERTY_ID": "123456789"
      }
    }
  }
}

更新配置后，重启 Claude Desktop。

🎯 与 Cursor 集成

将以下内容添加到 Cursor MCP 设置文件中：

macOS/Linux：~/.cursor/mcp.json Windows：%USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "mcp-google-analytics"],
      "env": {
        "GA_SERVICE_ACCOUNT_JSON": "/path/to/service-account.json",
        "GA_PROPERTY_ID": "123456789"
      }
    }
  }
}

更新配置后，重启 Cursor。

🛠️ 可用工具

概览

读取数据（Google Analytics Data API） — 所有读取工具默认返回 10 行，以节省 token：

工具	用途	说明
ga_run_report	使用维度和指标生成自定义报告	按需调整 limit
ga_run_realtime_report	实时数据（最近 30 分钟）	非常适合验证已发送的事件
ga_get_metadata	所有可用维度和指标	响应较大（500 多项），请谨慎使用
ga_list_accounts	列出可访问的 GA 账号
ga_list_properties	列出 GA4 资源	如果没有 accountId，则汇总所有账号
ga_get_property	已配置资源的详细信息
ga_list_data_streams	资源的数据流	可用于查找 Measurement ID
ga_run_pivot_report	透视表报告	响应可能非常大
ga_run_funnel_report	跨事件步骤进行漏斗分析	使用 Data API v1alpha
ga_batch_run_reports	在一个请求中生成多份报告	建议每批处理 2–5 份报告
ga_get_account_summaries	一次调用获取所有账号和资源	发现 ID 的最快方式
ga_list_custom_dimensions	资源的自定义维度	查找用于报告的 API 名称
ga_list_custom_metrics	资源的自定义指标	查找用于报告的 API 名称
ga_list_key_events	资源的关键事件（转化）	了解哪些事件计为转化
ga_list_google_ads_links	与资源关联的 Google Ads 账号
ga_check_compatibility	报告前验证维度和指标的组合	避免浪费请求和陷入错误循环

发送事件（Measurement Protocol）：

工具	用途
ga_send_event	发送带参数的任意自定义 GA4 事件
ga_validate_event	使用调试端点测试事件，不进行记录
ga_send_pageview	页面/屏幕浏览
ga_send_purchase	包含交易和商品信息的电商购买
ga_send_login	用户登录
ga_send_signup	用户注册
ga_send_view_item	商品/项目详情浏览
ga_send_add_to_cart	加入购物车事件
ga_send_begin_checkout	开始结账
ga_send_refund	全额或部分退款

Google Analytics Data API（读取数据）

ga_run_report

使用维度和指标运行自定义报告。

常用维度：date、city、country、deviceCategory、browser、pagePath、eventName、sessionSource、sessionMedium、sessionCampaignName

常用指标：activeUsers、sessions、screenPageViews、conversions、totalRevenue、engagementRate、averageSessionDuration

示例：

{
  "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "city"}],
  "metrics": [{"name": "activeUsers"}],
  "limit": 10
}

ga_run_realtime_report

获取实时数据（最近 30 分钟）。

示例：

{
  "metrics": [{"name": "activeUsers"}],
  "dimensions": [{"name": "country"}],
  "limit": 10
}

ga_get_metadata

获取媒体资源的所有可用维度和指标。

警告：会返回 500 多个条目。请谨慎使用。

ga_list_accounts

列出服务账号可访问的所有 GA 账号。

ga_list_properties

列出 GA4 媒体资源，可按账号 ID 筛选。

ga_get_property

获取已配置媒体资源的详细信息。

ga_list_data_streams

列出已配置媒体资源的数据流。

ga_run_pivot_report

使用行/列维度运行数据透视表报告。

示例：

{
  "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "country"}, {"name": "deviceCategory"}],
  "metrics": [{"name": "activeUsers"}],
  "pivots": [{"fieldNames": ["deviceCategory"], "limit": 5}]
}

ga_run_funnel_report

运行漏斗分析以跟踪用户进展。

注意：漏斗报告使用 Data API v1alpha 通道（Google 唯一开放此功能的通道）。每个步骤对应一个事件：为每个步骤设置 eventName，或省略该字段以使用步骤的 name 作为事件名称。如需高级匹配，请传入完整的 filterExpression。

示例：

{
  "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
  "funnelSteps": [
    {"name": "page_view"},
    {"name": "add_to_cart"},
    {"name": "begin_checkout"},
    {"name": "Purchase", "eventName": "purchase"}
  ]
}

ga_batch_run_reports

在单个请求中运行多个报告。

警告：可能返回大型数据集。每批限制为 2-5 个报告。

ga_get_account_summaries

通过一次简洁调用获取所有可访问账号及其媒体资源。这是查找账号和媒体资源 ID 的最快方式。

ga_list_custom_dimensions / ga_list_custom_metrics

列出为媒体资源定义的自定义维度和指标，包括其 API 名称（例如 customEvent:plan_type），以便在报告中使用。

ga_list_key_events

列出为媒体资源配置的关键事件（转化），便于在构建转化报告之前查看，或决定要发送哪些事件。

ga_list_google_ads_links

列出与媒体资源关联的 Google Ads 账号。

ga_check_compatibility

在运行报告之前检查维度/指标组合是否有效，避免浪费请求和陷入消耗大量令牌的错误循环。

示例：

{
  "dimensions": [{"name": "city"}],
  "metrics": [{"name": "activeUsers"}],
  "compatibilityFilter": "COMPATIBLE"
}

测量协议（发送事件）

须知：

• 事件需要几分钟才会显示在标准报告中，但几乎会立即显示在实时报告中（ga_run_realtime_report）。
• 使用 ga_validate_event 测试新事件，而不会将其记录下来。
• 如果省略 client_id，每次调用都会自动生成一个。若要让 GA 将多个事件（例如，从购物车到购买的流程）归入同一会话和用户，请在每次调用中传入相同的 client_id。

ga_send_event

向 GA4 发送自定义事件。

示例：

{
  "events": [{
    "name": "button_click",
    "params": {
      "button_id": "cta_signup",
      "page": "/landing"
    }
  }],
  "user_id": "user123"
}

ga_validate_event

发送前验证事件（使用调试端点）。

ga_send_pageview

发送页面浏览事件。

示例：

{
  "page_location": "https://example.com/products",
  "page_title": "Products",
  "user_id": "user123"
}

ga_send_purchase

发送电商购买事件。

示例：

{
  "transaction_id": "T12345",
  "value": 99.99,
  "currency": "USD",
  "items": [{
    "item_id": "SKU123",
    "item_name": "Product Name",
    "price": 99.99,
    "quantity": 1
  }]
}

ga_send_login

发送登录事件。

ga_send_signup

发送用户注册事件。

ga_send_view_item

发送产品/商品详情浏览事件。完善标准电商漏斗：view_item → add_to_cart → begin_checkout → purchase。

ga_send_add_to_cart

发送加入购物车事件。

ga_send_begin_checkout

发送发起结账事件。

ga_send_refund

发送全额或部分退款事件。使用与原始购买相同的 transaction_id；全额退款时省略 items，部分退款时包含 items。

示例（部分退款）：

{
  "transaction_id": "T12345",
  "currency": "USD",
  "value": 49.99,
  "items": [{"item_id": "SKU123", "quantity": 1}]
}

📖 使用示例

请参阅 EXAMPLES.md，了解西班牙语的实用示例。

示例：获取过去 7 天按国家/地区划分的用户数

Show me active users by country for the last 7 days

Claude 将使用 ga_run_report：

{
  "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
  "dimensions": [{"name": "country"}],
  "metrics": [{"name": "activeUsers"}],
  "limit": 10,
  "orderBys": [{"metric": {"metricName": "activeUsers"}, "desc": true}]
}

示例：跟踪购买

Send a purchase event for order #12345, $99.99 USD

Claude 将使用 ga_send_purchase：

{
  "transaction_id": "12345",
  "value": 99.99,
  "currency": "USD",
  "items": [{
    "item_id": "product_1",
    "item_name": "Example Product",
    "price": 99.99,
    "quantity": 1
  }]
}

示例：发送事件前验证事件

在接入任何新事件前，建议先使用调试端点检查载荷，而不会记录任何内容。

Validate this tutorial_complete event before we send it for real

Claude 将使用 ga_validate_event：

{
  "client_id": "test.123",
  "events": [{
    "name": "tutorial_complete",
    "params": {"tutorial_id": "onboarding", "duration_seconds": 120}
  }]
}

响应会列出验证消息；如果列表为空，则表示事件格式正确。

示例：服务端转化跟踪

跟踪在后端发生的注册或登录，这些操作不会运行 JavaScript 标签：

A user just registered with Google OAuth, record the signup in Analytics

Claude 将使用 ga_send_signup：

{
  "user_id": "user_789",
  "method": "Google"
}

示例：通过 Agent 跟踪完整电商转化漏斗

每次调用都发送相同的 client_id，以便 GA 将这些事件归入同一个会话：

Track this user's journey: they added a $49 course to the cart, started checkout, and completed the purchase

Claude 将依次调用 ga_send_add_to_cart → ga_send_begin_checkout → ga_send_purchase，并重复使用同一个客户端 ID：

{
  "client_id": "555.1717000000",
  "currency": "USD",
  "value": 49,
  "items": [{"item_id": "course_101", "item_name": "Intro Course", "price": 49, "quantity": 1}]
}

示例：跟踪自动化产生的自定义事件

衡量 GA 原生无法获取的数据，例如 AI Agent 活动或定时任务：

Log that the weekly report generator ran successfully

Claude 将使用 ga_send_event：

{
  "events": [{
    "name": "automation_run",
    "params": {"job": "weekly_report", "status": "success", "duration_ms": 5400}
  }]
}

示例：在一次对话中发送并验证

结合这两个 API，端到端确认跟踪正常运行：

Send a test event and confirm Analytics received it

Claude 将调用 ga_send_event，然后通过 ga_run_realtime_report 检查：

{
  "dimensions": [{"name": "eventName"}],
  "metrics": [{"name": "eventCount"}],
  "limit": 10
}

Measurement Protocol 事件会在数秒内出现在实时报告中，而标准报告可能需要几分钟。

🔍 调试

通过设置以下内容启用调试日志：

export DEBUG=mcp-google-analytics:*

对于 Measurement Protocol，请使用 ga_validate_event 在正式发送前检查事件。

🤝 参与贡献

欢迎参与贡献！欢迎提交 Pull Request。

📄 许可证

MIT 许可证——详情请参阅 LICENSE 文件。

🔗 链接

• GitHub 仓库
• npm 软件包
• Smithery
• MCP 文档
• GA4 Data API 文档
• Measurement Protocol 文档

🆘 支持

如有问题或疑问：

• GitHub Issues
• MCP 社区 Discord

📝 更新日志

版本历史请参阅 CHANGELOG.md。

---