用于 Google Analytics 4 的 MCP 服务器

[!NOTE] 这是一个正在进行中的项目。该服务器尚未经过全面测试。请自行决定是否使用。

主要特性

此服务器提供以下 MCP 功能：

工具

• get-page-views: 获取指定日期范围内的页面浏览量指标。
• get-active-users: 获取指定日期范围内的活跃用户指标。
• get-events: 获取指定日期范围内的事件指标。
• get-user-behavior: 获取用户行为指标，例如会话持续时间和跳出率。

资源

• ga4://property-info: GA4 媒体资源的元数据，包括可用的维度、指标和比较。

以下是更轻量级的资源。

• ga4://dimensions: 可用的 GA4 维度列表。
• ga4://filters-help: 关于使用 GA4 过滤器的帮助文档。
• ga4://metrics: 可用的 GA4 指标列表。

提示词

• analyze-data: 数据分析助手。
• create-report: 报告生成模板。
• select-dimensions: 协助选择适合分析目标的维度。

设置

前提条件

• 一个 Google Analytics 4 媒体资源。
• 一个具有 GA4 API 访问权限的 Google Cloud 服务帐户。
• Node.js 20 或更高版本。
• pnpm 包管理器。

安装

# 克隆存储库
git clone https://github.com/yourusername/mcp-server-ga4.git
cd mcp-server-ga4

# 使用 pnpm 安装依赖项
pnpm install

# 创建 .env 文件
cp .env.example .env

# 编辑 .env 文件并设置您的凭据
# GOOGLE_CLIENT_EMAIL=your-service-account-email@example.iam.gserviceaccount.com
# GOOGLE_PRIVATE_KEY=your-private-key
# GA_PROPERTY_ID=your-ga4-property-id

身份验证

如果设置了 GOOGLE_CLIENT_EMAIL 和 GOOGLE_PRIVATE_KEY，服务器将使用服务帐户进行身份验证。 如果未设置，它将使用默认凭据。

确保您的项目启用了 Google Analytics API 并且您的服务帐户具有必要的权限。（https://www.googleapis.com/auth/analytics.readonly）

以下是如何设置 Google 应用程序默认凭据：

1. 安装 Google Cloud SDK。
2. 运行以下命令进行身份验证：

gcloud auth application-default login --scopes=openid,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly

# 如果您想设置配额项目
gcloud auth application-default set-quota-project <my-quota-project>

构建和运行

# 构建服务器
pnpm run build

# 运行服务器
pnpm start

用法

与 Claude for Desktop 集成

将以下内容添加到您的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "ga4": {
      "command": "node",
      "args": ["/path/to/mcp-server-ga4/dist/index.js"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_CLIENT_EMAIL": "your-service-account-email@example.iam.gserviceaccount.com",
        "GOOGLE_PRIVATE_KEY": "your-private-key",
        "GA_PROPERTY_ID": "your-ga4-property-id"
      }
    }
  }
}

如果您想使用默认凭据，请在您的环境中设置 GOOGLE_APPLICATION_CREDENTIALS：

{
  "mcpServers": {
    "ga4": {
      "command": "node",
      "args": ["/path/to/mcp-server-ga4/dist/index.js"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GA_PROPERTY_ID": "your-ga4-property-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/credentials.json"
      }
    }
  }
}

过滤

您可以将 filter 参数与所有工具一起使用来缩小结果范围：

{
  "dimension": [
    {
      "name": "pagePath",
      "stringEquals": "/blog/article-1"
    }
  ],
  "metric": [
    {
      "name": "screenPageViews",
      "greaterThan": 100
    }
  ],
  "operator": "AND"
}

分页

在处理大量数据时，请使用 limit 和 offset 参数：

// 第一页（项目 1-50）
get-page-views with limit=50, offset=0

// 第二页（项目 51-100）
get-page-views with limit=50, offset=50

故障排除

• 身份验证错误：检查您的服务帐户密钥和权限。
• 没有数据显示：验证日期范围和媒体资源 ID 是否正确。
• 连接错误：检查您的网络设置和防火墙。

测试

使用 MCP Inspector 进行测试：

pnpm dlx @modelcontextprotocol/inspector node /path/to/mcp-server-ga4/dist/index.js

(注意：pnpm dlx 相当于 npx，用于执行包)

许可证

MIT

感谢

• https://github.com/lapras-inc/lapras-mcp-server/tree/main
  • 归功于 mcp 实现的基于类的结构。
• https://github.com/ruchernchong/mcp-server-google-analytics
  • 依赖于 Google Analytics API 的基本实现。