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 配置中添加：

{
  "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 调用：

umeng_ping

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

随后查询应用列表：

umeng_get_all_apps

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

{
  "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

参数示例

查询新增用户趋势：

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

查询单日统计：

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

原始 OpenAPI 调用：

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

本地运行

需要在本地直接运行时：

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：

cp .env.example .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

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：

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