MCP Google Analytics Oauth2

谷歌分析MCP服务器

模型上下文协议（MCP）服务器，通过标准MCP接口提供对Google Analytics 4数据的无缝访问。该工具允许LLM应用程序轻松查询和分析Google Analytics数据，而无需直接处理Google Analytics data API的复杂性。

✨ 特性

• 🔐 双重认证：支持服务帐户和OAuth2用户授权
• 实时数据访问：获取当前活跃用户和活动的实时分析数据
• 自定义报告：创建具有自定义维度和指标的综合报告
• 快速洞察：常见用例的预定义分析见解
• 元数据发现：获取您的Google Analytics属性的可用维度和指标
• 🔄 自动令牌刷新：自动刷新过期的OAuth2访问令牌
• 智能错误处理：详细的错误消息，其中包含权限问题的可操作解决方案
• 标准MCP接口：适用于任何兼容MCP的客户端

安装

npm install @toolsdk.ai/google-analytics-mcp

先决条件

• Node.js>=18.0.0
• 谷歌分析4属性
• 要么：

- 服务帐户 凭据（默认），或 - OAuth2令牌 来自用户授权流

🔐 身份验证模式

此MCP服务器支持两种身份验证模式，由 GOOGLE_AUTH_MODE 环境变量：

______________________________________________________________________

模式1：服务帐户（默认）

使用此模式进行服务器到服务器的身份验证，无需用户交互。

设置步骤

1. 创建服务帐户 在谷歌云控制台中
2. 下载JSON密钥 文件
3. 授予访问权限 前往您的GA4房产：

- 转到谷歌分析→ 管理员→ 物业出入管理 - 添加服务帐户电子邮件（例如。， xxx@project.iam.gserviceaccount.com)与 观众 访问

环境变量

# Optional: defaults to 'service_account'
GOOGLE_AUTH_MODE=service_account

# Option 1: Direct JSON string
GOOGLE_CREDENTIALS='{"type":"service_account","project_id":"...","private_key":"...","client_email":"..."}'

# Option 2: Path to JSON file
GOOGLE_CREDENTIALS_PATH=/path/to/service-account.json

Claude桌面配置

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "npx",
      "args": ["-y", "@toolsdk.ai/google-analytics-mcp"],
      "env": {
        "GOOGLE_AUTH_MODE": "service_account",
        "GOOGLE_CREDENTIALS_PATH": "/path/to/service-account.json"
      }
    }
  }
}

______________________________________________________________________

模式2:OAuth2用户授权

使用此模式代表具有自己权限的用户访问GA数据。

优势

• ✅ 无需设置服务帐户即可访问用户自己的GA属性
• ✅ 无需将服务帐户添加到GA属性权限
• ✅ 使用用户现有的Google帐户权限

⚠️ 重要：此MCP服务器 非 包括OAuth2授权流本身。您需要单独实现OAuth2同意流以获取令牌。

1.实施OAuth2授权流（您的责任）

您需要使用以下库来实现OAuth2授权流：

• googleapis （Node.js）
• google-auth-library （Node.js）

所需的OAuth2作用域：

https://www.googleapis.com/auth/analytics.readonly

OAuth2流示例（简化）：

import { google } from 'googleapis';

const oauth2Client = new google.auth.OAuth2(
  CLIENT_ID,
  CLIENT_SECRET,
  REDIRECT_URI
);

// Generate auth URL and redirect user
const authUrl = oauth2Client.generateAuthUrl({
  access_type: 'offline',  // Important: to get refresh_token
  scope: ['https://www.googleapis.com/auth/analytics.readonly']
});

// After user consent, exchange code for tokens
const { tokens } = await oauth2Client.getToken(code);

// Save tokens to tokens.json
fs.writeFileSync('tokens.json', JSON.stringify(tokens, null, 2));

2.tokens.json格式

完成OAuth2流后，将令牌保存在 tokens.json 文件：

{
  "access_token": "ya29.a0AWY7CknXXX...",
  "refresh_token": "1//0eXXX...",
  "scope": "https://www.googleapis.com/auth/analytics.readonly",
  "token_type": "Bearer",
  "expiry_date": 1234567890000
}

3.令牌加载优先级

MCP服务器按以下顺序加载OAuth2令牌：

1. 直接JSON字符串 通过 GOOGLE_OAUTH2_TOKENS 环境变量
2. 指定的路径 GOOGLE_OAUTH2_TOKEN_PATH 环境变量
3. {current working directory}/tokens.json
4. {current working directory}/../tokens.json
5. {src directory}/../../tokens.json

4.环境变量（OAuth2模式）

GOOGLE_AUTH_MODE=oauth2

