谷歌分析-MCP

Name: 谷歌分析-MCP
Author: surendranb

作者：surendranb156 星标更新：2025-11-09

安装使用来源：spider==github.com

项目介绍

Google Analytics MCP 服务器

mcp-name: io.github.surendranb/google-analytics-mcp

连接 Google Analytics 4 数据到 Claude、Cursor 和其他 MCP 客户端。使用自然语言查询您的网站流量、用户行为和分析数据，访问超过 200 个 GA4 维度和指标。

兼容性： Claude、Cursor 和其他 MCP 客户端。

我还构建了一个 Google 搜索控制台 MCP，使您可以混合匹配来自两个来源的数据。

</p>

预备条件

检查您的 Python 设置：

# 检查 Python 版本（需要 3.10 或更高）
python --version
python3 --version

# 检查 pip
pip --version
pip3 --version

必需项：

Python 3.10 或更高版本
包含数据的 Google Analytics 4 属性
具有 Analytics Reporting API 访问权限的服务账户

第一步：设置 Google Analytics 凭据

在 Google Cloud 控制台中创建服务账户

转到 Google Cloud 控制台
创建或选择项目：
- 新项目：点击“新建项目”→ 输入项目名称 → 创建
- 现有项目：从下拉菜单中选择
启用 Analytics API：
- 前往“APIs & Services”→ “库”
- 搜索“Google Analytics Data API”→ 点击“启用”
创建服务账户：
- 前往“APIs & Services”→ “凭据”
- 点击“创建凭据”→ “服务账户”
- 输入名称（例如，“ga4-mcp-server”）
- 点击“创建并继续”
- 跳过角色分配 → 点击“完成”
下载 JSON 密钥：
- 点击您的服务账户
- 前往“密钥”标签页 → “添加密钥”→ “创建新密钥”
- 选择“JSON”→ 点击“创建”
- 保存 JSON 文件 —— 您需要其路径

将服务账户添加到 GA4

获取服务账户电子邮件地址：
- 打开 JSON 文件
- 查找 client_email 字段
- 复制电子邮件（格式：ga4-mcp-server@your-project.iam.gserviceaccount.com）
添加到 GA4 属性：
- 转到 Google Analytics
- 选择您的 GA4 属性
- 点击“管理”（左下角的齿轮图标）
- 在“属性”下 → 点击“属性访问管理”
- 点击“+”→ “添加用户”
- 粘贴服务账户电子邮件
- 选择“查看者”角色
- 取消选中“通过电子邮件通知新用户”
- 点击“添加”

查找您的 GA4 属性 ID

在 Google Analytics 中，选择您的属性
点击“管理”（齿轮图标）
在“属性”下 → 点击“属性详情”
复制 属性 ID（数字形式，例如 123456789）
- 注意： 这与“测量 ID”不同（以 G- 开头）

测试您的设置（可选）

验证您的凭据：

pip install google-analytics-data

创建一个测试脚本（test_ga4.py）：

import os
from google.analytics.data_v1beta import BetaAnalyticsDataClient

# 设置凭据路径
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/path/to/your/service-account-key.json"

# 测试连接
client = BetaAnalyticsDataClient()
print("✅ GA4 凭据正常工作！")

运行测试：

python test_ga4.py

如果您看到“✅ GA4 凭据正常工作！”则可以继续进行下一步。

第二步：安装 MCP 服务器

选择一种方法：

方法 A：pip 安装（推荐）

pip install google-analytics-mcp

MCP 配置：

首先，检查您的 Python 命令：

python3 --version
python --version

然后使用适当的配置：

如果 python3 --version 工作：

