内容
# Google Analytics 4 配置指南
本仓库提供了一步一步的设置指南和配置模板，用于通过模型上下文协议（MCP）将 **Google Analytics 4（GA4）** 连接到您的 AI 优先的开发者工具和 CLI 助手（如 **Claude Code**、**AGI（agy cli）**、**Cursor**、**Windsurf** 和 **Codex**）。
通过使用 `uvx`（通过 PyPI 包 `google-analytics-mcp`），您可以安全地在 stdio 模式下运行 GA4 MCP 服务器，而无需在工作区中手动安装 Python 依赖项。
## 前置条件和安装
### 1. Google Cloud Platform（GCP）设置
1. 前往 **[Google Cloud 控制台](https://console.cloud.google.com/)**。
2. 选择或创建一个项目。
3. 启用以下两个 API：
* **[Google Analytics 管理 API](https://console.developers.google.com/apis/api/analyticsadmin.googleapis.com/overview)**（用于检索可用属性列表）
* **[Google Analytics 数据 API](https://console.developers.google.com/apis/api/analyticsdata.googleapis.com/overview)**（用于查询指标和流量报告）
4. 前往 **APIs & Services > Credentials** 并点击 **Create Credentials > Service Account**。
5. 为您的服务帐户命名（例如，`ga4-mcp`），点击 **Create and Continue**，然后点击 **Done**（不需要 GCP IAM 角色）。
6. 点击您新创建的服务帐户电子邮件地址，在列表中前往 **Keys** 选项卡，点击 **Add Key > Create New Key**，选择 **JSON**，然后点击 **Create**。将下载的 `.json` 密钥文件保存在计算机上的安全位置。
### 2. Google Analytics 4（GA4）访问管理
1. 复制您刚刚创建的服务帐户的电子邮件地址（例如，`ga4-mcp@your-project-id.iam.gserviceaccount.com`）。
2. 登录您的 **[Google Analytics](https://analytics.google.com/)** 帐户。
3. 前往 **Admin（管理）> Account Access Management（账号访问权限管理）**（或 **Property Access Management**，如果您只想授予对单个属性的访问权限）。
4. 点击右上角的 **+** 按钮，添加服务帐户电子邮件地址，并为其分配 **Viewer（查看者）** 角色。
## 查找您的 GA4 属性 ID
如果您不知道您的 GA4 属性 ID，可以使用以下终端命令列出您的服务帐户密钥可访问的所有属性（需要 `uv`）：
```bash
uv run --with google-analytics-admin python -c "
import os
from google.analytics.admin_v1alpha import AnalyticsAdminServiceClient
os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = '/path/to/your/google-credentials.json'
client = AnalyticsAdminServiceClient()
for summary in client.list_account_summaries():
print(f'账户：{summary.display_name}')
for prop in summary.property_summaries:
print(f' 属性：{prop.display_name}，ID：{prop.property.split(\"/\")[-1]}')
"
```
保存您要查询的属性的数字 ID（例如，`123456789`）。
## 配置您的 AI 客户端
复制下载的服务帐户 JSON 密钥的绝对路径，并找到您的 GA4 属性 ID。然后，更新您的客户端配置：
### 1. AGI / agy CLI（Gemini Coder）
将配置添加到您的项目的 `.mcp.json` 或全局 `mcp.json` 设置中：
```json
{
"mcpServers": {
"google-analytics": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"google-analytics-mcp",
"ga4-mcp-server"
],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/google-credentials.json",
"GA4_PROPERTY_ID": "YOUR_GA4_PROPERTY_ID"
}
}
}
}
```
### 2. Claude Code
Claude Code 读取项目级配置或全局桌面设置。将以下代码段添加到您的 `claude_desktop_config.json`（位于 `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS）：
```json
{
"mcpServers": {
"google-analytics": {
"command": "uvx",
"args": [
"--from",
"google-analytics-mcp",
"ga4-mcp-server"
],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/google-credentials.json",
"GA4_PROPERTY_ID": "YOUR_GA4_PROPERTY_ID"
}
}
}
}
```
### 3. Cursor
1. 前往 **Settings > Cursor Settings > Features > MCP**。
2. 点击 **+ Add New MCP Server**。
3. 填写字段：
* **名称**：`google-analytics`
* **类型**：`stdio`
* **命令**：`uvx --from google-analytics-mcp ga4-mcp-server`
4. 添加环境变量：
* 键：`GOOGLE_APPLICATION_CREDENTIALS` | 值：`/path/to/your/google-credentials.json`
* 键：`GA4_PROPERTY_ID` | 值：`YOUR_GA4_PROPERTY_ID`
5. 点击 **保存**。
### 4. Windsurf
将以下内容添加到您的全局配置文件（`~/.codeium/config.json`）：
```json
{
"mcp": {
"servers": {
"google-analytics": {
"command": "uvx",
"args": [
"--from",
"google-analytics-mcp",
"ga4-mcp-server"
],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/google-credentials.json",
"GA4_PROPERTY_ID": "YOUR_GA4_PROPERTY_ID"
}
}
}
}
}
```
## 如何查询 GA4
配置完成后，重启客户端，AI 助手将自动识别工具。您可以使用自然语言查询 GA4：
* *"昨天的网站总用户流量是多少？*"
* *"显示过去 7 天的流量渠道分布情况。*"
* *"现在有实时活跃流量吗？*"
AI 将把您的提示转换为结构化的 GA4 查询，使用暴露的 API 工具（例如 `run_report`、`run_realtime_report`）并呈现聚合指标。
