# umeng-openapi-mcp-server

友盟 U-App 移动统计 OpenAPI 的 MCP Server。可接入 Codex、Claude Desktop、Cursor 等支持 MCP 的 Agent，让 Agent 直接查询友盟应用列表、核心统计、留存、渠道/版本维度、自定义事件和游戏账号统计数据。

当前覆盖官方 `com.umeng.uapp` 命名空间下的 28 个 U-App 接口，并提供常用聚合工具与原始 OpenAPI 调用能力。

## 功能

- 查询当前账号下的 U-App 应用列表，并定位 `appkey`
- 查询今日、昨日、指定日期的 App 统计数据
- 查询新增用户、活跃用户、启动次数、使用时长和留存数据
- 查询渠道维度、版本维度数据
- 查询自定义事件、事件参数和事件参数值统计
- 查询游戏类型 App 的新增账号、活跃账号数据
- 创建 U-App 数据源和自定义事件
- 使用 `umeng_raw_call` 调用同命名空间下的 OpenAPI

## 环境要求

- Node.js >= 20
- npm
- 友盟 OpenAPI 的 `apiKey` 和 `apiSecurity`

`apiKey / apiSecurity` 是友盟 OpenAPI 账号级鉴权信息；`appkey` 是具体 App 的应用 ID，可通过 `umeng_get_all_apps` 或 `umeng_uapp_get_app_list` 查询。

## MCP 配置

