Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

试用 Google Analytics MCP 服务器

借助 Google Analytics Model Context Protocol (MCP) 服务器，您可以将 Google Analytics 数据连接到大语言模型 (LLM) 和 AI 智能体（例如 Gemini）。您可以使用 MCP 服务器以自然语言查询报告、检查媒体资源配置，以及构建自定义分析智能体。

设置 MCP 服务器在 GitHub 上查看观看设置教程

前提条件

在配置 Google Analytics MCP 服务器之前，请满足以下要求：

安装 Python 和软件包运行程序：
- 安装 Python 3.10 或更高版本。
- 安装 pipx 或 uv (uvx)，以便在隔离的 Python 环境中运行 MCP 服务器。
在以下位置启用 Google Analytics API ：
- 创建或选择一个项目。
- 在项目中同时启用 Google Analytics Admin API (analyticsadmin.googleapis.com) 和 Google Analytics Data API (analyticsdata.googleapis.com)：
```
gcloud services enable analyticsadmin.googleapis.com \
  analyticsdata.googleapis.com \
  --project=YOUR_PROJECT_ID
```
授予 Google Analytics 媒体资源访问权限：
- 在 Google Analytics 界面中，为您的用户账号或服务账号授予目标 Google Analytics 媒体资源的查看者角色 (roles/analytics.viewer)。如需了解相关说明，请参阅管理访问权限和数据限制管理。

设置身份验证

Google Analytics MCP 服务器使用应用默认凭证 (ADC) 进行身份验证，并具有只读 Google Analytics OAuth 2.0 范围：

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

您可以使用 Google 用户账号或服务账号配置 ADC。

选项 1：使用用户凭证进行身份验证

安装并初始化 gcloud CLI。

使用所需范围运行 gcloud auth application-default login：

gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

如果您使用下载的 OAuth 2.0 桌面或 Web 客户端配置文件（请参阅管理 OAuth 客户端），请传递 --client-id-file：

gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform" \
  --client-id-file=YOUR_CLIENT_JSON_FILE

命令执行完毕后，复制输出到控制台的凭证路径 (Credentials saved to file: [PATH_TO_CREDENTIALS_JSON])。在 GOOGLE_APPLICATION_CREDENTIALS 中配置 MCP 客户端时，您将使用此路径。

方法 2：使用服务账号进行身份验证

如需使用对您的 Google Analytics 媒体资源具有查看者访问权限的服务账号进行身份验证，请执行以下操作：

服务账号 JSON 密钥文件：将 MCP 客户端配置中的 GOOGLE_APPLICATION_CREDENTIALS 设置为服务账号 JSON 文件的绝对路径。

服务账号模拟：通过使用 gcloud CLI 模拟服务账号来生成 ADC 凭证：

gcloud auth application-default login \
  --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

配置 MCP 客户端

该服务器在 PyPI 上发布为 analytics-mcp，并公开 analytics-mcp 和 google-analytics-mcp 控制台脚本。

在以下配置中，替换：

PATH_TO_CREDENTIALS_JSON 替换为 ADC 或服务账号 JSON 文件的绝对路径。
YOUR_PROJECT_ID 替换为您在其中启用了 Google Analytics API 的项目 ID。

Antigravity CLI 和 Antigravity IDE

安装 Antigravity CLI 或 Antigravity IDE。

将 analytics-mcp 服务器添加到 ~/.gemini/config/mcp_config.json（或工作区中的 .agents/mcp_config.json）：

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

验证 analytics-mcp 是否已连接：
- Antigravity CLI：运行 agy，然后输入 /mcp 以查看已配置的 MCP 服务器。
- Antigravity IDE：依次打开设置 > 自定义 > 已安装的 MCP 服务器，然后点击刷新。

Claude Desktop 和 Claude Code

对于 Claude Desktop，将服务器添加到您的 claude_desktop_config.json 文件中（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json 或 Windows 上的 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

对于 Claude Code，请使用命令行工具注册服务器：

claude mcp add analytics-mcp \
  --scope user \
  -e GOOGLE_APPLICATION_CREDENTIALS="PATH_TO_CREDENTIALS_JSON" \
  -e GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" \
  -- pipx run analytics-mcp

光标

