Content
# 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 server for **Yandex Metrica**: ask web analytics - traffic, sources, behavior and conversions by goals - from Claude, Cursor, Codex and other AI clients in natural language.
The assistant finds counters itself, pulls statistics from the Reporting API and correlates goals with conversions - what you have to collect manually from reports in the Metrika interface.
<img src="docs/demo.gif" alt="Demo: one question - the assistant calls list_counters, list_goals and get_statistics and finds the traffic source with the best conversion" width="1000">
<sub>Real MCP session: real server, handshake and tools/call via stdio through the official SDK; Yandex Metrica responses are recorded fixtures (<a href="docs/demo">docs/demo</a>), so the demo is reproduced without a token and network - <a href="docs/demo.tape">vhs docs/demo.tape</a>.</sub>
## Quick Start
1. [Get a token](#getting-a-token) — your own Yandex OAuth application, ~5 minutes, no code.
2. Add the server - for example, in Claude Code ([other clients](#installation)):
```bash
claude mcp add yandex-metrica -e YANDEX_METRIKA_TOKEN=your_token -- npx -y mcp-yandex-metrica
```
3. Ask the assistant: "What is the conversion by the goal 'Order placement' for 30 days?"
> **Without installation:** Metrica is included in the remote Yandex Direct server - add `https://mcp.askads.ru/mcp` by URL ([instructions](https://github.com/askads/mcp-yandex-direct#getting-started-without-installation)), Metrica tools are visible with the prefix `metrika_`.
## Capabilities
- **Counters and goals** — `list_counters` (accessible counters) and `list_goals` (counter goals/conversions) via Management API.
- **Statistics** — `get_statistics` via Reporting API (`stat/v1/data`): metrics and dimensions, period (including relative - `7daysAgo`), filters, sorting, auto-pagination.
- **Conversions** — goal metrics `ym:s:goal<id>reaches` / `ym:s:goal<id>conversionRate`.
- **Fair sampling** — the response carries `totals` (summary for all rows) and `sampled`/`sample_share`, so you can see when the data is sampled.
- **Universal `raw_request`** — direct call of any API path; GET is free, writing (POST/DELETE) only with `confirmWrite=true`.
- **Robustness** — retries on 429/5xx with backoff and request timeout.
## Query Examples
Ask the assistant in Russian - for example:
- "How many visits and what is the bounce rate for the last week?"
- "Show traffic by sources for June - group by ym:s:lastTrafficSource"
- "What is the conversion by the goal 'Order placement' for 30 days?"
- "Find a counter by the domain shop.example and show its goals"
## Installation
<details>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add yandex-metrica -e YANDEX_METRIKA_TOKEN=your_token -- npx -y mcp-yandex-metrica
```
Or through the plugin marketplace - the token will be prompted by the dialog when enabled and saved in the system keychain (not in the config in plain text):
```
/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": "your_token" }
}
}
}
```
</details>
<details>
<summary><b>Cursor</b></summary>
`~/.cursor/mcp.json` (or `.cursor/mcp.json` in the project)
```json
{
"mcpServers": {
"yandex-metrica": {
"command": "npx",
"args": ["-y", "mcp-yandex-metrica"],
"env": { "YANDEX_METRIKA_TOKEN": "your_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 = "your_token"
```
</details>
<details>
<summary><b>VS Code</b></summary>
`.vscode/mcp.json` — key `servers` (not `mcpServers`)
```json
{
"servers": {
"yandex-metrica": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-yandex-metrica"],
"env": { "YANDEX_METRIKA_TOKEN": "your_token" }
}
}
}
```
</details>
## Getting a Token
You need an OAuth token with the right **«Getting statistics, reading parameters of own and trusted counters»** (scope `metrika:read`). Two ways.
**Fast - Ask Ads link.** Open the link **under the account with access to the required counters** and confirm access:
[**→ Get token**](https://oauth.yandex.ru/authorize?response_type=token&client_id=c48790e11f0e48c588d2cd2d1b4bb92d)
The browser will return you to the Ask Ads site - the token will appear **in the popup window**, copy it to `YANDEX_METRIKA_TOKEN`. ⚠️ The application is common with [mcp-yandex-direct](https://github.com/askads/mcp-yandex-direct), so the token gives not only reading of Metrica, but also **full access to Yandex Direct** - if this is extra, use the second method.
**Minimal - your own application (only `metrika:read`).**
<details>
<summary>Your own OAuth application is created in five minutes, no code is needed</summary>
1. Open [oauth.yandex.ru](https://oauth.yandex.ru/) → **Create application**. Platform — «Web services», Redirect URI — `https://oauth.yandex.ru/verification_code`.
2. In access rights, mark **Yandex Metrica → «Getting statistics, reading parameters of own and trusted counters»** and save. Copy the **ClientID** of the application.
3. Open in the browser - under the account with access to the required counters: `https://oauth.yandex.ru/authorize?response_type=token&client_id=<your ClientID>` - confirm access, and the token will appear directly on the page.
4. Copy the token to the `YANDEX_METRIKA_TOKEN` variable.
</details>
⚠️ The token gives access to analytics data and is stored **in plain text** in the config - treat it like a password.
## Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
| `YANDEX_METRIKA_TOKEN` | yes | — | OAuth token of Metrica (scope `metrika:read`). |
| `YANDEX_METRIKA_COUNTER_ID` | no | — | Default counter if not specified in the call `counterId`. |
| `YANDEX_METRIKA_LANG` | no | `ru` | `Accept-Language` header. |
| `YANDEX_METRIKA_API_BASE` | no | `https://api-metrika.yandex.net` | API root. |
| `YANDEX_METRIKA_TIMEOUT_MS` | no | `60000` | Request timeout, ms. |
| `YANDEX_METRIKA_MAX_RETRIES` | no | `3` | Retries on 429/5xx. |
The full list of tools is in [docs/TOOLS.md](https://github.com/askads/mcp-yandex-metrica/blob/main/docs/TOOLS.md).
## Requirements
- Node.js 20+ (launched via `npx`, no separate installation needed).
- Metrica OAuth token - see [Getting a token](#getting-a-token).
## Limitations
- **Read-only MVP** — no changing operations; writing is available only through `raw_request` with explicit `confirmWrite=true`.
- Reporting API may **sample** data for large periods - see `sampled`/`sample_share` in the response and, if necessary, pass `accuracy: "full"`.
- Metrica does not have a sandbox - all calls go to the combat API (but MVP only reads).
## Documentation
- [All tools](https://github.com/askads/mcp-yandex-metrica/blob/main/docs/TOOLS.md)
- [Development](https://github.com/askads/mcp-yandex-metrica/blob/main/docs/DEVELOPMENT.md)
## See Also
- **[Ask Ads](https://askads.ru)** — chat-analyst and «Guardian» of ad accounts from the authors of this server: alerts about budget drains and tracking breaks - in Telegram.
- **[askads/claude-plugins](https://github.com/askads/claude-plugins)** — Claude plugin marketplace: Ask Ads servers are installed with one command, tokens are prompted when enabled.
## Support
Questions, ideas and enhancements - write in Telegram: [@gistrec](http://t.me/gistrec).
## License
MIT - see [LICENSE](./LICENSE).
