针对 Google Analytics 4 的 MCP 服务器

这是一个模型上下文协议（MCP）服务器，允许大型语言模型（LLMs）通过 Google Analytics Data API 与 Google Analytics 4（GA4）数据进行交互。

特性

• 运行标准的 GA4 报告，具有可定制的维度、指标和日期范围
• 获取过去 30 分钟内的实时数据
• 检索有关可用指标和维度的元数据
• 使用 Google Cloud 的应用默认凭据进行安全认证
• 可配置以方便通过 Smithery 部署

安装

使用 pip

pip install mcp-server-ga4

从源代码安装

git clone https://github.com/yourusername/mcp-server-ga4.git
cd mcp-server-ga4
pip install -e .

认证

此服务器使用 Google Cloud 的应用默认凭据（ADC）进行认证。在使用服务器之前，您需要：

1. 创建一个 Google Cloud 项目
2. 启用 Google Analytics Data API
3. 设置认证：

gcloud auth application-default login

更多详情，请参阅 Google Cloud 认证文档。

使用方法

命令行

使用您的 GA4 属性 ID 启动服务器：

mcp-server-ga4 --property-id YOUR_GA4_PROPERTY_ID

服务器将默认使用标准 MCP 标准 I/O 传输。

环境变量

您也可以通过环境变量设置配置：

• GA4_PROPERTY_ID：您的 Google Analytics 4 属性 ID

与 Claude Desktop 结合使用

1. 全局安装服务器：pip install mcp-server-ga4
2. 设置您的 Google Cloud 认证：gcloud auth application-default login
3. 编辑您的 Claude Desktop 配置：

{
    "mcpServers": {
        "ga4": {
            "command": "mcp-server-ga4",
            "args": ["--property-id", "YOUR_GA4_PROPERTY_ID"]
        }
    }
}

可用工具

run-report

运行一个标准的 GA4 报告，具有可配置的指标、维度和日期范围。

参数：

• property_id（可选）：GA4 属性 ID（覆盖默认值）
• metrics：指标名称列表（例如，["activeUsers", "sessions"]）
• dimensions（可选）：维度名称列表（例如，["date", "country"]）
• date_range：日期范围，格式如下之一：
  • {"start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD"}
  • "last7days", "last30days", "today", "yesterday"
• limit（可选）：返回的行数（默认：110）

run-realtime-report

获取过去 30 分钟内的实时数据。

参数：

• property_id（可选）：GA4 属性 ID（覆盖默认值）
• metrics：指标名称列表（例如，["activeUsers", "screenPageViews"]）
• dimensions（可选）：维度名称列表（例如，["country", "city"]）
• limit（可选）：返回的行数（默认：10）

get-metadata

检索 GA4 属性的可用指标和维度。

参数：

• property_id（可选）：GA4 属性 ID（覆盖默认值）
• type（可选）：要检索的元数据类型（"metrics", "dimensions", 或 "all"，默认："all"）

示例

运行标准报告

过去 30 天内活跃用户最多的前 5 个国家是哪些？

查看实时数据

目前有多少用户正在访问网站？

获取元数据信息

我可以查询 GA4 中有哪些指标？

开发

1. 克隆仓库
2. 安装开发依赖项：pip install -e ".[dev]"
3. 运行测试：pytest

许可证

MIT