AI导哈

GA4自动化服务器

一个基于Model Context Protocol (MCP)的Google Analytics 4自动化服务器，允许AI代理查询GA4数据，包括报告、流量来源、人口统计等。

  • by mattwilkerson1121
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 mattwilkerson1121/ga-ai-mcp-server

使用说明

GA4自动化MCP服务器

这个项目是 谷歌分析4（GA4）自动化服务器 实施为a 模型上下文协议（MCP） 工具。它允许AI代理查询GA4数据 （报告、流量来源、人口统计等），还包括一个简单的 连接测试脚本。

1.先决条件

  • Node.js （推荐：最近的LTS，例如通过 nvm)
  • npm （随Node一起提供）
  • A. GA4物业 您可以访问
  • A. 谷歌云服务帐户 与：
    • 这 分析数据API 启用
    • 访问您的GA4属性（查看器或更高版本）

2.克隆项目并安装依赖项

cd /<path-to-your-projects>/ga4-automation
git clone https://github.com/mattwilkerson1121/ga-ai-mcp-server/ # or copy the folder another way
cd ga4-automation

npm install

（如果仓库已经在磁盘上，只需 cd /<path-to-your-project>/ga4-automation 然后跑 npm install.)

3.创建您的GA4服务帐户密钥

  1. 首选 谷歌云控制台→ IAM和管理员→ 服务帐户.
  2. 创建或选择服务帐户。
  3. 在...之下 钥匙，创建新 JSON 密钥并下载。
  4. 将JSON密钥文件保存到项目根目录中：
/<path-to-project-folder>/ga4-automation/credentials.json
  1. 在GA4中，授予此服务帐户访问您房产的电子邮件权限：
    • 管理员→ 物业出入管理→ 添加用户→ 粘贴服务帐户电子邮件→ 至少给予 观众.

4.配置环境和测试脚本

这 测试脚本 (test-connection.js)使用环境变量（和 .env) 以定位凭据和GA4属性。

创建一个 .env 项目根目录中的文件：

cd /<path-to-project-folder>/ga4-automation
cat > .env << 'EOF'
GOOGLE_APPLICATION_CREDENTIALS=/<path-to-project-folder>/ga4-automation/credentials.json
GA_PROPERTY_ID=<your-ga4-property-id>   # for multiple properties use comma‑separated list of your GA4 property IDs
EOF

关键变量：

  • GOOGLE_APPLICATION_CREDENTIALS：服务帐户JSON的绝对路径。
  • GA_PROPERTY_ID：一个或多个GA4属性ID，用逗号分隔。

运行GA4连接测试

从项目根：

cd /<path-to-project-folder>/ga4-automation
npm run test:connection

预期行为：

  • 对于您配置的每个属性ID，它将：
    • 运行一个小型GA4报告
    • 打印以下指标 activeUsers, sessions, screenPageViews, newUsers
    • 使用有用的提示显示任何权限或配置错误

如果你看到这样的消息：

  • Credentials file not found → check GOOGLE_APPLICATION_CREDENTIALS 以及文件路径。
  • PERMISSION_DENIED → 确保服务帐户可以访问GA4属性。
  • NOT_FOUND → 属性ID可能不正确。

5.MCP服务器概述(src/index.js)

GA4自动化主服务器在 src/index.js 作为一个 主控程序 stdio上的服务器 （不是HTTP服务器）。

  • 它
    • 读取以下位置的凭据文件 credentials.json 在项目根中。
    • 创建一个 GoogleAuth 和 BetaAnalyticsDataClient.
    • 显示几个工具，例如：
      • query_analytics
      • get_realtime_data
      • get_traffic_sources
      • get_user_demographics
      • get_page_performance
      • get_conversion_data
      • get_custom_report
    • 通过stdin/stdout连接到MCP客户端(StdioServerTransport).

您不会通过浏览器访问此服务器或 curl；相反，是一个支持MCP的客户端 （像克劳德桌面）启动并与之对话。

6.手动运行MCP服务器（用于健全性检查）

从项目根：

cd /<path-to-project-folder>/ga4-automation

