yandex-metrika-mcp

Query Yandex Metrika analytics in plain language, right inside Claude. "How many visits this week?", "Top traffic sources for June", "Mobile share today?" — the assistant queries Metrika and answers directly. No dashboards, no SQL, no API keys to manage.

Open-source by aiaiai — we build what we teach.

Задавай вопросы по Яндекс.Метрике обычным языком прямо в Claude. «Сколько визитов за неделю?», «топ источников за июнь», «доля мобильных?» — ассистент сам сходит в Метрику и ответит. Без дашбордов.

Спросил про географию аудитории обычным языком — агент сам построил карту из живой Яндекс.Метрики

Works with

Claude.ai · Claude Code · Claude Desktop · Cursor · any MCP-compatible client

Connect in one minute (hosted)

No installation needed — connect to the hosted service.

Claude.ai (Settings → Connectors → Add):

https://mcp.getaiaiai.ru/yandex-metrika

Click Connect → sign in with Yandex → allow access.

Claude Code CLI:

claude mcp add --transport http yandex-metrika https://mcp.getaiaiai.ru/yandex-metrika/
claude mcp login yandex-metrika

A browser window opens → sign in with Yandex → done. On headless/SSH: add --no-browser to mcp login and paste the redirect URL when prompted.

Claude Desktop / Cursor — add to mcpServers:

{
  "mcpServers": {
    "yandex-metrika": {
      "type": "http",
      "url": "https://mcp.getaiaiai.ru/yandex-metrika/"
    }
  }
}

No app registration, no tokens to manage. Read-only — the service never writes to your Metrika account.

Подключение на русском

Claude.ai (Настройки → Коннекторы → Добавить):

https://mcp.getaiaiai.ru/yandex-metrika

Нажмите Подключить → войдите через Яндекс → разрешите доступ.

Claude Code CLI:

claude mcp add --transport http yandex-metrika https://mcp.getaiaiai.ru/yandex-metrika/
claude mcp login yandex-metrika

Откроется браузер → войти через Яндекс → готово.

Tools

Tool	Description
`list_counters`	List all Yandex Metrika counters available to the token (id, name, site)
`query`	Run a Reporting API query — visits, users, pageviews, bounce rate, traffic sources, devices, geography, UTMs, and more

`query` parameters

Parameter	Default	Description
`counter_id`	required	Counter ID from `list_counters`
`metrics`	required	Comma-separated metrics, e.g. `ym:s:visits,ym:s:users`
`dimensions`	—	Group-by fields: `ym:s:date`, `ym:s:lastTrafficSource`, `ym:s:deviceCategory`, …
`date1` / `date2`	`7daysAgo` / `today`	Date range: `YYYY-MM-DD` or relative (`today`, `yesterday`, `NdaysAgo`)
`filters`	—	Filter expression, e.g. `ym:s:deviceCategory=='mobile'`
`sort`	—	Sort field; prefix `-` for descending, e.g. `-ym:s:visits`
`limit`	`100`	Max rows returned

Common metrics: ym:s:visits, ym:s:users, ym:s:pageviews, ym:s:bounceRate, ym:s:avgVisitDurationSeconds, ym:s:newUsers

Common dimensions: ym:s:date, ym:s:lastTrafficSource, ym:s:startURL, ym:s:deviceCategory, ym:s:regionCountry, ym:s:lastsourceUTMSource

Self-host with your own token

For developers — run the engine locally with full control over your data.

Requires Python 3.10+ and uv.

git clone https://github.com/expremiental/yandex-metrika-mcp.git
cd yandex-metrika-mcp
uv sync

Get a token. Go to oauth.yandex.ru, create an app (platform: "Web services"), enable Yandex Metrika → Read statistics (metrika:read), then get an OAuth token:

export YANDEX_METRIKA_TOKEN="<your-token>"

Connect (Claude Desktop / Cursor — add to mcpServers):

{
  "mcpServers": {
    "yandex-metrika": {
      "command": "uv",
      "args": ["run", "yandex-metrika-mcp"],
      "env": { "YANDEX_METRIKA_TOKEN": "<your-token>" }
    }
  }
}

Run over HTTP:

MCP_TRANSPORT=http PORT=8000 uv run yandex-metrika-mcp
# endpoint: http://localhost:8000/mcp

Embed in your own backend. The engine accepts an injectable async token resolver — wrap it with your own auth:

from yandex_metrika_mcp import build_server

async def my_token_resolver() -> str:
    return "<metrika:read token>"

build_server(token_resolver=my_token_resolver).run(transport="stdio")

Public API: build_server, YandexMetrikaClient, TokenResolver, env_token_resolver, main.

License

MIT · made by aiaiai

Yandex Metrika MCP