# yandex-metrica-mcp

An MCP server that lets an agent read Yandex Metrica data: reports, period comparisons, trends and log exports. Useful when a couple of numbers aren't worth opening the dashboard.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 15
- Author: BoxLab-Ltd
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/BoxLab-Ltd/yandex-metrica-mcp
- Updated: 2026-10-19
- HTML: https://affpapa.org/en/nevibecode/mcp/yandex-metrica-mcp

## What it does

The server exposes a handful of read-only tools over the Reporting API. `run_report` builds a report for a chosen breakdown, `run_comparison` puts two periods side by side with absolute and percentage deltas, `run_timeseries` splits metrics by time, and `run_drilldown` walks down a dimension tree. `get_metadata` lists the counters on the account plus real dimension and metric names, so the model stops inventing fields. The Logs API tools export raw visit or hit rows in four steps: request, poll, download, clean.

Nothing here writes to your counter. Sign-in is interactive: the server opens the consent page itself and captures the code through a local redirect, then caches the token for roughly a year. For CI or a GUI setup there is a static `YANDEX_METRIKA_TOKEN`. You need Node.js 18 or newer, and whoever owns the credentials must have access to the counters being queried under the `metrika:read` scope.

The loopback port `53682` can be busy. When that happens the flow falls back to pasting a code by hand, and `YANDEX_OAUTH_LOOPBACK_PORT` moves the port elsewhere. A cached login wins over the `YANDEX_METRIKA_TOKEN` variable, so an expired file token blocks the static one until you run the login again.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `YANDEX_METRIKA_TOKEN`, `YANDEX_METRIKA_COUNTER_ID`, `YANDEX_METRIKA_LOGS_DIR` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env YANDEX_METRIKA_TOKEN=<YANDEX_METRIKA_TOKEN> --env YANDEX_METRIKA_COUNTER_ID=<YANDEX_METRIKA_COUNTER_ID> --env YANDEX_METRIKA_LOGS_DIR=<YANDEX_METRIKA_LOGS_DIR> --transport stdio yandex-metrica-mcp -- npx -y yandex-metrica-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add yandex-metrica-mcp --env YANDEX_METRIKA_TOKEN=<YANDEX_METRIKA_TOKEN> --env YANDEX_METRIKA_COUNTER_ID=<YANDEX_METRIKA_COUNTER_ID> --env YANDEX_METRIKA_LOGS_DIR=<YANDEX_METRIKA_LOGS_DIR> -- npx -y yandex-metrica-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "yandex-metrica-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "yandex-metrica-mcp"
            ],
            "env": {
                "YANDEX_METRIKA_TOKEN": "<YANDEX_METRIKA_TOKEN>",
                "YANDEX_METRIKA_COUNTER_ID": "<YANDEX_METRIKA_COUNTER_ID>",
                "YANDEX_METRIKA_LOGS_DIR": "<YANDEX_METRIKA_LOGS_DIR>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "yandex-metrica-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "yandex-metrica-mcp"
            ],
            "env": {
                "YANDEX_METRIKA_TOKEN": "<YANDEX_METRIKA_TOKEN>",
                "YANDEX_METRIKA_COUNTER_ID": "<YANDEX_METRIKA_COUNTER_ID>",
                "YANDEX_METRIKA_LOGS_DIR": "<YANDEX_METRIKA_LOGS_DIR>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e YANDEX_METRIKA_TOKEN=<YANDEX_METRIKA_TOKEN> -e YANDEX_METRIKA_COUNTER_ID=<YANDEX_METRIKA_COUNTER_ID> -e YANDEX_METRIKA_LOGS_DIR=<YANDEX_METRIKA_LOGS_DIR> yandex-metrica-mcp npx -y yandex-metrica-mcp
```
Replace <…> with your own values

## When to use it
- check traffic sources for the last week without opening the Metrica UI
- compare two periods and spot where conversions dropped
- export raw visit rows for your own analysis
- find goal ids on a counter before querying conversion metrics
- chart a metric over time inside the chat

## Example prompts
- Show traffic sources for my counter over the last 7 days
- Compare visits and conversions between this week and last week
- List the goals configured on the counter with their ids

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40409
- [dbx](https://affpapa.org/en/nevibecode/mcp/dbx.md) — MCP server · ★ 27669
- [Metabase](https://affpapa.org/en/nevibecode/mcp/metabase.md) — MCP server · ★ 49845

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md