# Quick syntax check (no execution)
node --check src/index.js

# Start the server (will wait for MCP messages on stdin)
npm start

这 npm start 脚本在中定义 package.json 如：

NODE_OPTIONS='--no-deprecation' node src/index.js

如果你跑 npm start 在普通终端中，它只会等待，因为没有MCP 客户端已连接到其stdin/stdout。这是意料之中的。

7.使用克劳德（MCP）的服务器

此项目已经包含一个示例Claude MCP配置。您需要使用适当的路径更新内容，然后复制json并将其添加到您的Claude Desktop Configuration文件中（您可以在Claude AI Desktop App中找到该文件的路径，方法是转到设置>开发人员>并单击编辑配置按钮）：

claude-config.json:

{
  "mcpServers": {
    "ga4-analytics": {
      "command": "/Users/<your-user-name>/.nvm/versions/node/<your-node-version>/bin/node",
      "args": [
        "/<path-to-project-folder>/ga4-automation/src/index.js"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/<path-to-project-folder>/ga4-automation/credentials.json",
        "GA4_PROPERTY_ID": "<your-ga4-property-id>",
        "NODE_OPTIONS": "--no-deprecation"
      }
    }
  }
}

使用Claude Desktop的步骤

  1. 复制 claude-config.json 将其合并到Claude的MCP配置文件中 位置（因操作系统而异；请参阅Claude文档）。
  2. 全部调整 绝对路径 为了与您的环境相匹配：
    • command （您的节点二进制路径）
    • args[0] （路径到 src/index.js)
    • GOOGLE_APPLICATION_CREDENTIALS
    • GA4_PROPERTY_ID 值
  3. 重新启动Claude Desktop，使其能够启动新的MCP服务器。
  4. 在克劳德，问这样的问题：
    • “使用 ga4-analytics 获取最近7个页面性能数据的工具 天。”
    • “查询分析并向我显示2025年1月1日至2025年31月1日的新用户数量”
    • “在表头创建一个包含指标名称的列的表，并向我显示会话数，new 用户，以及与正确列对应的过去30天内新用户与总用户的百分比。"

克劳德将：

  • 使用生成Node MCP服务器 command/args 从 claude-desktop-config.json.
  • 调用您定义的工具(get_page_performance等等）来运行GA4报告。

8.工具有效载荷示例（概念性）

这些示例展示了 形状 MCP服务器期望的工具输入。这 实际布线由MCP客户端（Claude）处理；你通常会这样做 不 手动发送此JSON，但这应该能让您了解如何在Claude UI中构建提示。

例子： query_analytics

{
  "propertyId": "<your-ga4-property-id>",
  "startDate": "2025-01-01",
  "endDate": "2025-01-31",
  "dimensions": ["country", "city"],
  "metrics": ["sessions", "activeUsers"]
}

例子： get_page_performance

{
  "propertyId": "<your-ga4-property-id>",
  "startDate": "2025-01-01",
  "endDate": "2025-01-31",
  "limit": 50
}

响应被标准化为JSON结构，其中包含：

  • rows：对象数组（维度/度量名称→ 值）
  • rowCount：行数
  • totals：GA4提供的任何总计

9.故障排除

  • node: command not found

    • 安装节点（例如。 brew install node 或 nvm install --lts)并打开a 新航站楼。

  • ENOENT: no such file or directory, open 'credentials.json'

    • 确保在以下位置存在有效的JSON密钥：
      • /<path-to-project-folder>/ga4-automation/credentials.json，或
      • 更新 src/index.js 指向 credentials.json.

  • PERMISSION_DENIED 跑步时 npm run test:connection

    • 确认服务帐户有权访问GA4 Admin中的GA4属性。

  • NOT_FOUND: Property ID

    • 检查拼写错误 GA_PROPERTY_ID / GA4_PROPERTY_ID.

如果您遇到此处未涵盖的错误，请捕获完整的堆栈跟踪，然后 日志来自 npm run test:connection 或MCP客户端并调整凭证， 根据需要使用env变量或GA4访问。

如果您不断遇到错误，可能需要清除 克劳德桌面应用程序。

相关 MCP