Yandex Metrika MCP

io.github.expremientalPublished by GitHub account expremientalv0.1.0Updated Oct 25, 2026

Read-only Yandex Metrika MCP. Query visits, sources, geo, devices and more in plain language.

VerifiedStreamable HTTPWeb executableWeb Search & ScrapingData & Analytics

Overview

AI-generated overview

A read-only Yandex Metrika MCP server that lets an assistant list counters and run Reporting API queries for visits, sources, devices and geography.

What you can do
List Yandex Metrika counters available to the token, with id, name and site, to pick a counter for queries. Run Reporting API queries against a counter using Metrika field names for metrics, dimensions, date ranges, filters, sorting and row limits. Answer plain-language questions about visits, users, pageviews, bounce rate, traffic sources, devices, geography and UTMs.
When to use it
Useful when you want an assistant to answer questions about Yandex Metrika traffic and audience statistics without building dashboards or writing queries by hand. Suited to read-only reporting on one or more counters you already have access to.
Requirements
Either the hosted remote endpoint, where you sign in with a Yandex account and grant access, or a local self-hosted run needing Python 3.10+ and uv. Self-hosting requires a Yandex OAuth token with metrika:read scope, supplied via the YANDEX_METRIKA_TOKEN environment variable. Network access to Yandex Metrika is needed.
Before you install
The hosted service receives your Yandex sign-in and analytics data, so consider whether that is acceptable. Self-hosting keeps data local but requires storing an OAuth token in YANDEX_METRIKA_TOKEN. The service is described as read-only and does not write to your Metrika account.

Installation

In SourceWeft

  1. Open Yandex Metrika MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.expremiental%2Fyandex-metrika-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

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

README

yandex-metrika-mcp

[License: MIT] [Python 3.10+] [FastMCP] [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:

bash
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:

json
{  "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:

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

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

Tools

ToolDescription
list_countersList all Yandex Metrika counters available to the token (id, name, site)
queryRun a Reporting API query — visits, users, pageviews, bounce rate, traffic sources, devices, geography, UTMs, and more

query parameters

ParameterDefaultDescription
counter_idrequiredCounter ID from list_counters
metricsrequiredComma-separated metrics, e.g. ym:s:visits,ym:s:users
dimensions—Group-by fields: ym:s:date, ym:s:lastTrafficSource, ym:s:deviceCategory, …
date1 / date27daysAgo / todayDate 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
limit100Max 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.

bash
git clone https://github.com/expremiental/yandex-metrika-mcp.gitcd yandex-metrika-mcpuv 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:

bash
export YANDEX_METRIKA_TOKEN="<your-token>"

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

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

Run over HTTP:

bash
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:

python
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

Source: README.md at commit 4e708b3

Tools

2

list_counters

List Yandex Metrika counters available to the token. Returns each counter's id, name and site so you can pick a `counter_id` for `query`. Read scope is enough.

Takes no parameters.

query

Run a Reporting API query against a Metrika counter (aggregated stats). Pass Metrika field names directly. Common ones: Metrics (comma-separated): ym:s:visits, ym:s:users, ym:s:pageviews, ym:s:bounceRate, ym:s:avgVisitDurationSeconds, ym:s:newUsers Dimensions (comma-separated, optional — groups the result): ym:s:date, ym:s:lastTrafficSource, ym:s:startURL, ym:s:deviceCategory, ym:s:regionCountry, ym:s:<attribution>UTMSource date1 / date2: YYYY-MM-DD or relative (today, yesterday, NdaysAgo). filters: Metrika filter expression, e.g. "ym:s:deviceCategory=='mobile'". sort: field to sort by; prefix with '-' for descending, e.g. "-ym:s:visits". Returns the raw Reporting API response (query meta, totals and data rows).

Parameterssortdate1date2limitfiltersmetricsrequiredcounter_idrequireddimensions

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts