AI导哈

数据分析服务

一个提供Google Analytics数据API访问的Python实现，允许检索报告、实时数据和元数据。

  • by GunnarGriese
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 gunnargriese/mcp-server-google-analytics

使用说明

谷歌分析MCP服务器（Python）

模型上下文协议（MCP）服务器，提供对Google Analytics Data API的访问。此Python实现允许LLM从Google Analytics 4属性中检索报告、实时数据和元数据。

特性

  • 获取报告：根据指定的日期范围、指标和维度检索报告
  • 获取高度数据：获取实时分析数据
  • 元数据资源：访问Google Analytics属性的元数据，包括可用指标和维度

先决条件

  1. 谷歌云项目：创建谷歌云项目并启用分析数据API
  2. 服务帐户：创建服务帐户并下载凭据JSON文件
  3. GA4访问：授予服务帐户对GA4属性的适当访问权限

有关详细的设置说明，请参阅 Google Analytics Data API文档.

安装

选项1：使用pip（推荐）

pip install mcp-server-google-analytics

选项2：来源

# Clone the repository
git clone https://github.com/GunnarGriese/mcp-server-google-analytics.git
cd mcp-server-google-analytics

# Install dependencies
pip install -e .

配置

设置以下环境变量：

export GOOGLE_CLIENT_EMAIL="your-service-account@project.iam.gserviceaccount.com"
export GOOGLE_PRIVATE_KEY="your-private-key"
export GA_PROPERTY_ID="your-ga4-property-id"

查找配置值

  1. 谷歌客户端电子邮件：在您的服务帐户JSON文件中找到 client_email
  2. GOOGLE_PRIVATE_KEY：在您的服务帐户JSON文件中找到 private_key
  3. GA属性ID：您的GA4属性ID（数字，例如“123456789”）

用法

运行服务器

# Using the installed script
mcp-server-google-analytics

# Or directly with Python
python -m mcp_server_google_analytics.server

Claude桌面集成

将以下内容添加到您的Claude Desktop配置文件中：

{
  "mcpServers": {
    "google-analytics": {
      "command": "python",
      "args": ["-m", "mcp_server_google_analytics.server"],
      "env": {
        "GOOGLE_CLIENT_EMAIL": "your-service-account@project.iam.gserviceaccount.com",
        "GOOGLE_PRIVATE_KEY": "your-private-key",
        "GA_PROPERTY_ID": "your-ga4-property-id"
      }
    }
  }
}

替代方案：使用pip安装的脚本

{
  "mcpServers": {
    "google-analytics": {
      "command": "mcp-server-google-analytics",
      "env": {
        "GOOGLE_CLIENT_EMAIL": "your-service-account@project.iam.gserviceaccount.com",
        "GOOGLE_PRIVATE_KEY": "your-private-key",
        "GA_PROPERTY_ID": "your-ga4-property-id"
      }
    }
  }
}

例子

获取报告

使用 get_report 检索分析数据的工具：

# Example arguments:
{
  "start_date": "7daysAgo",
  "end_date": "today",
  "metrics": ["activeUsers", "screenPageViews"],
  "dimensions": ["date"],
  "limit": 10
}

获取实时数据

使用 get_realtime_data 获取当前活跃用户的工具：

# Example arguments:
{
  "metrics": ["activeUsers"],
  "dimensions": ["deviceCategory"],
  "limit": 10
}

访问元数据

访问 ga4://property/123456789/metadata 或 ga4://default/metadata 查看可用指标和维度的资源。

支持的日期格式

  • 绝对日期： "2024-01-01"
  • 相对日期： "today", "yesterday"
  • 几天前： "7daysAgo", "30daysAgo"
  • 几个月前： "1monthAgo", "2monthsAgo"

通用度量和维度

热门指标

  • activeUsers -不同用户的数量
  • screenPageViews -页面/屏幕浏览次数
  • sessions -会话数
  • bounceRate -跳出率百分比
  • averageSessionDuration -平均会话持续时间

流行尺寸

  • date -会议日期
  • country -原产国
  • city -起源城市
  • deviceCategory -设备类别（台式机、移动设备、平板电脑）
  • browser -使用的浏览器
  • operatingSystem -操作系统

错误处理

该服务器包括全面的错误处理功能，用于：

  • 缺少环境变量
  • 无效的Google API凭据
  • API费率限制和配额
  • 属性ID无效
  • 请求格式错误

发展

为发展而设立

# Clone the repository
git clone https://github.com/your-username/mcp-server-google-analytics-python.git
cd mcp-server-google-analytics-python

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

故障排除

身份验证问题

  1. 验证您的服务帐户是否具有正确的权限
  2. 检查分析数据API是否已在您的谷歌云项目中启用
  3. 确保您的私钥格式正确（换行符应为 \n)

物业准入问题

  1. 确认您的服务帐户已添加到GA4属性中
  2. 验证属性ID是否正确（数字格式）
  3. 检查该属性是否具有所请求日期范围的数据

常见错误消息

  • "Google Analytics client not initialized"：检查环境变量
  • "No property ID provided"：设置GA_PROPERTY_ID环境变量
  • "Google API error"：检查API凭据和权限

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

贡献

请随时提交拉取请求。

支持

如果您遇到任何问题或有疑问，请在GitHub存储库上提交问题。

相关 MCP