Yandex Metrica MCP

Статистика

get_statistics

Read-onlyIdempotent

Retrieves Yandex Metrica reporting data for a counter, returning aggregated totals or grouped rows by dimensions like date, traffic source, or device, with customizable metrics, filters, and date ranges.

Instructions

Запрашивает Reporting API Яндекс Метрики (stat/v1/data) по счётчику. ПО УМОЛЧАНИЮ возвращает одну строку, агрегированную за период (без измерений), с visits/users/pageviews/bounceRate/avgVisitDurationSeconds. dimensions разбивает результат на строки (ym:s:date — динамика по дням, ym:s:lastTrafficSource — источники трафика, ym:s:deviceCategory — устройства), metrics задаёт нужные метрики — для конверсий это ym:s:goalreaches / ym:s:goalconversionRate (идентификаторы целей даёт list_goals). В ответе есть totals (итог по ВСЕМ строкам — для вопросов «сколько всего» суммировать не нужно), total_rows и sampled/sample_share (sampled=true означает, что данные приблизительные; для точных цифр нужно сузить период или передать accuracy=full). counterId обязателен: id счётчика даёт list_counters.

Input Schema

Name	Required	Description
`sort`	No	Поле сортировки; префикс '-' — по убыванию, например -ym:s:visits.
`date1`	No	Дата начала: YYYY-MM-DD или относительная (today, yesterday, NdaysAgo). По умолчанию 7daysAgo.
`date2`	No	Дата конца: YYYY-MM-DD или относительная (today, yesterday, NdaysAgo). По умолчанию yesterday.
`limit`	No	Максимум строк на странице (игнорируется, если задан autoPaginate).
`offset`	No	Смещение по строкам для постраничной выдачи, отсчёт с 1.
`filters`	No	Выражение фильтра Метрики, например ym:s:deviceCategory=='mobile'.
`metrics`	No	Метрики (не больше 20 — лимит API), например ym:s:visits, ym:s:users, ym:s:bounceRate, ym:s:goal<id>reaches. По умолчанию — типовой набор.
`accuracy`	No	Точность сэмплирования: 'full' — точный расчёт (медленнее) или доля 0..1. По умолчанию — авторежим API.
`maxPages`	No	Лимит страниц для autoPaginate. По умолчанию 100.
`counterId`	Yes	Идентификатор счётчика из list_counters.
`dimensions`	No	Измерения для группировки, например ym:s:date, ym:s:lastTrafficSource, ym:s:deviceCategory. Без них — итог за период.
`autoPaginate`	No	Забирает все строки, листая страницами максимального для API размера (склеивает data, сохраняет totals). Игнорирует `limit`; ограничен maxPages и лимитами по строкам/байтам (при их достижении выставляет _truncated).
`directClientLogins`	No	Логины клиентов Яндекс Директа — нужны метрикам расходов Директа (ym:ad:*), без них API отвечает 403 direct_client_logins.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv1.5.1Oct 31, 2026

changedInput schema / properties / counterId / description

Previous value: -"Идентификатор счётчика. По умолчанию YANDEX_METRIKA_COUNTER_ID."New value: +"Идентификатор счётчика из list_counters."

addedInput schema / properties / directClientLogins

