内容
# appmetrica-mcp
[](https://www.npmjs.com/package/appmetrica-mcp)
[](LICENSE)
MCP 服务器，用于 [AppMetrica](https://appmetrica.yandex.com) - Yandex 的移动应用分析平台。提供 Claude 直接访问您的应用分析数据：报告、原始事件日志、崩溃数据和推送通知活动。
## 功能
- **报告 API** - 提供汇总指标（用户、会话、收入、留存）及维度细分
- **日志 API** - 提供原始事件、崩溃和安装日志导出
- **管理 API** - 列出和查看您的 AppMetrica 应用
- **推送 API** - 查看活动和统计数据；创建推送活动（需启用写入模式）
- **默认安全** - 除非显式启用，否则写入操作被禁用
## 要求
- Node.js 22+
- 一个 AppMetrica 账户，至少有一个应用
- 一个 Yandex OAuth token（见下文）
## 获取 OAuth Token
AppMetrica 使用 Yandex OAuth。请使用 **俄罗斯 OAuth 门户** (`oauth.yandex.ru`) - 国际版 (`oauth.yandex.com`) 不会在其 UI 中公开 AppMetrica 权限。
### 步骤 1 - 创建 OAuth 应用
1. 访问 [oauth.yandex.ru/client/new](https://oauth.yandex.ru/client/new)
2. 填写任意 **名称**（例如 `AppMetrica MCP`）
3. 在 **平台** 下，选择 **Web 服务** 并将回调 URI 设置为：
```
https://oauth.yandex.ru/verification_code
```
4. 在 **访问权限（Доступы）** 下，找到 **AppMetrica** 部分并启用：
- `Чтение данных AppMetrica` - 读取权限（必需）
- `Запись данных AppMetrica` - 写入权限（可选，创建推送活动需要）
5. 点击 **创建应用** 并复制 **ClientID**
### 步骤 2 - 获取 token
在浏览器中打开以下网址（将 `CLIENT_ID` 替换为您的应用 ID）：
```
https://oauth.yandex.ru/authorize?response_type=token&client_id=CLIENT_ID
```
登录 → 授权应用 → 从重定向 URL 中复制 `access_token` 值。
> **注意：** token 默认不会过期。您可以在 [passport.yandex.ru/profile/access](https://passport.yandex.ru/profile/access) 处随时撤销它。
## 安装
### Claude 代码（推荐）
```bash
claude mcp add appmetrica \
-e APPMETRICA_OAUTH_TOKEN=您的_token \
-- npx -y appmetrica-mcp
```
要启用写入操作（创建推送活动）：
```bash
claude mcp add appmetrica \
-e APPMETRICA_OAUTH_TOKEN=您的_token \
-e APPMETRICA_ALLOW_WRITE=true \
-- npx -y appmetrica-mcp
```
### Claude 桌面版
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"appmetrica": {
"command": "npx",
"args": ["-y", "appmetrica-mcp"],
"env": {
"APPMETRICA_OAUTH_TOKEN": "您的_token"
}
}
}
}
```
### 从源码构建
```bash
git clone https://github.com/pavellunev99/app_metrica_mcp
cd app_metrica_mcp
npm install
npm run build
```
## 配置
| 变量 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|
| `APPMETRICA_OAUTH_TOKEN` | 是 | - | 具有 AppMetrica 权限的 Yandex OAuth token |
| `APPMETRICA_ALLOW_WRITE` | 否 | `false` | 设置为 `true` 以启用推送活动创建 |
## 可用工具
### 管理
| 工具 | 描述 |
|---|---|
| `list_applications` | 列出您账户中的所有 AppMetrica 应用 |
| `get_application` | 获取特定应用的详细信息，ID |
### 报告
| 工具 | 描述 |
|---|---|
| `get_report` | 获取指定日期范围的汇总指标（用户、会话、崩溃等） |
| `get_drilldown` | 深入某个维度值以获取详细分类 |
| `list_metrics` | 列出可用的指标键及其描述 |
### 日志
| 工具 | 描述 |
|---|---|
| `export_events` | 导出原始自定义事件日志 |
| `export_crashes` | 导出原始崩溃日志 |
| `export_installations` | 导出原始安装日志 |
### 推送通知
| 工具 | 访问权限 | 描述 |
|---|---|---|
| `list_push_campaigns` | 读取 | 列出推送通知活动，附带可选状态筛选 |
| `get_push_stats` | 读取 | 获取活动的投递统计数据 |
| `create_push_campaign` | 写入 | 创建推送活动（需要 `APPMETRICA_ALLOW_WRITE=true`） |
## 使用示例
连接后，您可以询问 Claude：
- *"列出我的 AppMetrica 应用"*
- *"显示应用 12345 在过去 7 天内的 DAU 和会话数"*
- *"导出应用 12345 从 2024-01-01 至 2024-01-07 的崩溃日志"*
- *"应用 12345 当前有哪些活跃的推送活动？"*
- *"按应用版本显示新增用户数量的细分数据"*
## 请求限制
AppMetrica 对所有 API 请求实施以下限制：
- **每秒 30 个请求**，每个 OAuth token
- **每天 5,000 个请求**，每个 OAuth token
客户端在 `429` 和 `5xx` 响应时自动重试，指数退避（1s → 2s → 4s，最多 3 次尝试）。
## 许可证
MIT
