关键词

Google Analytics 4GA4网站分析数据分析营销分析

GA4数据MCP服务器

项目简介

本项目是一个MCP（Model Context Protocol）服务器，专门为需要访问Google Analytics 4 (GA4) 数据的LLM应用而设计。它允许LLM客户端通过标准化的MCP协议，安全、便捷地获取GA4的各种指标、维度和元数据，并利用预设的分析工具和Prompt模板，实现更智能的数据分析和报告生成。

主要功能点

  • 数据访问工具 (Tools):
    • 'get-page-views': 获取页面浏览量指标，可按日期范围和维度筛选。
    • 'get-active-users': 获取活跃用户数指标，可按日期范围筛选。
    • 'get-events': 获取事件指标，可按日期范围和事件名称筛选。
    • 'get-user-behavior': 获取用户行为指标（如会话时长、跳出率），可按日期范围筛选。
    • 'get-source-media': 获取来源/媒介数据，可按日期范围筛选。
  • 数据资源 (Resources):
    • 'ga4://property-info': 提供GA4属性的元数据，包括可用的维度、指标和比较。
    • 'ga4://dimensions': 列出所有可用的GA4维度及其描述。
    • 'ga4://metrics': 列出所有可用的GA4指标及其描述。
    • 'ga4://filters-help': 提供GA4数据过滤语法的帮助文档。
  • Prompt 模板 (Prompts):
    • 'analyze-data': 数据分析助手，引导LLM分析指定GA4指标。
    • 'create-report': 报告生成模板，帮助LLM生成结构化的GA4报告。
    • 'select-dimensions': 维度选择助手，辅助LLM根据分析目标选择合适的GA4维度。

安装步骤

  1. 克隆仓库 
    git clone https://github.com/HosakaKeigo/mcp-server-ga4.git
cd mcp-server-ga4
  2. 安装依赖 确保已安装 Node.js (>= 20) 和 pnpm。然后运行： 
    pnpm install
  3. 配置环境变量 复制 '.env.example' 文件并重命名为 '.env'，然后根据你的Google Cloud Service Account 和 GA4 属性信息修改 '.env' 文件： 
    GOOGLE_CLIENT_EMAIL=你的服务账号邮件地址
GOOGLE_PRIVATE_KEY=你的私钥 (注意处理换行符，参考 .env.example 注释)
GA_PROPERTY_ID=你的GA4属性ID
  4. 构建项目 
    pnpm run build

服务器配置

要将此MCP服务器与MCP客户端（例如 Claude for Desktop）集成，你需要在客户端的配置文件中添加服务器信息。以 'claude_desktop_config.json' 为例，配置如下：

{
  "mcpServers": {
    "ga4": {  // 服务器名称，客户端用以识别
      "command": "node", // 启动服务器的命令
      "args": ["/path/to/mcp-server-ga4/dist/index.js"], // 启动命令的参数，指向服务器入口文件
      "env": { // 环境变量，传递GA4认证信息
        "GOOGLE_CLIENT_EMAIL": "你的服务账号邮件地址", // 你的服务账号邮件地址
        "GOOGLE_PRIVATE_KEY": "你的私钥", // 你的私钥
        "GA_PROPERTY_ID": "你的GA4属性ID"  // 你的GA4属性ID
      }
    }
  }
}

注意:

  • 请将 '/path/to/mcp-server-ga4/dist/index.js' 替换为你的 'mcp-server-ga4' 项目 'dist/index.js' 文件的实际路径。
  • 上述 'env' 中的环境变量需要与你 '.env' 文件中配置的保持一致。

基本使用方法

  1. 启动服务器

    pnpm start

    服务器成功启动后，会显示 "mcp-server-ga4 connected and ready" 的信息。

  2. 在MCP客户端中使用 配置完成后，你的MCP客户端应该能够检测到名为 'ga4' 的MCP服务器。

    • 使用 Tools: 客户端可以调用 'get-page-views', 'get-active-users' 等工具，并根据工具的参数描述传递日期范围、维度、过滤器等参数，获取GA4数据。
    • 访问 Resources: 客户端可以请求访问 'ga4://property-info', 'ga4://dimensions' 等资源，获取GA4元数据或帮助文档。
    • 调用 Prompts: 客户端可以调用 'analyze-data', 'create-report' 等 Prompt，并根据 Prompt 的参数描述传递相关信息，以生成分析或报告指令。

    具体使用方法请参考你的MCP客户端的文档。例如，在 Claude for Desktop 中，你可以在对话框中使用 '@ga4:工具名 参数' 的形式调用工具，或使用 '@ga4:资源URI' 访问资源，或使用 '@ga4:prompt名 参数' 调用 Prompt。

过滤器和分页

  • 过滤器 (Filter): 大多数工具都支持 'filter' 参数，允许你根据维度和指标对GA4数据进行筛选。具体过滤器语法请参考 'ga4://filters-help' 资源。
  • 分页 (Pagination): 当处理大量数据时，可以使用 'limit' 和 'offset' 参数进行分页。'limit' 参数限制每次返回的最大行数，'offset' 参数指定起始行数。

测试

可以使用 MCP Inspector 工具测试服务器功能：

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

信息

分类

商业系统

访问项目