将服务器添加到项目目录中的 .cursor/mcp.json（或全局配置的 ~/.cursor/mcp.json）中。您可以使用 uvx 或 pipx 调用 google-analytics-mcp：

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "uvx",
      "args": ["--from", "analytics-mcp", "google-analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

如需使用 uvx 直接从 GitHub 运行最新的开发版本，请更新 "args"：

"args": [
  "--from",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

或者，如需使用 pipx，请将 "command" 更改为 "pipx"，并将 "args" 设置为：

"command": "pipx",
"args": [
  "run",
  "--spec",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

可用的 MCP 工具

Google Analytics MCP 服务器使用 Admin API 和 Data API v1 向 MCP 客户端公开只读工具：

账号和媒体资源发现 (Admin API)：
- get_account_summaries：列出经过身份验证的用户 (accountSummaries.list) 可访问的 Google Analytics 账号和媒体资源。
- get_property_details：返回特定 Google Analytics 媒体资源 (properties.get) 的配置详细信息。
- list_google_ads_links：列出与媒体资源 (properties.googleAdsLinks.list) 关联的 Google Ads 账号。
- list_property_annotations：列出为媒体资源 (properties.reportingDataAnnotations.list) 配置的注释。
报告和架构检查 (Data API v1)：
- get_custom_dimensions_and_metrics：检索为媒体资源 (getMetadata) 定义的自定义维度和自定义指标。
- run_report：运行标准 Google Analytics 报告 (runReport)。
- run_realtime_report：运行 Google Analytics 实时报告 (runRealtimeReport)。
- run_funnel_report：运行 Google Analytics 漏斗探索报告 (runFunnelReport)。
- run_conversions_report：运行转化效果报告 (runConversionsReport)。

示例提示

连接后，尝试向 AI 助理提问，例如：

我昨天有多少用户？
我昨天最畅销的产品是什么？
我的营销预算是每月 5,000 美元，需要提高收入。帮我制定一份以数据为依据的营销计划。
我的媒体资源中配置了哪些自定义维度和自定义指标？
过去 90 天内，我的 Google Analytics 媒体资源中最热门的事件是什么？

问题排查

请使用以下核对清单来解决常见的设置和运行时错误：

403 PERMISSION_DENIED（API 未启用或媒体资源权限不足）：
- 确认 GOOGLE_CLOUD_PROJECT 指定的项目中已启用 Google Analytics Admin API (analyticsadmin.googleapis.com) 和 Google Analytics Data API (analyticsdata.googleapis.com)。
- 验证进行身份验证的用户或服务账号在 Google Analytics 界面中对目标 Google Analytics 媒体资源至少具有查看者角色 (roles/analytics.viewer)。
- 如果错误状态指出 Request had insufficient authentication scopes，请使用 https://www.googleapis.com/auth/analytics.readonly 和 https://www.googleapis.com/auth/cloud-platform 范围重新运行 gcloud auth application-default login。
缺少配额项目 (GOOGLE_CLOUD_PROJECT) 或 403 ACCESS_NOT_CONFIGURED：
- 使用用户 ADC 凭证进行身份验证的请求需要一个启用了 Google Analytics API 的配额项目。在 MCP 服务器的 env 配置中设置 "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"，或在 ADC 文件中设置配额项目：
```
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
```
找不到 401 UNAUTHENTICATED 或凭据文件：
- 为 GOOGLE_APPLICATION_CREDENTIALS 使用绝对路径（例如 /Users/username/.config/gcloud/application_default_credentials.json）。避免使用 ~ 或 $HOME 变量，因为许多 MCP 主机不会在 JSON 配置文件中展开 shell 变量。
- 如果您的用户凭证已过期，请重新运行 gcloud auth application-default login。
服务器无法启动（spawn pipx ENOENT、uvx: command not found 或 Python 版本错误）：
- 确认已安装 Python 3.10 或更高版本 (python3 --version)。
- 桌面 GUI 应用（例如 Claude Desktop 和 Cursor）通常不会继承交互式 shell PATH。将 "command" 中的 "pipx" 或 "uvx" 替换为 which pipx 或 which uvx 返回的绝对二进制文件路径（例如 /opt/homebrew/bin/pipx 或 /Users/username/.local/bin/pipx）。