谷歌分析MCP服务器
项目介绍
Google Analytics MCP Server 📊
一个基于 FastMCP 的模型上下文协议服务器，用于与 Google Analytics 4 API 集成，并自动进行 OAuth 2.0 身份验证
将 Google Analytics 4 数据直接连接到 Claude Desktop 和其他 MCP 客户端，具有无缝的 OAuth 2.0 身份验证、自动令牌刷新、全面报告和分析功能。
🌟 开源及社区
GoMarble AI 开源项目
查看我们在 GoMarble AI GitHub 上的其他开源贡献：
- 分析工具 - 高级分析和报告解决方案
- AI 集成 - 将 AI 与营销平台集成的工具
- MCP 服务器 - 其他模型上下文协议实现
- 营销自动化 - 开源营销自动化工具
加入我们的社区
与其他使用广告中 AI 的开发者和营销人员联系：
- 💬 讨论 广告中的 AI 应用
- 🤝 分享 你的项目并获取反馈
- 📚 学习 来自行业专家的知识
- 🚀 合作 开源项目
- 🔧 获得帮助 技术实施
🚀 尝试一键集成
跳过手动设置，立即开始：
一键 MCP 集成 - 在几秒钟内将 Google Analytics 和其他工具连接到 Claude Desktop
- ⚡ 即时设置 - 不需要手动配置
- 🔐 安全认证 - 内置 OAuth 处理
- 📊 多种集成 - Google Analytics、Google Ads、Meta Ads 等
- 📖 文档 - 完整的集成指南在 gomarble.ai/docs
✨ 特性
- 🔐 自动 OAuth 2.0 - 一次性浏览器身份验证，自动刷新
- 🔄 智能令牌管理 - 自动处理过期令牌
- 📊 全面报告 - 访问所有 GA4 指标和维度
- 🏢 属性管理 - 列出和管理 Google Analytics 属性
- 📈 高级分析 - 页面浏览量、用户、事件、流量来源等
- 🚀 FastMCP 框架 - 基于现代 MCP 标准构建
- 🖥️ Claude Desktop 就绪 - 直接与 Claude Desktop 集成
- 🛡️ 安全本地存储 - 令牌本地存储，永不暴露
📋 可用工具
| 工具 | 描述 | 参数 | 示例用法 |
|---|---|---|---|
list_properties | 列出所有 GA4 账户和属性 | account_id（可选） | "列出我所有的 Google Analytics 属性" |
get_page_views | 获取页面浏览量指标 | property_id, start_date, end_date, dimensions（可选） | "显示上个月的页面浏览量" |
get_active_users | 获取活跃用户指标 | property_id, start_date, end_date, dimensions（可选） | "获取上周每天的活跃用户" |
get_events | 获取事件指标 | property_id, start_date, end_date, dimensions（可选） | "显示属性 123456789 的事件数据" |
get_traffic_sources | 获取流量来源数据 | property_id, start_date, end_date, dimensions（可选） | "分析过去 30 天的流量来源" |
get_device_metrics | 获取基于设备的指标 | property_id, start_date, end_date, dimensions（可选） | "显示上个月的设备细分" |
run_report | 综合定制报告 | property_id, start_date, end_date, metrics, dimensions, 过滤器等 | "创建按国家划分的会话和转化的自定义报告" |
注意： 所有工具都会自动处理身份验证 - 不需要令牌参数！
🚀 快速入门
前提条件
在设置 MCP 服务器之前，你需要：
- 安装 Python 3.10+
- 一个 Google Cloud Platform 账户
- 一个具有数据访问权限的 Google Analytics 4 属性
🔧 第一步：Google Cloud Platform 设置
1.1 创建 Google Cloud 项目
- 前往 Google Cloud 控制台
- 创建新项目：
- 点击 "选择项目" → "新建项目"
- 输入项目名称（例如，“Google Analytics MCP”）
- 点击 "创建"
1.2 启用 Google Analytics API
- 在你的 Google Cloud 控制台中：
- 转到 "APIs & Services" → "库"
- 搜索 "Google Analytics Data API" 并启用它
1.3 创建 OAuth 2.0 凭据
- 转到 "APIs & Services" → "凭据"
- 点击 "+ 创建凭据" → "OAuth 2.0 客户端 ID"
- 配置同意屏幕（如果是第一次）：
- 点击 "配置同意屏幕"
- 选择 "外部"（除非你有 Google Workspace）
- 填写所需字段：
- 应用名称："Google Analytics MCP"
- 用户支持邮箱：你的邮箱
- 开发者联系方式：你的邮箱
- 添加范围：
https://www.googleapis.com/auth/analyticshttps://www.googleapis.com/auth/analytics.readonly
- 点击 "保存并继续" 通过所有步骤
- 创建 OAuth 客户端：
- 应用类型："桌面应用"
- 名称："Google Analytics MCP 客户端"
- 点击 "创建"
- 下载凭据：
- 点击 "下载 JSON" 按钮
- 将文件保存为
client_secret_[长字符串].json在你的项目目录中
🔧 第二步：Google Analytics 访问
2.1 确保分析访问
- 登录到 Google Analytics
- 验证你是否可以访问 GA4 属性
- 记下你的属性 ID（在 GA4 管理 → 属性设置中找到）
- 确保你的 Google 账户至少具有查看者权限 对你要查询的属性
🔧 第三步：安装与设置
3.1 克隆并安装
# 克隆仓库
git clone https://github.com/yourusername/google-analytics-mcp-server.git
cd google-analytics-mcp-server
# 创建虚拟环境（推荐）
python3 -m venv .venv
source .venv/bin/activate # 在 Windows 上：.venv\Scripts\activate
# 安装依赖项
pip install -r requirements.txt
3.2 环境配置
在你的项目目录中创建一个 .env 文件：
# 复制示例文件
cp .env.example .env
编辑 .env 文件以包含你的凭据：
# 必需：OAuth 凭据 JSON 文件路径（从 Google Cloud 下载）
GOOGLE_ANALYTICS_OAUTH_CONFIG_PATH=/完整路径/到你的/client_secret_file.json
示例 .env 文件：
GOOGLE_ANALYTICS_OAUTH_CONFIG_PATH=/Users/john/google-analytics-mcp/client_secret_138737274875-abc123.apps.googleusercontent.com.json
🖥️ 第四步：Claude Desktop 集成
4.1 查找 Claude 配置
找到你的 Claude Desktop 配置文件：
macOS：
~/Library/Application Support/Claude/claude_desktop_config.json
Windows：
%APPDATA%\Claude\claude_desktop_config.json
4.2 添加 MCP 服务器配置
编辑配置文件并添加你的 Google Analytics MCP 服务器：
{
"mcpServers": {
"google-analytics": {
"command": "/完整路径/到你的/project/.venv/bin/python",
"args": [
"/完整路径/到你的/project/server.py"
]
}
}
}
真实示例：
{
"mcpServers": {
"google-analytics": {
"command": "/Users/marble-dev-01/workspace/google_analytics_mcp/.venv/bin/python",
"args": [
"/Users/marble-dev-01/workspace/google_analytics_mcp/server.py"
]
}
}
}
重要：
- 使用 绝对路径 对所有文件位置
- 在 Windows 上，路径中使用正斜杠
/或双反斜杠\\
4.3 重启 Claude Desktop
关闭并重新启动 Claude Desktop 以加载新的配置。
🔐 第五步：首次身份验证
5.1 触发 OAuth 流程
- 打开 Claude Desktop
- 尝试任何 Google Analytics 命令，例如：
"列出我所有的 Google Analytics 属性"
5.2 完成身份验证
- 浏览器会自动打开 到 Google OAuth 页面
- 使用你的 Google 账户登录（具有 Analytics 访问权限的那个）
- 授予权限 通过点击 "允许"
- 浏览器显示成功页面
- 返回 Claude - 你的命令将自动完成！
5.3 验证设置
身份验证后，你应该看到：
- 项目目录中生成了一个
google_analytics_token.json文件 - 你的 Google Analytics 属性列在 Claude 的响应中
📖 使用示例
属性管理
"列出我所有的 Google Analytics 属性"
"显示账户 123456789 的属性"
"我有权访问哪些 GA4 属性？"
页面浏览量分析
"获取属性 421301275 从 2025-01-01 到 2025-01-31 的页面浏览量"
"显示属性 421301275 上个月按页面浏览量排名最高的页面"
"按国家分析属性 421301275 的页面性能"
用户分析
"获取属性 421301275 最近 7 天的活跃用户"
"显示属性 421301275 按设备类别划分的用户指标"
"比较属性 421301275 上个月的新用户与回访用户"
流量来源分析
"分析属性 421301275 从 2025-01-01 到 2025-01-31 的流量来源"
"显示哪些渠道为我的网站带来了最多的用户"
"比较自然流量与付费流量的表现"
事件跟踪
"获取属性 421301275 最近 30 天的事件数据"
"显示按来源/媒介划分的转换事件"
"在我的网站上最受欢迎的事件是什么？"
自定义报告
"为属性 421301275 创建一份从 2025-01-01 到 2025-01-31 按国家划分的会话、用户和页面浏览量的报告"
"运行一份显示按设备类别划分的跳出率和参与率的自定义报告"
"生成一份综合流量报告，按来源/媒介划分会话、转化和收入"
🔍 高级 GA4 示例
按国家划分的会话和用户
run_report(
property_id="421301275",
start_date="2025-01-01",
end_date="2025-01-31",
metrics=["sessions", "totalUsers", "screenPageViews"],
dimensions=["country"],
limit=20
)
设备性能分析
run_report(
property_id="421301275",
start_date="2025-01-01",
end_date=" 2025-01-31",
metrics=["sessions", "bounceRate", "engagementRate"],
dimensions=["deviceCategory", "operatingSystem"],
limit=50
)
包含转化的流量来源
run_report(
property_id="421301275",
start_date="2025-01-01",
end_date="2025-01-31",
metrics=["sessions", "conversions", "totalRevenue"],
dimensions=["source", "medium", "campaignName"],
limit=100
)
每日趋势分析
run_report(
property_id="421301275",
start_date="2025-01-01",
end_date="2025-01-31",
metrics=["sessions", "activeUsers", "screenPageViews"],
dimensions=["date"],
limit=31
)
📁 项目结构
google-analytics-mcp-server/
├── server.py # 主 MCP 服务器
├── oauth/
│ ├── __init__.py # 包初始化
│ └── google_auth.py # OAuth 身份验证逻辑
├── google_analytics_token.json # 自动生成的令牌存储（已忽略版本控制）
├── client_secret_[长字符串].json # 你的 OAuth 凭据（已忽略版本控制）
├── .env # 环境变量（已忽略版本控制）
├── .env.example # 环境模板
├── .gitignore # Git 忽略文件
├── requirements.txt # Python 依赖项
├── LICENSE # MIT 许可证
└── README.md # 本文件
🔒 安全与最佳实践
文件安全
- ✅ 凭据文件被忽略版本控制 - 从未提交到版本控制
- ✅ 本地令牌存储 - 令牌存储在本地的
google_analytics_token.json中 - ✅ 环境变量 - 敏感数据在
.env文件中 - ✅ 自动刷新 - 最小化令牌暴露时间
推荐文件权限
# 为敏感文件设置安全权限
chmod 600 .env
chmod 600 google_analytics_token.json
chmod 600 client_secret_*.json
生产考虑
- 在生产中使用环境变量 而不是
.env文件 - 实现速率限制 以尊重 API 配额
- 监控 API 使用情况 在 Google Cloud 控制台
- 安全令牌存储 使用适当的访问控制
- 定期令牌轮换 以增强安全性
🛠️ 故障排除
身份验证问题
| 问题 | 症状 | 解决方案 |
|---|---|---|
| 未找到令牌 | "开始 OAuth 流程" 消息 | ✅ 正常的初次设置 - 完成浏览器身份验证 |
| 令牌刷新失败 | "刷新令牌失败" 错误 | ✅ 删除 google_analytics_token.json 并重新认证 |
| OAuth 流程失败 | 浏览器错误或无响应 | 检查凭据文件路径和互联网连接 |
| 权限被拒绝 | 浏览器中的 "访问被拒" | 确保 Google 账户具有 Analytics 访问权限 |
配置问题
| 问题 | 症状 | 解决方案 |
|---|---|---|
| 缺少环境变量 | "环境变量未设置" | 检查 .env 文件和 Claude 配置 env 部分 |
| 文件未找到 | "FileNotFoundError" | 验证配置中的绝对路径 |
| 模块导入错误 | "ModuleNotFoundError" | 运行 pip install -r requirements.txt |
| Python 路径问题 | "命令未找到" | 使用 Python 可执行文件的绝对路径 |
Claude Desktop 问题
| 问题 | 症状 | 解决方案 |
|---|---|---|
| 服务器无法连接 | 无 Google Analytics 工具可用 | 重启 Claude Desktop，检查配置文件语法 |
| 无效的 JSON 配置 | Claude 启动错误 | 验证配置文件中的 JSON 语法 |
| 权限错误 | 启动时 "权限被拒" | 检查文件权限和路径 |
API 问题
| 问题 | 症状 | 解决方案 | |-------|----------|