{
  "mcpServers": {
    "ga4-analytics": {
      "command": "python3",
      "args": ["-m", "ga4_mcp_server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

如果 python --version 工作：

{
  "mcpServers": {
    "ga4-analytics": {
      "command": "python",
      "args": ["-m", "ga4_mcp_server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

方法 B：GitHub 下载

git clone https://github.com/surendranb/google-analytics-mcp.git
cd google-analytics-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

MCP 配置：

{
  "mcpServers": {
    "ga4-analytics": {
      "command": "/full/path/to/ga4-mcp-server/venv/bin/python",
      "args": ["/full/path/to/ga4-mcp-server/ga4_mcp_server.py"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

第三步：更新配置

在您的 MCP 配置中替换这些占位符：

/path/to/your/service-account-key.json 替换为您 JSON 文件的路径
123456789 替换为您的 GA4 属性 ID
/full/path/to/ga4-mcp-server/ 替换为您下载的路径（仅限方法 B）

使用

配置完成后，向您的 MCP 客户端提问如下：

发现与探索

可用的 GA4 维度类别有哪些？
显示所有电子商务指标
我可以用于地理分析的维度有哪些？

流量分析

我过去一周的网站流量是多少？
显示上个月按城市划分的用户指标
对比不同日期范围内的跳出率

多维分析

显示过去 30 天内按国家和地区设备类别的收入
分析会话和转化率按活动和来源/媒介
对比不同页面路径和流量源之间的用户参与度

电子商务分析

按收入表现最好的产品是什么？
显示按流量源和设备类型划分的转化率
分析按用户人口统计的购买行为

快速入门示例

尝试这些示例查询以了解 MCP 的分析能力：

1. 地理分布

显示过去 30 天内按城市的访客地图，并按新访客和回访者细分

这展示了：

地理分析
用户分段
时间过滤
数据可视化

2. 用户行为分析

比较过去 90 天内按设备类别和浏览器划分的平均会话时长和每会话页面数

这展示了：

多维分析
时间序列对比
用户参与度指标
技术分段

3. 流量源性能

显示过去 30 天与前 30 天相比按流量源和活动划分的转化率和收入

这展示了：

营销绩效分析
同期对比
转化跟踪
收入归属

4. 内容表现

我的前 10 个页面按参与率排名如何，它们的表现在过去 3 个月内有何变化？

这展示了：

内容分析
趋势分析
参与度指标
排序和筛选

🚀 性能优化

此 MCP 服务器包括内置优化以防止上下文窗口崩溃并确保平稳运行：

智能数据量管理

自动行估算 - 在获取数据之前检查数据量
交互警告 - 当查询返回 >2,500 行时发出警报
优化建议 - 提供具体建议以减少数据量

服务器端处理

智能聚合 - 自动聚合数据（例如，时间周期总计）
智能排序 - 返回最相关数据（最近日期，最高值）
高效过滤 - 利用 GA4 的服务器端过滤功能

用户控制参数

limit - 设置要返回的最大行数
proceed_with_large_dataset=True - 覆盖大型数据集的警告
enable_aggregation=False - 禁用自动聚合
estimate_only=True - 获取行数估计而不获取数据

示例：处理大型数据集

# 此查询通常会返回 2,605 行并导致上下文窗口崩溃
get_ga4_data(
    dimensions=["date", "pagePath", "country"],
    date_range_start="90daysAgo"
)
# 返回：{"warning": True, "estimated_rows": 2605, "suggestions": [...]}

# 使用每月聚合代替
get_ga4_data(
    dimensions=["month", "pagePath", "country"], 
    date_range_start="90daysAgo"
)
# 返回：干净的月度数据，具有可控的行数

可用工具

服务器提供了一系列工具用于数据报告和模式发现。

search_schema - 在所有可用维度和指标中搜索关键字。这是发现查询字段的最有效方式。
get_ga4_data - 获取 GA4 数据，内置智能以获得更好更安全的结果（包括数据量保护、智能聚合和智能排序）。
list_dimension_categories - 列出所有可用的维度类别。
list_metric_categories - 列出所有可用的指标类别。
get_dimensions_by_category - 获取特定类别的所有维度。
get_metrics_by_category - 获取特定类别的所有指标。
get_property_schema - 返回属性的完整模式（警告：这可能是一个非常大的对象）。

维度与指标

访问组织好的 200+ GA4 维度和指标：

维度类别

时间：日期、小时、月份、年份等
地理：国家、城市、地区
技术：浏览器、设备、操作系统
流量源：活动、来源、媒介、渠道组
内容：页面路径、标题、内容组
电子商务：商品详情、交易信息
用户人口统计：年龄、性别、语言
Google 广告：活动、广告组、关键词数据
以及更多类别

指标类别

用户指标：总用户数、新用户数、活跃用户数
会话指标：会话数、跳出率、参与率
电子商务：总收入、交易数、转化数
事件：事件计数、转化数、事件值
广告：广告收入、广告支出回报率
以及其他专业指标

故障排除

如果遇到“没有名为 ga4_mcp_server 的模块”错误（方法 A）：

pip3 install --user google-analytics-mcp

如果遇到“找不到可执行文件”错误：

尝试另一种 Python 命令（python vs python3）
如果需要，使用 pip3 而不是 pip

权限错误：

# 尝试用户安装而不是系统范围安装
pip install --user google-analytics-mcp

凭据不起作用：

验证 JSON 文件路径是否正确且可访问
检查服务账户权限：
- 转到 Google Cloud 控制台 → IAM & Admin → IAM
- 查找您的服务账户 → 检查权限
验证 GA4 访问：
- GA4 → 管理 → 属性访问管理
- 检查是否有您的服务账户电子邮件
验证 ID 类型：
- 属性 ID：数字形式（例如，123456789）✅
- 测量 ID：以 G- 开头（例如，G-XXXXXXXXXX）❌

API 配额/速率限制错误：

GA4 每天有配额和速率限制
尝试减少查询中的日期范围
在大型请求之间等待几分钟

项目结构

google-analytics-mcp/
├── ga4_mcp/                # 主包目录
│   ├── server.py           # 核心服务器逻辑
│   ├── coordinator.py      # MCP 实例
│   └── tools/              # 工具定义（报告、元数据）
├── pyproject.toml          # PyPI 的包配置
├── requirements.txt        # 本地开发依赖
├── README.md               # 本文件
└── ...

许可证

MIT 许可证