使用说明

用于谷歌分析的MCP服务器

生产准备就绪 模型上下文协议（MCP）服务器 它为AI代理和语言模型提供对Google Analytics 4（GA4）数据的安全、标准化访问。采用TypeScript构建，专为企业级可靠性和安全性而设计。

特性

全面分析访问：检索页面浏览量、活动用户、事件和用户行为指标
HTTP传输：完全基于HTTP的MCP实现，具有会话管理功能
灵活的身份验证：可配置的身份验证模式（无/JWT/OAuth 2.1）
企业安全：与Auth0集成的符合OAuth 2.1的身份验证
Docker就绪：通过多阶段构建实现生产优化的集装箱化
类型安全：带Zod模式验证的完整TypeScript实现
模块化架构：干净、可维护的代码库，关注点明确分离
提示和资源：暴露 prompts/list + prompts/get 和 resources/* 为了获得更好的LLM用户体验
进度和取消：发送进度通知并接受取消请求

建筑

服务器遵循模块化架构，关注点明确分离：

src/
├── index.ts              # Application entry point
├── config/               # Configuration management
│   └── index.ts         # Environment variable loading and validation
├── lib/                 # Core application logic
│   └── server.ts        # MCP server implementation and tool definitions
├── middleware/          # Authentication middleware
│   └── auth.ts          # JWT-based authentication with Auth0
├── schemas/             # Data validation schemas
│   └── index.ts         # Zod schemas for input validation
└── utils/               # Utility functions
    ├── index.ts         # Helper functions for validation and formatting
    └── logger.ts        # Winston logger configuration

先决条件

Node.js：版本20或更高
谷歌分析4：活性GA4物业
谷歌云项目：启用了分析数据API
服务帐户：具有适当的GA4权限
Auth0帐户：（可选）用于JWT身份验证

谷歌云身份验证

身份验证体系结构

此MCP服务器实现了两个不同的身份验证层：

MCP传输认证 （可选）：控制MCP客户端和此服务器之间的访问
- 通过配置 MCP_AUTH_MODE （无/jwt/outh）
- 当设置为 none，不需要客户端身份验证
Google Analytics API验证 （必填）：控制此服务器对Google Analytics的访问
- 无论MCP身份验证模式如何，始终需要
- 使用Google Cloud服务帐户凭据
- 无法绕过或禁用

所需的Google Cloud控制台设置

即使有 MCP_AUTH_MODE=none，您必须为Google Analytics API访问配置Google云控制台。

第一步：创建谷歌云项目

引导到谷歌云控制台
创建新项目或选择现有项目
记下项目ID以备后用

步骤2：启用所需的API

首选 API和服务>库
搜索并启用：
- 谷歌分析数据API v1 （GA4数据访问所需）
- 谷歌分析报告API （某些操作需要）

步骤3：创建服务帐户

首选 IAM和管理>服务帐户
点击 +创建服务帐户
输入描述性名称（例如，“mcp分析阅读器”）
跳过角色分配（角色在Google Analytics中管理）
点击完成

步骤4：生成服务帐户密钥

点击已创建的服务帐户
首选钥匙标签
点击 添加密钥>创建新密钥
选择 对象符号 格式
下载并安全存储JSON文件

步骤5：提取凭据

从下载的JSON文件中，为您的环境提取以下值：

{
  "client_email": "service-account@project-id.iam.gserviceaccount.com",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "project_id": "your-project-id"
}

步骤6：授予分析访问权限

打开谷歌分析
引导到 管理>物业访问管理
点击 +添加用户
从步骤5输入服务帐户电子邮件
分配观众角色
点击添加

步骤7：获取房产ID

在谷歌分析中，转到 管理员>物业>物业详情
复制属性ID（数值，如 123456789)
格式为 properties/123456789 用于配置

常见的身份验证误解

重要：设置 MCP_AUTH_MODE=none 仅禁用MCP客户端和此服务器之间的身份验证。它不影响Google Analytics API身份验证的要求，该身份验证使用服务帐户凭据，并且访问GA4数据始终是强制性的。

身份验证故障排除

403禁止：服务帐户缺少正确的GA4属性访问权限
401未经授权：服务帐户凭据无效或过期
API未启用：所需的Google Cloud API未激活
属性ID无效：确保格式为 properties/numeric-id

Auth0设置（可选-用于JWT/OAuth身份验证）

如果你打算使用 MCP_AUTH_MODE=jwt 或 MCP_AUTH_MODE=oauth，您必须配置Auth0进行身份验证。

所需的Auth0配置

步骤1:创建Auth0帐户

引导到身份验证0
注册免费帐户或登录现有帐户
创建新租户（或使用现有租户）

步骤2：创建API资源

在Auth0仪表板中，转到 应用程序>API
点击 +创建API
输入API详细信息：
- 名字: MCP Google Analytics Server
- 标识符: https://mcp.yourdomain.com （这将成为你的 AUTH0_AUDIENCE)
- 签名算法: RS256
点击创建

步骤3：配置API设置

在API设置中，请转至设置标签
注意 标识符 -这是你的 AUTH0_AUDIENCE
首选范围选项卡并添加：
- read:analytics -读取谷歌分析数据
启用 RBAC 和 在访问令牌中添加权限

步骤4：创建应用程序（用于测试）

首选 应用>应用
点击 +创建应用程序
选择 机器对机器应用
选择步骤2中创建的MCP API
授予 read:analytics 范围
注意 客户端ID 和 客户端密钥

步骤5：获取域名信息

在Auth0仪表板中，记录您的领域（例如。， your-tenant.auth0.com)
这将成为你的 AUTH0_DOMAIN 环境变量

步骤6：配置环境变量

# Auth0 Configuration
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=https://mcp.yourdomain.com
MCP_SERVER_RESOURCE=https://mcp.yourdomain.com
MCP_RESOURCE_URI=https://mcp.yourdomain.com

正在测试Auth0配置

您可以通过获取令牌来测试Auth0设置：

curl -X POST https://your-tenant.auth0.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "audience": "https://mcp.yourdomain.com",
    "grant_type": "client_credentials"
  }'

使用返回的 access_token 测试对MCP服务器的已验证请求。

常见的Auth0误解

重要：只有当您想对连接到服务器的MCP客户端进行身份验证时，才需要设置Auth0。如果你设置 MCP_AUTH_MODE=none，不需要Auth0配置，但仍然需要Google Analytics API身份验证。

快速开始

1.谷歌云设置

完成谷歌云身份验证在继续之前，请参阅上文。

2.安装

git clone https://github.com/nalyk/mcp-server-google-analytics.git
cd mcp-server-google-analytics
npm install

3.配置

创建一个 .env 示例中的文件：

cp .env.example .env

使用Google Cloud设置中的凭据配置所需的环境变量：

# HTTP Server Configuration
PORT=3001
MCP_AUTH_MODE=none
MCP_HTTP_HOST=0.0.0.0
MCP_CORS_ORIGINS=*
MCP_RESOURCE_URI=https://mcp.yourdomain.com
# Transport: stdio (default for MCP clients) or http
MCP_TRANSPORT=stdio
# HTTP session mode (http only): stateless accepts repeated initialize; stateful enforces session IDs
MCP_HTTP_SESSION_MODE=stateless

# Google Analytics Configuration (from Google Cloud setup)
# GA_PROPERTY_ID can be either just the numeric id (e.g. 123456789)
# or the full resource string (properties/123456789). The server normalizes it.
GA_PROPERTY_ID=123456789
GOOGLE_PROJECT_ID=your-google-cloud-project-id
GOOGLE_CLIENT_EMAIL=your-service-account@project.iam.gserviceaccount.com
GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

# Optional: MCP Transport Authentication
AUTH0_DOMAIN=your-domain.auth0.com
AUTH0_AUDIENCE=your-api-audience
MCP_SERVER_RESOURCE=required-resource-indicator
# Optional if not using AUTH0_ISSUER_URL explicitly; derived from domain otherwise
# AUTH0_ISSUER_URL=https://your-domain.auth0.com

4.发展

# Start in development mode
npm run dev

# Build for production
npm run build

# Start production server
npm start

跑步时 MCP_TRANSPORT=stdio （默认），服务器通过stdio为MCP客户端（例如Claude Desktop）通信。对于HTTP传输，设置 MCP_TRANSPORT=http.

启用HTTP传输后，服务器可在 http://localhost:3001 具有以下端点：

健康检查: GET /health
MCP端点: POST /mcp （JSON-RPC 2.0）
MCP SSE: GET /mcp （服务器发送的事件）
OAuth元数据: GET /.well-known/oauth-protected-resource （仅限OAuth模式）

MCP功能已实现

tools：列出了四个具有模式验证的GA工具
resources：基本资源(mcp-ga://server/health, mcp-ga://server/instructions, mcp-ga://ga/property)和模板
prompts：有用的GA提示模板(top_pages, active_users_by_country, events_by_name)
logging：发送服务器日志通知；客户端可以请求日志级别
progress：工具在请求时发出进度通知

Docker部署

使用Docker Compose（推荐）

# Build and start the service
docker compose up --build

# Run in detached mode
docker compose up --build -d

# Stop the service
docker compose down

直接使用Docker

# Build the image
docker build -t mcp-server-google-analytics .

# Run the container
docker run --env-file .env -p 3001:3001 mcp-server-google-analytics

身份验证模式

服务器通过以下方式支持三种身份验证模式 MCP_AUTH_MODE 环境变量：

无（开发）

MCP_AUTH_MODE=none

无需身份验证。适用于开发和可信环境。

JWT（制作）

MCP_AUTH_MODE=jwt
AUTH0_DOMAIN=your-domain.auth0.com
AUTH0_AUDIENCE=your-api-audience
MCP_SERVER_RESOURCE=your-resource-indicator

使用Auth0进行基于JWT的身份验证。请求标头中需要有效的JWT令牌。

OAuth 2.1（生产版）

MCP_AUTH_MODE=oauth
AUTH0_DOMAIN=your-domain.auth0.com
AUTH0_AUDIENCE=your-api-audience
MCP_RESOURCE_URI=https://mcp.yourdomain.com
MCP_SERVER_RESOURCE=your-resource-indicator

完全符合OAuth 2.1的受保护资源元数据和Auth0集成。提供自动授权服务器发现和资源绑定令牌，以实现最大安全性。

可用工具

该服务器提供了四种访问Google Analytics数据的工具：

`get_page_views`

使用可选的维度细分检索页面视图度量。

参数：

startDate （字符串）：YYYY-MM-DD格式的开始日期
endDate （字符串）：YYYY-MM-DD格式的结束日期
dimensions （数组，可选）：其他维度，如 ["page", "country"]

`get_active_users`

检索指定日期范围内的活动用户指标。

参数：

startDate （字符串）：YYYY-MM-DD格式的开始日期
endDate （字符串）：YYYY-MM-DD格式的结束日期

`get_events`

检索事件数据和指标，可选择按事件名称进行筛选。

参数：

startDate （字符串）：YYYY-MM-DD格式的开始日期
endDate （字符串）：YYYY-MM-DD格式的结束日期
eventName （字符串，可选）：要筛选的特定事件名称

`get_user_behavior`

检索用户行为和参与度指标，包括会话持续时间和跳出率。

参数：

startDate （字符串）：YYYY-MM-DD格式的开始日期
endDate （字符串）：YYYY-MM-DD格式的结束日期

Claude桌面集成

将此配置添加到您的Claude Desktop设置中：

{
  "mcpServers": {
    "google-analytics": {
      "command": "node",
      "args": ["path/to/mcp-server-google-analytics/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_EMAIL": "your-service-account@project.iam.gserviceaccount.com",
        "GOOGLE_PRIVATE_KEY": "your-private-key",
        "GA_PROPERTY_ID": "your-ga4-property-id",
        "GOOGLE_PROJECT_ID": "your-google-cloud-project-id",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

HTTP客户端集成

对于基于HTTP的MCP客户端，请连接到：

POST http://localhost:3001/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

可用脚本

npm run build -将TypeScript编译为JavaScript
npm start -运行已编译的服务器
npm run dev -在开发模式下运行并自动重新加载
npm test -使用Jest运行测试套件
npm run lint -使用ESLint抓取TypeScript文件

安全考虑

环境变量：始终对敏感凭据使用环境变量
服务帐户权限：遵循最小特权原则
JWT身份验证：为生产部署启用JWT身份验证
API费率限制：监控Google Analytics API的使用情况并实施速率限制
凭证轮换：定期轮换服务帐户凭据
CORS配置：为您的用例配置适当的CORS设置

依赖项

核心依赖关系

@google-analytics/data -官方谷歌分析数据API客户端
@modelcontextprotocol/sdk -用于构建MCP服务器的MCP SDK
express -Node.js的Web框架
express-oauth2-jwt-bearer -JWT身份验证中间件
googleapis -谷歌API Node.js客户端库
winston -专业日志库
zod -TypeScript第一模式验证

发展依赖性

typescript -类型安全的JavaScript开发
jest -测试框架
eslint -代码过滤和样式执行

贡献

我们欢迎捐款！请按照以下步骤操作：

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

请确保您的代码遵循现有样式，并包含适当的测试。

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

支持

有关问题、疑问或贡献，请访问我们的 GitHub存储库或者打开一个问题。

使用说明

用于谷歌分析的MCP服务器

特性

建筑

先决条件

谷歌云身份验证

身份验证体系结构

所需的Google Cloud控制台设置

第一步：创建谷歌云项目

步骤2：启用所需的API

步骤3：创建服务帐户

步骤4：生成服务帐户密钥

步骤5：提取凭据

步骤6：授予分析访问权限

步骤7：获取房产ID

常见的身份验证误解

身份验证故障排除

Auth0设置（可选-用于JWT/OAuth身份验证）

所需的Auth0配置

步骤1:创建Auth0帐户

步骤2：创建API资源

步骤3：配置API设置

步骤4：创建应用程序（用于测试）

步骤5：获取域名信息

步骤6：配置环境变量

正在测试Auth0配置

常见的Auth0误解

快速开始

1.谷歌云设置

2.安装

3.配置

4.发展

MCP功能已实现

Docker部署

使用Docker Compose（推荐）

直接使用Docker

身份验证模式

无（开发）

JWT（制作）

OAuth 2.1（生产版）

可用工具

get_page_views

get_active_users

get_events

get_user_behavior

Claude桌面集成

HTTP客户端集成

可用脚本

安全考虑

依赖项

核心依赖关系

发展依赖性

贡献

许可证

支持

相关 MCP

文件与终端管理MCP服务

图表生成MCP服务器

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

`get_page_views`

`get_active_users`

`get_events`

`get_user_behavior`