# Option 1: Direct JSON string
GOOGLE_OAUTH2_TOKENS='{"access_token":"ya29...","refresh_token":"1//0e...","expiry_date":1234567890000}'

# Option 2: Path to tokens.json
GOOGLE_OAUTH2_TOKEN_PATH=/path/to/your/tokens.json

# Optional: For automatic token refresh
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Claude桌面配置（OAuth2）

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "npx",
      "args": ["-y", "@toolsdk.ai/google-analytics-mcp"],
      "env": {
        "GOOGLE_AUTH_MODE": "oauth2",
        "GOOGLE_OAUTH2_TOKEN_PATH": "/path/to/your/tokens.json",
        "GOOGLE_CLIENT_ID": "your-client-id (optional)",
        "GOOGLE_CLIENT_SECRET": "your-client-secret (optional)"
      }
    }
  }
}

______________________________________________________________________

⚠️ 令牌生命周期管理（OAuth2模式）

访问令牌过期

• Google OAuth2访问令牌通常在以下时间到期 1小时
• 如果发生以下情况，MCP服务器将自动尝试刷新令牌 refresh_token 被提供

自动令牌刷新

当配置为 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET，服务器将：

1. 检测访问令牌何时过期
2. 使用 refresh_token 获取新的 access_token
3. 自动保存 新代币 tokens.json

刷新令牌注意事项

⚠️ 关于刷新令牌的重要说明：

1. 刷新令牌可能会过期或被撤销：

- 如果用户在其Google帐户设置中撤销访问权限 - 如果刷新令牌未使用6个月（对于未验证的应用程序） - 如果您已超过每个客户端每个用户100个刷新令牌的限制

1. 获取刷新令牌：

- 你只能得到一个 refresh_token 在 第一 授权 - 使用 access_type: 'offline' 在您的身份验证URL中 - 使用 prompt: 'consent' 强制重新同意并获取新的刷新令牌

1. 推荐做法：

- 始终请求 access_type: 'offline' 在OAuth2流期间 - 储存和保护 refresh_token 安全地 - 当刷新令牌失效时，实施重新授权流程 - 监视器 invalid_grant 指示刷新令牌不再有效的错误

______________________________________________________________________

可用工具

analytics_report

使用自定义维度和指标获取全面的Google Analytics数据。可以创建任何类型的报告。

参数：

• propertyId （字符串，必填）：谷歌分析属性ID
• startDate （字符串，必填）：开始日期（YYYY-MM-DD）
• endDate （字符串，必填）：结束日期（YYYY-MM-DD）
• dimensions （数组，可选）：要查询的维度
• metrics （数组，必填）：要查询的指标
• dimensionFilter （对象，可选）：按维度值过滤
• metricFilter （对象，可选）：按度量值过滤
• orderBy （对象，可选）：按维度或度量对结果进行排序
• limit （数字，可选）：限制结果数量（默认值：100）

realtime_data

获取当前活跃用户和活动的实时分析数据。

参数：

• propertyId （字符串，必填）：谷歌分析属性ID
• dimensions （数组，可选）：实时数据的维度
• metrics （数组，可选）：实时指标（默认值：\['activeUsers'\]）
• limit （数字，可选）：限制结果数量（默认值：50）

quick_insights

获取常见用例的预定义分析见解。

参数：

• propertyId （字符串，必填）：谷歌分析属性ID
• startDate （字符串，必填）：开始日期（YYYY-MM-DD）
• endDate （字符串，必填）：结束日期（YYYY-MM-DD）
• reportType （字符串，必填）：快速洞察报告的类型（概述、top_pages、traffic_source等）
• limit （数字，可选）：限制结果数量（默认值：20）

get_metadata

获取Google Analytics属性的可用维度和指标。

参数：

• propertyId （字符串，必填）：谷歌分析属性ID
• type （字符串，可选）：要检索的元数据类型（维度、指标，两者都有）

search_metadata

按名称或类别搜索特定维度或指标。

参数：

• propertyId （字符串，必填）：谷歌分析属性ID
• query （字符串，必填）：用于查找维度/指标的搜索词
• type （字符串，可选）：要搜索的元数据类型（维度、指标，两者都有）
• category （字符串，可选）：按类别筛选

错误处理

服务器根据身份验证模式提供详细的错误消息和可操作的解决方案：

服务帐户模式：

• 权限错误将提示您将服务帐户电子邮件添加到GA属性访问

OAuth2模式：

• 权限错误将建议重新授权
• 令牌错误将指示需要刷新或重新授权

环境变量摘要

贡献

欢迎投稿！请随时提交拉取请求。

许可证

麻省理工学院