mcp-ga4-终极版

作者：Gatescrispy1 星标更新：2025-08-06

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

项目介绍

MCP Google Analytics 4 服务器

这是一个全面的模型上下文协议（MCP）服务器，用于与Google Analytics 4集成，提供高级分析能力以支持AI应用程序。

🎯 概述

此MCP服务器使AI应用程序能够通过标准化协议与Google Analytics 4进行交互。它支持数据检索、配置管理、合规性功能以及业务智能自动化。

兼容性：适用于Cursor、Claude Desktop及任何兼容MCP的AI平台。

📊 功能

第一阶段：高级报告（8个工具）

基本指标：核心GA4指标和关键绩效指标（KPIs）
流量分析：来源、页面和用户行为
实时报告：实时数据（标准属性最多可延迟29分钟）
透视报告：跨维度分析
漏斗分析：转换路径跟踪
批处理：多报告自动化

第二阶段：配置管理（13个工具）

自定义维度：创建、读取、更新、归档
自定义指标：生命周期管理
转化事件：配置和管理目标
属性设置：全面配置访问

第三阶段：平台集成（15个工具）

Google Ads：广告活动表现和归属
BigQuery：数据仓库连接
数据流：多平台跟踪设置
测量协议：服务器端事件跟踪

第四阶段：合规性和隐私（10个工具）

GDPR合规性：自动数据主体权利
用户删除：符合隐私的数据移除
数据保留：自动生命周期管理
访问控制：权限和审计管理

第五阶段：商业智能（8个工具）

归属模型：多触点归属分析
受众管理：自动细分
预测分析：基于机器学习的洞察
自定义仪表板：自动报告

总计：54个工具，分布在5个阶段

🔧 安装

先决条件

Python 3.8+
Google Analytics 4 属性
启用了Analytics API的Google Cloud项目

快速设置

安装包：

pip install mcp-ga4-ultimate

配置认证：

# 设置应用默认凭据
gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/analytics.edit

添加到您的MCP客户端：

对于Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "ga4-ultimate": {
      "command": "python",
      "args": ["-m", "mcp_ga4_ultimate"],
      "env": {
        "GOOGLE_ANALYTICS_PROPERTY_ID": "your_property_id"
      }
    }
  }
}

对于Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "ga4-ultimate": {
      "command": "python",
      "args": ["-m", "mcp_ga4_ultimate"],
      "env": {
        "GOOGLE_ANALYTICS_PROPERTY_ID": "your_property_id"
      }
    }
  }
}

🚀 使用示例

基本分析查询

“显示过去30天内流量最高的10个页面”

实时监控

“现在我的网站上发生了什么？显示活跃用户和热门内容”

转化分析

“分析从落地页到购买完成的漏斗”

配置管理

“创建一个用于跟踪用户参与度分数的自定义维度”

GDPR合规性

“处理用户ID为abc123的数据删除请求”

📋 API覆盖

此服务器实现了Google Analytics API的全面覆盖：

API	覆盖范围	工具数
Analytics Data API	完整	15个工具
Analytics Admin API	完整	27个工具
Analytics Measurement Protocol	完整	8个工具
User Deletion API	完整	4个工具

总API覆盖：54个专用工具

🔒 安全与权限

所需OAuth范围

https://www.googleapis.com/auth/analytics.readonly - 数据访问
https://www.googleapis.com/auth/analytics.edit - 配置管理
https://www.googleapis.com/auth/analytics.manage.users - 用户管理

数据隐私

不在本地存储数据
仅直接API通信
符合GDPR的数据处理
符合法规的审计日志

🧪 测试与验证

该服务器包括全面测试：

单元测试：所有54个工具单独测试
集成测试：真实API验证
成功率：92.3%（50/54个工具通过）
错误处理：优雅回退和详细的错误消息

运行测试：

python -m pytest tests/ -v

📖 文档

完整API参考

工具文档 - 所有54个工具的详细信息
配置指南 - 设置和自定义
示例 - 常见用例
故障排除 - 常见问题

开发

贡献指南 - 如何贡献
架构 - 技术设计
测试 - 测试套件详情

🆚 与其他解决方案比较

特征	本服务器	Google官方MCP	基础包
总工具数	54	6	2-3
平台支持	通用MCP	仅Gemini	各异
实时数据	✅ 高级	✅ 基础	❌
配置管理	✅ 完整	❌	❌
GDPR合规性	✅ 内置	❌	❌
商业智能	✅ 自动化	❌	❌
写权限	✅ 完整	❌ 仅读	各异
多触点归属	✅ 高级	❌	❌
测试覆盖率	✅ 92.3%	未知	最小

🤝 贡献

欢迎贡献！请参阅我们的贡献指南了解详情。

开发环境设置

git clone https://github.com/your-org/mcp-ga4-ultimate.git
cd mcp-ga4-ultimate
pip install -e .[dev]

📄 许可证

MIT许可证 - 详情见LICENSE文件。

🔗 链接

📞 支持

文档：docs/
问题：GitHub Issues
讨论：GitHub Discussions

注意：这是一个独立实现。如需官方Google Analytics MCP服务器，请参阅googleanalytics/google-analytics-mcp。