在 Agent 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "umeng": {
      "command": "npx",
      "args": [
        "-y",
        "github:devhuang0714/umeng-openapi-mcp-server",
        "--transport",
        "stdio"
      ],
      "env": {
        "UMENG_API_KEY": "你的apiKey",
        "UMENG_API_SECURITY": "你的apiSecurity",
        "UMENG_HOST": "gateway.open.umeng.com",
        "UMENG_TIMEOUT_MS": "20000",
        "UMENG_DEFAULT_APPKEY": ""
      }
    }
  }
}
```

`UMENG_DEFAULT_APPKEY` 可选。设置后，带 `appkey` 的工具可以省略 `appkey` 参数，默认查询该 App。

## 快速验证

配置完成后，可先让 Agent 调用：

```text
umeng_ping
```

返回 `ok: true` 表示 MCP Server 已启动，并且环境变量已正确加载。

随后查询应用列表：

```text
umeng_get_all_apps
```

拿到目标应用的 `appkey` 后，即可调用统计工具，例如：

```json
{
  "appkey": "你的AppKey",
  "date": "2026-06-16"
}
```

## 常用工具

| MCP tool | 用途 |
| --- | --- |
| `umeng_ping` | 检查服务状态 |
| `umeng_get_app_list` | 分页查询应用列表 |
| `umeng_get_all_apps` | 自动翻页查询全部应用 |
| `umeng_find_apps` | 按关键词搜索应用 |
| `umeng_get_app_summary` | 聚合查询今日/昨日及指定日期统计 |
| `umeng_raw_call` | 按 `apiName` 调用友盟 OpenAPI |

## U-App 接口工具

这些工具一一对应官方 `com.umeng.uapp` 的 U-App 移动统计接口，统一使用 `umeng_uapp_*` 命名。

| MCP tool | 官方 API |
| --- | --- |
| `umeng_uapp_create_app` | `umeng.uapp.createApp` |
| `umeng_uapp_get_new_accounts` | `umeng.uapp.getNewAccounts` |
| `umeng_uapp_get_active_accounts` | `umeng.uapp.getActiveAccounts` |
| `umeng_uapp_event_create` | `umeng.uapp.event.create` |
| `umeng_uapp_get_launches_by_channel_or_version` | `umeng.uapp.getLaunchesByChannelOrVersion` |
| `umeng_uapp_get_active_users_by_channel_or_version` | `umeng.uapp.getActiveUsersByChannelOrVersion` |
| `umeng_uapp_get_new_users_by_channel_or_version` | `umeng.uapp.getNewUsersByChannelOrVersion` |
| `umeng_uapp_event_param_get_value_duration_list` | `umeng.uapp.event.param.getValueDurationList` |
| `umeng_uapp_get_today_yesterday_data` | `umeng.uapp.getTodayYesterdayData` |
| `umeng_uapp_get_yesterday_data` | `umeng.uapp.getYesterdayData` |
| `umeng_uapp_get_today_data` | `umeng.uapp.getTodayData` |
| `umeng_uapp_event_get_unique_users` | `umeng.uapp.event.getUniqueUsers` |
| `umeng_uapp_get_all_app_data` | `umeng.uapp.getAllAppData` |
| `umeng_uapp_get_app_count` | `umeng.uapp.getAppCount` |
| `umeng_uapp_get_channel_data` | `umeng.uapp.getChannelData` |
| `umeng_uapp_get_version_data` | `umeng.uapp.getVersionData` |
| `umeng_uapp_event_param_get_data` | `umeng.uapp.event.param.getData` |
| `umeng_uapp_event_param_get_value_list` | `umeng.uapp.event.param.getValueList` |
| `umeng_uapp_event_get_data` | `umeng.uapp.event.getData` |
| `umeng_uapp_event_param_list` | `umeng.uapp.event.param.list` |
| `umeng_uapp_event_list` | `umeng.uapp.event.list` |
| `umeng_uapp_get_retentions` | `umeng.uapp.getRetentions` |
| `umeng_uapp_get_durations` | `umeng.uapp.getDurations` |
| `umeng_uapp_get_launches` | `umeng.uapp.getLaunches` |
| `umeng_uapp_get_active_users` | `umeng.uapp.getActiveUsers` |
| `umeng_uapp_get_new_users` | `umeng.uapp.getNewUsers` |
| `umeng_uapp_get_daily_data` | `umeng.uapp.getDailyData` |
| `umeng_uapp_get_app_list` | `umeng.uapp.getAppList` |

## 参数示例

查询新增用户趋势：

```json
{
  "appkey": "你的AppKey",
  "startDate": "2026-06-01",
  "endDate": "2026-06-16",
  "periodType": "daily"
}
```

查询单日统计：

```json
{
  "appkey": "你的AppKey",
  "date": "2026-06-16",
  "channel": "App Store",
  "version": "1.0.0"
}
```

原始 OpenAPI 调用：

```json
{
  "apiName": "umeng.uapp.getDailyData",
  "namespace": "com.umeng.uapp",
  "version": 1,
  "method": "GET",
  "params": {
    "appkey": "你的AppKey",
    "date": "2026-06-16"
  }
}
```

## 本地运行

需要在本地直接运行时：

```bash
git clone git@github.com:devhuang0714/umeng-openapi-mcp-server.git
cd umeng-openapi-mcp-server
npm install
npm run build
npm run start
```

也可以使用 `.env`：

```bash
cp .env.example .env
```

```env
UMENG_API_KEY=你的友盟OpenAPI_apiKey
UMENG_API_SECURITY=你的友盟OpenAPI_apiSecurity
UMENG_HOST=gateway.open.umeng.com
UMENG_TIMEOUT_MS=20000
UMENG_DEFAULT_APPKEY=
```

## Docker

```bash
docker build -t umeng-openapi-mcp-server .

docker run --rm -i \
  -e UMENG_API_KEY="你的apiKey" \
  -e UMENG_API_SECURITY="你的apiSecurity" \
  -e UMENG_HOST="gateway.open.umeng.com" \
  -e UMENG_TIMEOUT_MS="20000" \
  umeng-openapi-mcp-server
```

MCP stdio 需要保持标准输入打开，因此 Docker 运行时需要 `-i`。

## 常见问题

### 如何获取 appkey？

调用 `umeng_get_all_apps` 或 `umeng_uapp_get_app_list`，返回结果中的 `appkey` 即为后续统计查询使用的 App ID。

### 已配置 UMENG_DEFAULT_APPKEY，为什么仍然查不到数据？

确认 `UMENG_DEFAULT_APPKEY` 是目标 U-App 的应用 `appkey`，不是友盟 OpenAPI 的 `UMENG_API_KEY`。

### 友盟返回鉴权或权限错误

检查 `UMENG_API_KEY / UMENG_API_SECURITY` 是否正确，以及当前友盟账号是否拥有目标 App 的 OpenAPI 访问权限。

### npx 运行时出现 npm cache 权限错误

可以临时指定 npm cache：

```bash
npm_config_cache=/tmp/npm-cache npx -y github:devhuang0714/umeng-openapi-mcp-server --transport stdio
```