内容
# Yandex Metrica MCP
[](https://www.npmjs.com/package/mcp-yandex-metrica)
[](https://github.com/askads/mcp-yandex-metrica/actions/workflows/ci.yml)
[](https://glama.ai/mcp/servers/askads/mcp-yandex-metrica)
[](./LICENSE)
MCP服务器，用于 **Yandex Metrica（Яндекс Метрика）**：通过自然语言从Claude、Cursor、Codex等AI客户端查询网站分析数据，包括流量来源、用户行为和目标转化率。
助手自动查找计数器，拉取Reporting API中的统计数据，并将目标与转化率进行匹配 - 所有这些都可以在Метрика界面中手动完成。
<img src="docs/demo.gif" alt="演示：一个问题 - 助手调用 list_counters、list_goals 和 get_statistics 并找到具有最佳转化率的流量来源" width="1000">
<sub>真正的MCP会话：实时服务器、握手和通过stdio进行tools/call，使用官方SDK；Метрика的答案是记录的fixture（<a href="docs/demo">docs/demo</a>），因此无需令牌和网络即可重现演示 - <a href="docs/demo.tape">vhs docs/demo.tape</a>。</sub>
## 快速入门
1. [获取令牌](#获取令牌) - 您的Yandex OAuth应用程序，大约5分钟，无需代码。
2. 添加服务器 - 例如，在Claude Code中（[其他客户端](#安装)）：
```bash
claude mcp add yandex-metrica -e YANDEX_METRIKA_TOKEN=您的令牌 -- npx -y mcp-yandex-metrica
```
3. 向助手提问：“目标‘订单完成’的30天转化率是多少？”
> **无需安装：** Метрика 进入远程服务器 Яндекс Директа - 将 `https://mcp.askads.ru/mcp` 添加到URL（[说明](https://github.com/askads/mcp-yandex-direct#连接-url-无需安装)），Метрика 工具在前缀 `metrika_` 下可见。
## 功能
- **计数器和目标** - `list_counters`（可访问的计数器）和`list_goals`（计数器的目标/转化率）通过Management API。
- **统计数据** - `get_statistics` 通过Reporting API（`stat/v1/data`）：指标和维度、时间段（包括相对时间段 - `7daysAgo`）、过滤器、排序、自动分页。
- **转化率** - 目标指标 `ym:s:goal<id>reaches` / `ym:s:goal<id>conversionRate`.
- **诚实抽样** - 答案包含 `totals`（所有行的总和）和 `sampled`/`sample_share`，以便在数据被抽样时可见。
- **通用`raw_request`** - 任何API路径的直接调用；GET请求免费，写入（POST/DELETE）仅在 `confirmWrite=true` 时允许。
- **容错性** - 429/5xx 错误重试，带有回退和请求超时。
## 查询示例
用中文向助手提问 - 例如：
- “过去一周的访问量和跳出率是多少？”
- “显示六月份的流量来源 - 按 ym:s:lastTrafficSource 分组”
- “目标‘订单完成’的30天转化率是多少？”
- “根据域名 shop.example 查找计数器并显示其目标”
## 安装
<details>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add yandex-metrica -e YANDEX_METRIKA_TOKEN=您的令牌 -- npx -y mcp-yandex-metrica
```
或者通过插件市场 - 令牌将在启用时通过对话框询问并保存在系统keychain中（不以明文存储在配置文件中）：
```
/plugin marketplace add askads/claude-plugins
/plugin install yandex-metrica@askads
```
</details>
<details>
<summary><b>Claude Desktop</b></summary>
`claude_desktop_config.json` - macOS `~/Library/Application Support/Claude/`，Windows `%APPDATA%\Claude\`
```json
{
"mcpServers": {
"yandex-metrica": {
"command": "npx",
"args": ["-y", "mcp-yandex-metrica"],
"env": { "YANDEX_METRIKA_TOKEN": "您的令牌" }
}
}
}
```
</details>
<details>
<summary><b>Cursor</b></summary>
`~/.cursor/mcp.json`（或项目中的 `.cursor/mcp.json`）
```json
{
"mcpServers": {
"yandex-metrica": {
"command": "npx",
"args": ["-y", "mcp-yandex-metrica"],
"env": { "YANDEX_METRIKA_TOKEN": "您的令牌" }
}
}
}
```
</details>
<details>
<summary><b>OpenAI Codex</b></summary>
```toml
[mcp_servers.yandex-metrica]
command = "npx"
args = ["-y", "mcp-yandex-metrica"]
[mcp_servers.yandex-metrica.env]
YANDEX_METRIKA_TOKEN = "您的令牌"
```
</details>
<details>
<summary><b>VS Code</b></summary>
`.vscode/mcp.json` - 关键字 `servers`（不是 `mcpServers`）
```json
{
"servers": {
"yandex-metrica": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-yandex-metrica"],
"env": { "YANDEX_METRIKA_TOKEN": "您的令牌" }
}
}
}
```
</details>
## 获取令牌
需要具有 **“获取统计数据，读取自己的和受信任的计数器的参数”** 权限的OAuth令牌（范围 `metrika:read`）。有两种方法。
**快速 - Ask Ads 链接。** 在具有访问所需计数器的帐户下打开链接并确认访问：
[**→ 获取令牌**](https://oauth.yandex.ru/authorize?response_type=token&client_id=c48790e11f0e48c588d2cd2d1b4bb92d)
浏览器将返回Ask Ads网站 - 令牌将显示在 **弹出窗口** 中，复制到 `YANDEX_METRIKA_TOKEN`。⚠️ 应用程序与 [mcp-yandex-direct](https://github.com/askads/mcp-yandex-direct) 共享，因此令牌不仅提供Метрика读取权限，还提供 **完全访问Яндекс Директ** - 如果不需要，请使用第二种方法。
**最小 - 您自己的应用程序（仅 `metrika:read`）。**
<details>
<summary>创建自己的OAuth应用程序需要5分钟，无需代码</summary>
1. 打开 [oauth.yandex.ru](https://oauth.yandex.ru/) → **创建应用程序**。平台 - “Web服务”，Redirect URI - `https://oauth.yandex.ru/verification_code`。
2. 在访问权限中，选中 **Яндекс.Метрика → “获取统计数据，读取自己的和受信任的计数器的参数”** 并保存。复制应用程序的 **ClientID**。
3. 在浏览器中打开 - 在具有访问所需计数器的帐户下：`https://oauth.yandex.ru/authorize?response_type=token&client_id=<您的ClientID>` - 确认访问，令牌将直接在页面上显示。
4. 将令牌复制到 `YANDEX_METRIKA_TOKEN` 变量中。
</details>
⚠️ 令牌提供对分析数据的访问，并以 **明文** 存储在配置文件中 - 请像对待密码一样保护它。
## 配置
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `YANDEX_METRIKA_TOKEN` | 是 | - | Метрика OAuth令牌（范围 `metrika:read`）。 |
| `YANDEX_METRIKA_COUNTER_ID` | 否 | - | 默认计数器，如果调用中未指定 `counterId`。 |
| `YANDEX_METRIKA_LANG` | 否 | `ru` | `Accept-Language` 头。 |
| `YANDEX_METRIKA_API_BASE` | 否 | `https://api-metrika.yandex.net` | API根。 |
| `YANDEX_METRIKA_TIMEOUT_MS` | 否 | `60000` | 请求超时，毫秒。 |
| `YANDEX_METRIKA_MAX_RETRIES` | 否 | `3` | 429/5xx 错误重试次数。 |
完整工具列表在 [docs/TOOLS.md](https://github.com/askads/mcp-yandex-metrica/blob/main/docs/TOOLS.md)。
## 要求
- Node.js 20+（通过 `npx` 运行，不需要单独安装）。
- Метрика OAuth令牌 - 参见 [获取令牌](#获取令牌)。
## 限制
- **只读MVP** - 没有更改操作；通过 `raw_request` 进行写入仅在显式 `confirmWrite=true` 时允许。
- Reporting API可能 **抽样** 大时间段的数据 - 在响应中查看 `sampled`/`sample_share`，并在必要时传递 `accuracy: "full"`。
- Метрика 没有沙盒 - 所有调用都到战斗API（但MVP仅读取）。
## 文档
- [所有工具](https://github.com/askads/mcp-yandex-metrica/blob/main/docs/TOOLS.md)
- [开发](https://github.com/askads/mcp-yandex-metrica/blob/main/docs/DEVELOPMENT.md)
## 另见
- **[Ask Ads](https://askads.ru)** - 作者的聊天分析师和广告账户“守卫”：来自Telegram的预算耗尽和跟踪损坏警报。
- **[askads/claude-plugins](https://github.com/askads/claude-plugins)** - Claude插件市场：Ask Ads服务器通过一个命令安装，令牌在启用时询问。
## 支持
问题，想法和改进 - 请在Telegram上写给 [@gistrec](http://t.me/gistrec)。
## 许可证
MIT - 参见 [LICENSE](./LICENSE)。
