Google Analytics 4

@mindstone/mcp-server-google-analytics

适用于 Model Context Protocol 主机的 Google Analytics 4 MCP 服务。通过标准化的 MCP 接口发现账号／媒体资源结构、探索实时架构、运行报告（包含行数安全保护）、创建大型异步导出，并检查管理配置。

状态

• 版本： 0.2.1 · npm
• 身份验证： 通过 Google ADC 使用 OAuth（GOOGLE_APPLICATION_CREDENTIALS）
• 工具： 34（账号、架构、报告、管理）
• 服务类型： cloud-api
• 机器可读： STATUS.json

要求

• Node.js 20+
• npm
• 具有 analytics.readonly 范围的 Google Application Default Credentials（ADC），或可访问 GA4 媒体资源的服务账号 JSON

一键安装

点击按钮后，主机将提示你填写：GOOGLE_APPLICATION_CREDENTIALS。

{
  "mcpServers": {
    "Google Analytics 4": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-google-analytics"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": ""
      }
    }
  }
}

快速开始

安装和构建

cd <path-to-repo>/connectors/google-analytics
npm install
npm run build

npx（发布后使用）

npx -y @mindstone/mcp-server-google-analytics

本地

node dist/index.js

身份验证

此服务使用 Google Application Default Credentials（ADC）。安装 Google Cloud CLI 并运行以下命令，为用户账号创建 ADC：

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/analytics.readonly \
  --client-id-file=/absolute/path/to/oauth-client-secret.json

--client-id-file 为可选参数，但强烈建议使用——使用你自己的 OAuth 客户端可以避免共享 gcloud 配额，并提供稳定的验证环境。你需要一个已启用 Google Analytics Admin API 和 Google Analytics Data API 的 Google Cloud 项目。

对于服务账号，将 GOOGLE_APPLICATION_CREDENTIALS 设置为服务账号 JSON 文件的绝对路径。必须在 GA4 管理界面中授予该服务账号访问 GA4 媒体资源的权限。

配置

环境变量

• GOOGLE_APPLICATION_CREDENTIALS — 必需。ADC 或服务账号 JSON 文件的绝对路径。Node 不会展开 ~ 或 %APPDATA% — 请提供完整解析后的路径。
• GA4_PROPERTY_ID — 可选。默认 GA4 媒体资源 ID（例如 123456789）。调用时未传入 property_id 的话，工具将使用此值。

主机配置示例

Claude Desktop / Cursor

{
  "mcpServers": {
    "GoogleAnalytics": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-google-analytics"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/you/.config/gcloud/application_default_credentials.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

本地开发（无需发布到 npm）

{
  "mcpServers": {
    "GoogleAnalytics": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/google-analytics/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/credentials.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

工具（34）

账号和媒体资源

• ga_list_account_summaries — 查找可用账号和媒体资源
• ga_list_properties — GA4 媒体资源的平面列表，支持可选筛选
• ga_get_property_details — 货币、时区、行业类别、服务级别

架构发现

• ga_get_metadata — 实时媒体资源架构
• ga_get_property_schema — 相同数据及汇总计数
• ga_search_schema — 在维度和指标中进行关键词搜索
• ga_list_dimension_categories、ga_list_metric_categories
• ga_get_dimensions_by_category、ga_get_metrics_by_category
• ga_check_compatibility — 在生成报告前验证维度和指标组合

报告

• ga_run_report — 核心报告，并提供行数安全保护（估算、选择加入大型数据集、自动提供聚合建议）
• ga_run_pivot_report — 交叉表报告
• ga_batch_run_reports — 单次调用最多运行 5 份报告
• ga_run_realtime_report — 最近 30 分钟的活动
• ga_get_property_quotas_snapshot — 剩余令牌 / 请求数

大型导出

• ga_create_report_task — 为大型导出启动异步报告任务（无同步超时限制，也无行数门槛）
• ga_get_report_task — 轮询任务状态，直到 ACTIVE
• ga_query_report_task — 对任务行进行分页查询（每页最多 250,000 行）
• ga_create_audience_export — 对受众中的用户进行快照（包括预测细分）；会扣除受众导出配额令牌
• ga_get_audience_export — 轮询导出状态，直到 ACTIVE
• ga_list_audience_exports — 查找并复用现有导出
• ga_query_audience_export — 对 ACTIVE 导出中的用户级行进行分页查询

管理可见性

• ga_list_audiences — 媒体资源上配置的受众，支持筛选子句
• ga_list_channel_groups — 渠道组及其分组规则
• ga_get_custom_dimensions_and_metrics
• ga_list_google_ads_links
• ga_list_key_events
• ga_list_data_streams
• ga_get_global_site_tag — 第一个 Web 数据流的 gtag.js 代码片段
• ga_list_bigquery_links
• ga_get_data_retention_settings
• ga_list_firebase_links
• ga_search_change_history_events

备注

• 只读模式。 除 ga_create_report_task 和 ga_create_audience_export 外，所有工具均为只读。这两个工具会生成服务端快照并扣除配额（标注为 readOnlyHint: false、destructiveHint: true、idempotentHint: false），但不会修改媒体资源配置。宿主可以要求用户明确批准后再调用这两个创建工具。
• Alpha 端点。 受众、渠道组、BigQuery 链接、全局网站代码、变更历史（Admin API）和报告任务（Data API）目前仅通过 Google 的 v1alpha 接口提供；相应工具的描述中会注明这一点。
• 不可信内容。 GA4 媒体资源中撰写的文本——报告维度值（网页标题、广告系列名称、自定义维度值）、受众 / 显示名称、描述、定义数据块、数据流数据块、全局网站代码片段、自定义元数据表达式、供应商回显的标头 / 维度名称以及供应商错误消息——都会放在 <untrusted-content source="…"> 封装中返回，以便宿主将其视为数据，而非指令。指标值和资源标识符保持原样，以便 Agent 组合后续调用。传递给工具的资源 ID 会在插入 URL 前限制为符合 ID 字符集的内容（其他内容会触发 INVALID_RESOURCE_ID）。
• 响应验证。 每个 Google API 响应都会在边界处根据 Zod 架构进行验证；如果数据结构不匹配，将以 INVALID_API_RESPONSE 错误安全失败，而不会传递格式错误的数据。分页列表会完整跟进 nextPageToken；如果 API 在达到宽松的安全上限后仍未停止分页，则会触发 PAGINATION_LIMIT_EXCEEDED，绝不会静默截断。

许可

FSL-1.1-MIT — Functional Source License, Version 1.1，附带未来转为 MIT 许可的条款。该软件将在发布两周年之际转为 MIT 许可。