🚀 Google Analytics 4 的 MCP 服务器

本项目是 Google Analytics 4 的 MCP 服务器，为用户提供丰富的 MCP 功能，涵盖数据获取、资源管理和数据分析等方面，助力用户高效利用 GA4 数据。

🚀 快速开始

此为一个正在进行中的项目。服务器尚未完全测试完毕，请谨慎使用。

✨ 主要特性

此服务器提供以下 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

💻 使用示例

资源路径示例

• ga4://property-info：获取 GA4 属性的元数据，包括可用维度、指标和比较项。
• ga4://dimensions：列出 GA4 的所有可用维度。
• ga4://metrics：列出 GA4 的所有可用指标。

提示功能示例

• analyze-data：帮助分析数据并提供见解。
• create-report：生成自定义报告模板。
• select-dimensions：根据目标选择最合适的维度。

🔧 技术细节

故障排除

• 认证错误：检查服务账户密钥和权限。
• 无数据显示：确认日期范围和属性 ID 是否正确。
• 连接错误：检查网络设置和防火墙配置。

测试

使用 MCP 检查器测试：

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
  • 此项目借鉴了该仓库的类结构实现。
• https://github.com/ruchernchong/mcp-server-google-analytics
  • 基于 Google Analytics API 的基本实现。