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