Added value: +{
+  "description": "Логины клиентов Яндекс Директа — нужны метрикам расходов Директа (ym:ad:*), без них API отвечает 403 direct_client_logins.",
+  "items": {
+    "pattern": "^[A-Za-z0-9][A-Za-z0-9._@-]{0,99}$",
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / metrics / description

Previous value: -"Метрики, например ym:s:visits, ym:s:users, ym:s:bounceRate, ym:s:goal<id>reaches. По умолчанию — типовой набор."New value: +"Метрики (не больше 20 — лимит API), например ym:s:visits, ym:s:users, ym:s:bounceRate, ym:s:goal<id>reaches. По умолчанию — типовой набор."

addedInput schema / properties / metrics / maxItems
```
Added value: +20
```
addedInput schema / properties / metrics / minItems
```
Added value: +1
```
addedInput schema / required
```
Added value: +[
+  "counterId"
+]
```

Changed12 schema fields changedv1.4.1Aug 21, 2026

changedInput schema / properties / accuracy / description

Previous value: -"Sampling accuracy: 'full' for exact (slower), or a 0..1 share. Default the API's auto."New value: +"Точность сэмплирования: 'full' — точный расчёт (медленнее) или доля 0..1. По умолчанию — авторежим API."

changedInput schema / properties / autoPaginate / description

Previous value: -"Fetch all rows by following the API-max page size (merges data, carries totals). Ignores `limit`; capped by maxPages and by row/byte limits (flags _truncated when hit)."New value: +"Забирает все строки, листая страницами максимального для API размера (склеивает data, сохраняет totals). Игнорирует `limit`; ограничен maxPages и лимитами по строкам/байтам (при их достижении выставляет _truncated)."

changedInput schema / properties / counterId / description

Previous value: -"Counter id. Defaults to YANDEX_METRIKA_COUNTER_ID."New value: +"Идентификатор счётчика. По умолчанию YANDEX_METRIKA_COUNTER_ID."

changedInput schema / properties / date1 / description

Previous value: -"Start date YYYY-MM-DD or relative (today, yesterday, NdaysAgo). Default 7daysAgo."New value: +"Дата начала: YYYY-MM-DD или относительная (today, yesterday, NdaysAgo). По умолчанию 7daysAgo."

changedInput schema / properties / date2 / description

Previous value: -"End date YYYY-MM-DD or relative (today, yesterday, NdaysAgo). Default yesterday."New value: +"Дата конца: YYYY-MM-DD или относительная (today, yesterday, NdaysAgo). По умолчанию yesterday."

changedInput schema / properties / dimensions / description

Previous value: -"Group-by dimensions, e.g. ym:s:date, ym:s:lastTrafficSource, ym:s:deviceCategory. Omit for a period total."New value: +"Измерения для группировки, например ym:s:date, ym:s:lastTrafficSource, ym:s:deviceCategory. Без них — итог за период."

changedInput schema / properties / filters / description

Previous value: -"Metrica filter expression, e.g. ym:s:deviceCategory=='mobile'."New value: +"Выражение фильтра Метрики, например ym:s:deviceCategory=='mobile'."

changedInput schema / properties / limit / description

Previous value: -"Max rows per page (ignored when autoPaginate is set)."New value: +"Максимум строк на странице (игнорируется, если задан autoPaginate)."

changedInput schema / properties / maxPages / description

Previous value: -"Page cap for autoPaginate. Default 100."New value: +"Лимит страниц для autoPaginate. По умолчанию 100."

changedInput schema / properties / metrics / description

Previous value: -"Metrics, e.g. ym:s:visits, ym:s:users, ym:s:bounceRate, ym:s:goal<id>reaches. Defaults to a common set."New value: +"Метрики, например ym:s:visits, ym:s:users, ym:s:bounceRate, ym:s:goal<id>reaches. По умолчанию — типовой набор."

changedInput schema / properties / offset / description

Previous value: -"1-based row offset for pagination."New value: +"Смещение по строкам для постраничной выдачи, отсчёт с 1."

changedInput schema / properties / sort / description

Previous value: -"Sort field; prefix with '-' for descending, e.g. -ym:s:visits."New value: +"Поле сортировки; префикс '-' — по убыванию, например -ym:s:visits."

Changed11 schema fields changedv1.0.2Jul 7, 2026

addedInput schema / properties / accuracy / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "maximum": 1,
+    "minimum": 0,
+    "type": "number"
+  }
+]

changedInput schema / properties / accuracy / description

Previous value: -"Sampling accuracy: 'full' for exact (slower), or 0..1. Default the API's auto."New value: +"Sampling accuracy: 'full' for exact (slower), or a 0..1 share. Default the API's auto."

removedInput schema / properties / accuracy / type
```
Removed value: -"string"
```

changedInput schema / properties / autoPaginate / description

Previous value: -"Fetch all rows by following limit/offset (merges data, carries totals)."New value: +"Fetch all rows by following the API-max page size (merges data, carries totals). Ignores `limit`; capped by maxPages and by row/byte limits (flags _truncated when hit)."

removedInput schema / properties / date2 / $ref
```
Removed value: -"#/properties/date1"
```

changedInput schema / properties / date2 / description

Previous value: -"End date YYYY-MM-DD or relative. Default yesterday."New value: +"End date YYYY-MM-DD or relative (today, yesterday, NdaysAgo). Default yesterday."

addedInput schema / properties / date2 / pattern

Added value: +"^(\\d{4}-\\d{2}-\\d{2}|today|yesterday|\\d+daysAgo)$"

addedInput schema / properties / date2 / type
```
Added value: +"string"
```

changedInput schema / properties / limit / description

Previous value: -"Max rows per page."New value: +"Max rows per page (ignored when autoPaginate is set)."

changedInput schema / properties / limit / maximum
```
Previous value: -100000New value: +10000
```

addedInput schema / properties / maxPages

Added value: +{
+  "description": "Page cap for autoPaginate. Default 100.",
+  "maximum": 1000,
+  "minimum": 1,
+  "type": "integer"
+}

First observedv1.0.0Jun 27, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations already covering read-only, idempotent, non-destructive, and open-world behavior, the description adds substantial context: default aggregation, totals semantics, total_rows, sampled/sample_share meaning, and the accuracy=full workaround for exact data. These are real behavioral traits not captured by the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well front-loaded: purpose and default output come first, followed by dimensions, metrics, response semantics, and the required counterId. Every sentence carries useful information, and backticked names keep it readable despite the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter API tool with no output schema, the description covers the most important return semantics: default fields, totals, total_rows, and sampling. It does not summarize pagination, filters, date defaults, or the Direct login 403 behavior, but the 100%-covered input schema carries those details adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description still adds useful semantics beyond the schema by explaining that dimensions turn the result into rows, giving conversion metric examples such as goal reaches/conversionRate, and identifying list_goals as the source of goal IDs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

It states a specific verb and resource: querying the Yandex Metrica Reporting API (stat/v1/data) for a counter. It immediately distinguishes the default aggregated behavior from dimension-based row breakdown, so an agent knows exactly what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context for dimensions, metrics, conversions, and sampling, and it points to list_counters and list_goals for required IDs. However, it does not explicitly say when to use this tool instead of sibling tools such as raw_request, nor does it state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Статистика

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools