Google Analytics MCP：连接GA4数据与大模型的本地服务器工具

Google Analytics MCP（Model Context Protocol）是一个开源工具，允许用户通过本地服务器连接Google Analytics 4 (GA4) 数据与大模型（如Claude、Cursor等）。它通过Google Analytics Admin API和Data API提供数据查询和管理功能。用户可以在本地运行服务器，借助自然语言处理分析网站流量、用户行为等数据。项目托管在GitHub，由Google Analytics团队维护，支持Python环境，适合开发者和数据分析师使用。代码更新频繁，最近一次更新在2025年7月，社区活跃度较高。

功能列表

• 获取Google Analytics账户和属性信息。
• 查询特定属性的详细信息，如配置和设置。
• 列出与Google Ads账户的链接。
• 运行GA4数据报告，支持自定义维度和指标。
• 获取特定属性的核心报告维度，包括自定义维度。
• 获取特定属性的核心报告指标，包括自定义指标。
• 提供标准维度和指标列表，方便数据分析。
• 支持自然语言查询，结合大模型处理复杂数据需求。

使用帮助

安装流程

要使用Google Analytics MCP，用户需在本地环境中安装并配置服务器。以下是详细的安装和使用步骤：

1. 准备环境
   • 确保系统已安装Python 3.10或更高版本。运行以下命令检查版本：

     python --version
     python3 --version
     

   • 安装pip并检查版本：

     pip --version
     pip3 --version
     

2. 克隆仓库
   使用Git克隆Google Analytics MCP仓库到本地：

   git clone https://github.com/googleanalytics/google-analytics-mcp.git
   cd google-analytics-mcp
   

3. 创建虚拟环境
   为避免依赖冲突，建议创建Python虚拟环境：

   python3 -m venv venv
   source venv/bin/activate  # Linux/Mac
   venv\Scripts\activate     # Windows
   

4. 安装依赖
   在虚拟环境中安装项目所需依赖：

   pip install -r requirements.txt
   

5. 配置Google Analytics凭据
   • 在Google Cloud Console中创建服务账户，启用Google Analytics Data API。
   • 下载服务账户的JSON密钥文件，路径记为/path/to/your/service-account-key.json。
   • 设置环境变量GOOGLE_APPLICATION_CREDENTIALS：

     export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"  # Linux/Mac
     set GOOGLE_APPLICATION_CREDENTIALS="path\to\your\service-account-key.json"     # Windows
     

   • 可选：编辑~/.gemini/settings.json，添加凭据路径：

     {
     "mcpServers": {
     "analytics-mcp": {
     "command": "pipx",
     "args": ["run", "--spec", "git+https://github.com/googleanalytics/google-analytics-mcp.git", "google-analytics-mcp"],
     "env": {
     "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json"
     }
     }
     }
     }
     

6. 运行服务器
   使用以下命令启动MCP服务器：

   pipx run --spec git+https://github.com/googleanalytics/google-analytics-mcp.git google-analytics-mcp
   

   或在虚拟环境中运行：

   python -m ga4_mcp_server
   

7. 测试连接
   运行以下代码验证GA4凭据：

   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 credentials working!")
   

   如果看到“✅ GA4 credentials working!”，说明配置成功。

主要功能操作

1. 获取账户和属性信息
   使用get_account_summaries工具查询用户的Google Analytics账户和属性列表。运行后，服务器返回账户ID、属性ID等信息，适合快速了解账户结构。
2. 运行数据报告
   使用run_report工具生成GA4报告。用户需指定属性ID、日期范围、维度和指标。例如，查询最近7天的国家/地区和活跃用户数据：

   {
   "propertyId": "properties/123456789",
   "dateRanges": [{"startDate": "7daysAgo", "endDate": "yesterday"}],
   "dimensions": [{"name": "country"}],
   "metrics": [{"name": "activeUsers"}]
   }
   

   报告结果以JSON格式返回，包含指定维度和指标的数据。

3. 获取维度和指标
   • 使用get_dimensions和get_metrics获取属性的核心维度和指标，包括自定义维度和指标。
   • 使用get_standard_dimensions和get_standard_metrics获取GA4的标准维度和指标列表，适合初次配置报告。
4. 自然语言查询
   MCP支持通过大模型（如Claude）使用自然语言查询数据。例如，输入“过去30天按设备类别比较平均会话时长”：
   • 服务器将请求转换为API调用，生成报告。
   • 返回结果以表格或JSON格式展示，方便理解。

特色功能操作

1. 与大模型集成
   MCP服务器通过本地运行，允许用户将GA4数据与大模型结合。例如，使用Claude或Cursor，输入自然语言指令如“显示过去90天按浏览器分组的页面浏览量”。服务器解析指令，调用GA4 API，返回结构化数据。
2. Google Ads链接管理
   使用list_google_ads_links查询与GA4属性的Google Ads账户链接。返回结果包括链接的账户ID和状态，适合营销人员优化广告投放。
3. 自定义维度和指标
   用户可通过get_dimensions和get_metrics获取自定义维度和指标，创建个性化报告。例如，分析特定事件（如“购买”事件）的触发次数。

注意事项

• 确保服务账户具有Google Analytics Data API和Admin API的权限。
• 检查网络连接，服务器需访问Google API。
• 定期更新仓库代码以获取最新功能：

  git pull origin main
  

应用场景

1. 网站流量分析
   网站管理员使用MCP查询GA4数据，分析过去30天的流量来源、用户行为和转化率，帮助优化网站内容和营销策略。
2. 广告效果评估
   营销团队通过list_google_ads_links和run_report功能，比较不同广告活动的点击率和转化率，调整投放预算。
3. 数据驱动的产品优化
   产品经理使用自然语言查询，分析用户在特定页面上的停留时间和跳出率，优化用户体验。
4. 开发者集成测试
   开发者将MCP服务器集成到数据分析工具中，测试API调用和数据返回，确保系统稳定运行。

QA

1. 如何确保GA4凭据安全？
   将服务账户密钥文件存储在安全位置，避免公开分享。使用环境变量或~/.gemini/settings.json配置凭据，防止泄露。
2. MCP支持哪些大模型？
   支持Claude、Cursor、Gemini CLI等MCP客户端，未来可能扩展更多兼容模型。
3. 报告查询失败怎么办？
   检查服务账户权限、API启用状态和网络连接。确保propertyId正确，日期范围格式为“YYYY-MM-DD”或“7daysAgo”。
4. 如何查看支持的维度和指标？
   使用get_standard_dimensions和get_standard_metrics获取标准列表，或get_dimensions和get_metrics获取属性特定的自定义维度和指标。