Google Analytics Data API MCP Server

Google Analytics Data API MCP 服务

一个用于与 Google Analytics Data API v1 交互的模型上下文协议（MCP）服务。此服务提供用于查询 Google Analytics 数据、管理受众群体和访问元数据的工具和资源。

## 功能

- 运行标准报告和透视报告
- 批量报告功能
- 访问维度和指标的元数据
- 创建、列出、更新和删除受众群体
- 检查维度和指标之间的兼容性
- 提供全面的资源端点，用于探索 GA 数据

## 前提条件

- Node.js 14 或更高版本
- Google Analytics 4 媒体资源
- 具有相应权限的 Google Cloud 服务账号

## 设置

1. 克隆此代码库
2. 安装依赖项：
   ```
   npm install
   ```
3. 根据 `.env.example` 创建 `.env` 文件，并填入你的 Google Analytics 凭据：
   ```
   GOOGLE_CLIENT_EMAIL=your-service-account-email@project-id.iam.gserviceaccount.com
   GOOGLE_PRIVATE_KEY=your-private-key
   DEFAULT_PROPERTY_ID=properties/123456789
   ```

## 使用方法

### 运行服务

```
npm start
```

### 使用 MCP Inspector 进行测试

```
npm run inspect
```

## 可用工具

- **runReport**：运行 Google Analytics 数据标准报告
- **batchRunReports**：在单个批次中运行多份报告
- **runPivotReport**：运行 Google Analytics 数据透视报告
- **batchRunPivotReports**：在一个批次中运行多份透视报告
- **getMetadata**：获取维度和指标的元数据
- **checkCompatibility**：检查维度和指标之间的兼容性
- **createAudience**：创建新的受众群体
- **listAudiences**：列出媒体资源中的受众群体
- **getAudience**：获取特定受众群体的详细信息
- **deleteAudience**：删除受众群体
- **updateAudience**：更新现有受众群体

## 可用资源

- **ga://property/{propertyId}**：获取媒体资源信息
- **ga://report/{propertyId}/{reportType}/{dimensions}/{metrics}/{startDate}/{endDate}**：生成报告
- **ga://metadata**：获取 API 元数据
- **ga://dimensions**：按类别浏览维度
- **ga://dimensions/{category}**：获取特定类别中的维度
- **ga://metrics**：按类别浏览指标
- **ga://metrics/{category}**：获取特定类别中的指标
- **ga://audiences/{propertyId}**：列出媒体资源中的受众群体
- **ga://audiences/{propertyId}/{audienceId}**：获取特定受众群体的详细信息

## 查询示例

### 运行基本报告

```javascript
{
  "propertyId": "properties/123456789",
  "dateRanges": [
    {
      "startDate": "7daysAgo",
      "endDate": "yesterday"
    }
  ],
  "dimensions": [
    {
      "name": "country"
    },
    {
      "name": "deviceCategory"
    }
  ],
  "metrics": [
    {
      "name": "activeUsers"
    },
    {
      "name": "sessions"
    }
  ]
}
```

### 创建受众群体

```javascript
{
  "propertyId": "properties/123456789",
  "displayName": "High Value Users",
  "description": "Users who have completed a purchase",
  "membershipDurationDays": 30,
  "filterClauses": [
    {
      "filterExpression": {
        "andGroup": {
          "expressions": [
            {
              "filter": {
                "fieldName": "eventName",
                "stringFilter": {
                  "value": "purchase",
                  "matchType": "EXACT"
                }
              }
            }
          ]
        }
      }
    }
  ]
}
```

## 许可证

MIT