谷歌分析MCP服务器
mcp名称：io.github.srendranb/google-analytics mcp
](https://badge.fury.io/py/google-analytics-mcp) ](https://pepy.tech/projects/google-analytics-mcp) ](https://github.com/surendranb/google-analytics-mcp/stargazers) ](https://github.com/surendranb/google-analytics-mcp/network/members)   
将Google Analytics 4数据连接到AI代理、代理工作流和MCP客户端。通过模式发现、服务器端聚合和减少数据争用的安全默认值，使代理能够随时分析网站流量、用户行为和性能数据。
适用于： Claude、ChatGPT、Cursor、Windsurf和自定义主机上的AI代理、分析师副驾驶和MCP运行时。
我还建了一个 谷歌搜索控制台MCP 这使您能够混合和匹配来自两个来源的数据
为什么代理使用此服务器
- 分析就绪输出 通过服务器端聚合，代理可以花更多的时间回答问题，更少的时间处理行
- 实时架构发现 对于每个GA4属性，包括基于类别的维度和度量探索
- 上下文安全默认值 在大型数据集破坏对话或工作流程之前对其进行估计
- 便携式MCP表面 它适用于代理运行时、IDE副本和自定义自动化
______________________________________________________________________
先决条件
检查你的Python设置：
# Check Python version (need 3.10+)
python --version
python3 --version
# Check pip
pip --version
pip3 --version必修的：
- Python 3.10或更高版本
- 谷歌分析4属性与数据
- 具有Google Analytics Data API访问权限和GA4属性访问权限的服务帐户
______________________________________________________________________
步骤1：设置Google Analytics凭据
在Google Cloud控制台中创建服务帐户
- 首选 谷歌云控制台
- 创建或选择项目:
- 新建项目：点击“新建项目”→ 输入项目名称→ 创建 - 现有项目：从下拉列表中选择
- 启用分析API:
- 转到“API和服务”→ “图书馆” - 搜索“Google Analytics Data API”→ 点击“启用”
- 创建服务帐户:
- 转到“API和服务”→ “凭据” - 点击“创建凭据”→ “服务帐户” - 输入名称（例如，“ga4-mcp服务器”） - 点击“创建并继续” - 跳过角色分配→ 点击“完成”
- 下载JSON密钥:
- 单击您的服务帐户 - 转到“密钥”选项卡→ “添加密钥”→ “创建新密钥” - 选择“JSON”→ 点击“创建” - 保存JSON文件-您需要它的路径
将服务帐户添加到GA4
- 获取服务帐户电子邮件:
- 打开JSON文件 - 找到 client_email 领域 - 复制电子邮件（格式： ga4-mcp-server@your-project.iam.gserviceaccount.com)
- 添加到GA4属性:
- 首选 谷歌分析 - 选择您的GA4房产 - 点击“管理员”（左下角的齿轮图标） - 在“财产”项下→ 点击“物业访问管理” - 点击“+”→“添加用户” - 粘贴服务帐户电子邮件 - 选择“查看器”角色 - 取消选中“通过电子邮件通知新用户” - 点击“添加”
查找您的GA4房产ID
- 在 谷歌分析，选择您的房产
- 点击“管理”（齿轮图标）
- 在“财产”项下→ 点击“物业详情”
- 复制 属性ID （数字。，
123456789)
- 备注：这与“测量ID”（以G-开头）不同
测试您的设置（可选）
验证您的凭据：
pip install google-analytics-data创建测试脚本(test_ga4.py):
import os
from google.analytics.data_v1beta import BetaAnalyticsDataClient
# Set credentials path
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/path/to/your/service-account-key.json"
# Test connection
client = BetaAnalyticsDataClient()
print("✅ GA4 credentials working!")运行测试：
python test_ga4.py如果你看到“✅ GA4证书有效！“你准备好继续了。
______________________________________________________________________
步骤2：安装MCP服务器
有两种支持的启动服务器的方法：
ga4-mcp-server当安装的控制台脚本在您的PATHpython -m ga4_mcp当你想使用特定的解释器或虚拟环境时
方法A：从PyPI安装（推荐）
python3 -m pip install google-analytics-mcp如果您的机器使用 python 而不是 python3，运行：
python -m pip install google-analytics-mcp选项1：使用控制台脚本
在以下情况下使用此功能 ga4-mcp-server 可在您的 PATH:
{
"mcpServers": {
"ga4-analytics": {
"command": "ga4-mcp-server",
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
"GA4_PROPERTY_ID": "123456789"
}
}
}
}选项2：使用显式Python解释器
当您想固定确切的Python运行时或控制台脚本不在您的 PATH.
如果 python3 --version 工作：
{
"mcpServers": {
"ga4-analytics": {
"command": "python3",
"args": ["-m", "ga4_mcp"],
"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"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
"GA4_PROPERTY_ID": "123456789"
}
}
}
}方法B：从本地克隆安装
git clone https://github.com/surendranb/google-analytics-mcp.git
cd google-analytics-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .如果您计划在本地修改包，请使用 python -m pip install -e . 相反。
MCP配置：
{
"mcpServers": {
"ga4-analytics": {
"command": "/full/path/to/google-analytics-mcp/.venv/bin/python",
"args": ["-m", "ga4_mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
"GA4_PROPERTY_ID": "123456789"
}
}
}
}______________________________________________________________________
步骤3：更新配置
替换MCP配置中的这些占位符：
/path/to/your/service-account-key.json带有JSON密钥的绝对路径123456789使用您的数字GA4属性ID/full/path/to/google-analytics-mcp/.venv/bin/python使用虚拟环境的Python路径（仅限方法B）
______________________________________________________________________
用法
配置后，向MCP客户端提出以下问题：
发现与探索
- 哪些GA4维度类别可用？
- 显示所有电子商务指标
- 我可以使用哪些维度进行地理分析？
流量分析
- 过去一周我的网站流量是多少？
- 按城市显示上个月的用户指标
- 比较不同日期范围之间的跳出率
多维分析
- 按国家和设备类别显示过去30天的收入
- 按活动和来源/媒介分析会话和转换
- 比较不同页面路径和流量来源的用户参与度
电子商务分析
- 我的收入最高的产品是什么？
- 按流量来源和设备类型显示转化率
- 按用户人口统计分析购买行为
______________________________________________________________________
快速入门示例
尝试以下示例查询以查看MCP的分析能力：
1.地理分布
Show me a map of visitors by city for the last 30 days, with a breakdown of new vs returning users这表明：
- 地理分析
- 用户细分
- 基于时间的过滤
- 数据可视化
2.用户行为分析
Compare average session duration and pages per session by device category and browser over the last 90 days这表明：
- 多维分析
- 时间序列比较
- 用户参与度指标
- 技术细分
3.流量源性能
Show me conversion rates and revenue by traffic source and campaign, comparing last 30 days vs previous 30 days这表明：
- 营销绩效分析
- 期间比较
- 转化跟踪
- 收入归属
4.内容表现
What are my top 10 pages by engagement rate, and how has their performance changed over the last 3 months?这表明：
- 内容分析
- 趋势分析
- 参与度指标
- 排名和排序
______________________________________________________________________
🚀 性能优化
此MCP服务器包括 内置优化 为了防止上下文窗口崩溃并确保平稳运行：
智能数据量管理
- 自动行估计 -取数前检查数据量
- 交互式警告 -当查询返回的行数超过2500行时发出警报
- 优化建议 -提供减少数据量的具体建议
服务器端处理
- 智能聚合 -在有利的情况下自动聚合数据（例如，跨时间段的总计）
- 智能分拣 -首先返回最相关的数据（最近日期、最高值）
- 高效过滤 -利用GA4的服务器端过滤功能
用户控制参数
limit-设置要返回的最大行数proceed_with_large_dataset=True-覆盖大型数据集的警告enable_aggregation=False-禁用自动聚合estimate_only=True-在不获取数据的情况下获取行数估计值
示例：处理大型数据集
# This query would normally return 2,605 rows and crash context window
get_ga4_data(
dimensions=["date", "pagePath", "country"],
date_range_start="90daysAgo"
)
# Returns: {"warning": True, "estimated_rows": 2605, "suggestions": [...]}
# Use monthly aggregation instead
get_ga4_data(
dimensions=["month", "pagePath", "country"],
date_range_start="90daysAgo"
)
# Returns: Clean monthly data with manageable row count______________________________________________________________________
可用工具
服务器提供了一套用于数据报告和模式发现的工具。
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广告：活动、广告组、关键字数据
- 10多个类别
度量类别
- 使用者评价：totalUsers、newUsers、activeUsers
- 会话指标：会话数、跳出率、参与率
- 电子商务：总收入、交易、转换
- 事件：eventCount、转换、事件值
- 广告：adRevenue，return On AdSpend
- 以及更专业的指标
______________________________________________________________________
故障排除
如果 ga4-mcp-server 未找到：
- 请改用显式解释器启动样式：
python -m ga4_mcp - 使用MCP客户端将使用的Python解释器重新安装
如果你得到 No module named ga4_mcp:
/full/path/to/python -m pip install google-analytics-mcp使用您在MCP配置中引用的确切解释器安装该包。
权限错误：
# Try user install instead of system-wide
python -m pip install --user google-analytics-mcp如果服务器说凭据文件丢失：
- 验证JSON文件路径 是绝对、正确和可访问的
- 检查服务帐户权限:
- 转到谷歌云控制台→ IAM和管理员→ IAM - 查找您的服务帐户→ 检查权限
- 验证GA4访问权限:
- GA4 → 管理员→ 物业出入管理 - 检查您的服务帐户电子邮件
如果服务器说 GA4_PROPERTY_ID 无效或查询未返回任何数据：
- 使用数字 属性ID （例如
123456789) - 做 不 使用 测量ID （例如
G-XXXXXXXXXX) - 确认服务帐户至少对该属性具有查看器访问权限
API配额/速率限制错误：
- GA4有每日配额和费率限制
- 尝试缩小查询中的日期范围
- 在大型请求之间等待几分钟
______________________________________________________________________
项目结构
google-analytics-mcp/
├── ga4_mcp/ # Main package directory
│ ├── server.py # Core server logic
│ ├── coordinator.py # MCP instance
│ └── tools/ # Tool definitions (reporting, metadata)
├── pyproject.toml # Package configuration for PyPI
├── requirements.txt # Dependencies for local dev
├── README.md # This file
└── ...______________________________________________________________________
许可证
Apache许可证2.0