Google Analytics MCP 服务器

这是一个使用模型上下文协议（Model Context Protocol）TypeScript SDK 实现的 MCP 服务器，用于访问 Google Analytics 4 (GA4) 数据。

特性

• 获取可自定义维度的页面浏览指标
• 跟踪活跃用户和新用户的趋势
• 分析特定事件及其指标
• 监控用户行为指标（会话时长、跳出率）
• 所有查询均可灵活选择日期范围

预备条件

• Node.js 20 或更高版本
• 一个 Google Analytics 4 属性
• 启用了 Analytics Data API 的 Google Cloud 项目
• 具有访问 API 凭证的服务账户

设置与配置

要使用此服务器，您需要通过服务账户进行 Google Analytics 认证。

1. 启用 Google Analytics Data API

1. 前往 Google Cloud 控制台。
2. 选择您要使用的项目。
3. 在导航菜单中，前往 APIs & Services > Library。
4. 搜索 "Google Analytics Data API" 并启用它。

2. 创建服务账户

1. 在 Google Cloud 控制台中，导航到 IAM & Admin > Service Accounts。
2. 点击 "创建服务账户"。
3. 给服务账户命名（例如："GA4 MCP 服务器"）。
4. 点击 "创建并继续"。
5. 可以跳过授予服务账户对项目的访问权限。
6. 点击 "完成"。
7. 查找您刚刚创建的服务账户，并点击 "操作" 下的三个点。
8. 选择 "管理密钥"，然后 "添加密钥" > "创建新密钥"。
9. 选择 JSON 作为密钥类型并点击 "创建"。将下载包含凭证的 JSON 文件。

3. 授予服务账户访问 Google Analytics 的权限

1. 打开 Google Analytics。
2. 导航到您的 GA4 属性的 管理 部分。
3. 在 属性 列下，点击 属性访问管理。
4. 点击 "+" 按钮添加新用户。
5. 在 "电子邮件地址" 字段中，粘贴您下载的 JSON 凭证文件中的 client_email。
6. 分配 "查看者" 角色。无需通知用户。
7. 点击 "添加"。

4. 设置环境变量

服务器需要以下环境变量：

• GOOGLE_CLIENT_EMAIL：来自您的服务账户 JSON 文件的 client_email。
• GOOGLE_PRIVATE_KEY：来自您的服务账户 JSON 文件的 private_key。
• GA_PROPERTY_ID：您的 Google Analytics 4 属性 ID。

您可以在环境中设置它们，或使用 .env 文件。

export GOOGLE_CLIENT_EMAIL="your-service-account@your-project.iam.gserviceaccount.com"
export GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n"
export GA_PROPERTY_ID="your_property_id"

安装

通过 Smithery 安装

要通过 Smithery 自动安装 Google Analytics 服务器：

npx -y @smithery/cli install mcp-server-google-analytics --client claude

手动安装

npm install -g mcp-server-google-analytics

或者直接使用 npx：

npx mcp-server-google-analytics

使用方法

启动服务器

pnpm start

在 Claude Desktop 中配置

在您的 Claude Desktop 配置中添加以下内容：

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "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"
      }
    }
  }
}

可用函数

runReport

运行灵活的报告以获取分析数据。

输入：

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "dimensions": [{ "name": "country" }, { "name": "city" }],
  "metrics": [{ "name": "activeUsers" }, { "name": "newUsers" }],
  "dimensionFilter": {
    "filter": {
      "fieldName": "country",
      "stringFilter": {
        "value": "United States"
      }
    }
  }
}

getPageViews

获取特定日期范围内的页面浏览指标：

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "dimensions": ["page", "country"] // 可选
}

getActiveUsers

获取活跃用户指标：

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31"
}

getEvents

获取事件指标：

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "eventName": "purchase" // 可选
}

getUserBehavior

获取用户行为指标：

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31"
}

安全注意事项

• 最小权限原则：仅授予服务账户在 Google Analytics 中的 "查看者" 角色。
• 密钥管理：确保服务账户密钥文件的安全，不要在客户端代码中暴露它。
• 环境变量：使用环境变量存储敏感信息，如客户端电子邮件、私钥和属性 ID。

贡献

欢迎贡献！请参阅我们的 贡献指南，了解我们的行为准则以及提交拉取请求的过程。

许可证

本项目采用 MIT 许可证 - 详情见 LICENSE 文件。