GA4自动化MCP服务器
这个项目是 谷歌分析4（GA4）自动化服务器 实施为a 模型上下文协议（MCP） 工具。它允许AI代理查询GA4数据 （报告、流量来源、人口统计等），还包括一个简单的 连接测试脚本。
______________________________________________________________________
1.先决条件
- Node.js （推荐：最近的LTS，例如通过
nvm) - npm （随Node一起提供）
- A. GA4物业 您可以访问
- A. 谷歌云服务帐户 与：
- 这 分析数据API 启用 - 访问您的GA4属性（查看器或更高版本）
______________________________________________________________________
2.克隆项目并安装依赖项
cd /
/ga4-automation
git clone https://github.com/mattwilkerson1121/ga-ai-mcp-server/ # or copy the folder another way
cd ga4-automation
npm install*（如果仓库已经在磁盘上，只需 cd / /ga4-automation 然后跑 npm install.)*
______________________________________________________________________
3.创建您的GA4服务帐户密钥
- 首选 谷歌云控制台→ IAM和管理员→ 服务帐户.
- 创建或选择服务帐户。
- 在...之下 钥匙，创建新 JSON 密钥并下载。
- 将JSON密钥文件保存到项目根目录中：
/
/ga4-automation/credentials.json- 在GA4中，授予此服务帐户访问您房产的电子邮件权限：
- 管理员→ 物业出入管理→ 添加用户→ 粘贴服务帐户电子邮件→ 至少给予 观众.
______________________________________________________________________
4.配置环境和测试脚本
这 测试脚本 (test-connection.js)使用环境变量（和 .env) 以定位凭据和GA4属性。
创建一个 .env 项目根目录中的文件：
cd /
/ga4-automation
cat > .env # for multiple properties use comma‑separated list of your GA4 property IDs
EOF关键变量：
GOOGLE_APPLICATION_CREDENTIALS：服务帐户JSON的绝对路径。GA_PROPERTY_ID：一个或多个GA4属性ID，用逗号分隔。
运行GA4连接测试
从项目根：
cd /
/ga4-automation
npm run test:connection预期行为：
- 对于您配置的每个属性ID，它将：
- 运行一个小型GA4报告 - 打印以下指标 activeUsers, sessions, screenPageViews, newUsers - 使用有用的提示显示任何权限或配置错误
如果你看到这样的消息：
Credentials file not found→ checkGOOGLE_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 /
/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//.nvm/versions/node//bin/node",
"args": [
"/
/ga4-automation/src/index.js"
],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/
/ga4-automation/credentials.json",
"GA4_PROPERTY_ID": "",
"NODE_OPTIONS": "--no-deprecation"
}
}
}
}使用Claude Desktop的步骤
- 复制
claude-config.json将其合并到Claude的MCP配置文件中
位置（因操作系统而异；请参阅Claude文档）。
- 全部调整 绝对路径 为了与您的环境相匹配：
- command （您的节点二进制路径） - args[0] （路径到 src/index.js) - GOOGLE_APPLICATION_CREDENTIALS - GA4_PROPERTY_ID 值
- 重新启动Claude Desktop，使其能够启动新的MCP服务器。
- 在克劳德，问这样的问题：
- “使用 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": "",
"startDate": "2025-01-01",
"endDate": "2025-01-31",
"dimensions": ["country", "city"],
"metrics": ["sessions", "activeUsers"]
}例子： get_page_performance
{
"propertyId": "",
"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密钥： - / /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访问。
如果您不断遇到错误，可能需要清除 克劳德桌面应用程序。