Yandex Metrica MCP
MCP server for Yandex Metrica API: list counters, goals and pull web-analytics statistics.
Open source Open in the app JSON README (API)
About
MCP server for Yandex Metrica API: list counters, goals and pull web-analytics statistics.
Details
- Kind
- MCP servers
- Topic
- Government & public data
- Publisher
- askads
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.4.1
- Stars
- 1
- Last push
- 2026-08-21T15:30:24Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:27
- Updated
- 2026-08-29 03:02:27
- Origin id
io.github.askads/mcp-yandex-metrica
README
# Яндекс Метрика 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** подключает AI-приложение к веб-аналитике сайта. Спросите на естественном языке, откуда приходят посетители, как меняется конверсия или где растёт доля отказов — ассистент возьмёт данные из вашего счётчика и объяснит результат. Подключение начинается прямо в диалоге: не нужно заранее создавать токен или редактировать конфигурацию.
- **Восемь инструментов.** Счётчики, цели и отчёты Метрики, подключение и отключение доступа, а также один универсальный запрос к API.
- **Отчёты и конверсии.** Визиты, пользователи, просмотры, отказы, длительность визита, источники, устройства и цели за выбранный период.
- **Подключение в чате.** Яндекс откроет страницу входа; одноразовый код действует 10 минут, а сервер проверит доступ к счётчикам сразу после подключения.
- **Обычные запросы — только чтение.** Специализированные инструменты не меняют счётчики, цели или данные Метрики.
- **Без молчаливого обрезания.** В отчёте видны итоговые значения и признак выборки; при большой выдаче сервер отмечает, если упёрся в лимит.
Попробуйте первым сообщением:
> Сколько визитов, пользователей и отказов было у моего сайта за последнюю неделю?
[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация)
---
## Увидеть работу за минуту
> **Вы:** Подключи Яндекс Метрику.
>
> **Ассистент:** Даёт ссылку на вход в Яндекс. Откройте её под аккаунтом, у которого есть доступ к нужным счётчикам, подтвердите доступ и пришлите показанный код.
>
> **Вы:** Отправляет код из страницы Яндекса.
>
> **Ассистент:** Подключает Метрику, проверяет, видны ли счётчики, и сообщает результат. Перезапускать приложение не нужно.
>
> **Вы:** За последние 30 дней покажи источники трафика и конверсию по цели «Оформление заказа».
>
> **Ассистент:** Находит цель, строит отчёт по источникам и показывает визиты, достижения цели и конверсию. Если Метрика применила выборку, отмечает, что цифры приблизительные.
## Содержание
- [Быстрый старт](#быстрый-старт)
- [Что можно поручить](#что-можно-поручить)
- [Как это работает](#как-это-работает)
- [Что может изменить данные](#что-может-изменить-данные)
- [Подключение и настройка](#подключение-и-настройка)
- [Данные и телеметрия](#данные-и-телеметрия)
- [Ограничения](#ограничения)
- [Техническая документация](#техническая-документация)
- [Поддержка](#поддержка)
## Быстрый старт
Нужен Node.js 20 или новее. Сервер запускается через `npx`, поэтому отдельно устанавливать пакет не требуется.
1. Добавьте сервер в AI-приложение — ниже открыт пример для Codex, остальные приложения собраны в сворачиваемые инструкции.
2. Напишите: «Подключи Яндекс Метрику». Ассистент проведёт через вход в Яндекс и сразу проверит, что ему видны ваши счётчики.
3. Задайте первый вопрос, например: «Какие источники дали больше всего визитов за прошлый месяц?»
<details open>
<summary><strong>Codex</strong></summary>
<br>
**Через интерфейс приложения:**
1. Откройте **Settings → Plugins → MCP servers**.
2. Нажмите **Add server**.
3. Добавьте команду запуска `npx -y mcp-yandex-metrica@latest`.
**Через командную строку:**
```bash
codex mcp add yandex-metrica -- npx -y mcp-yandex-metrica@latest
```
Проверьте подключение:
```bash
codex mcp list
```
Затем в чате Codex попросите: «Подключи Яндекс Метрику».
[Официальная инструкция Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
</details>
<details>
<summary><strong>Claude Code</strong></summary>
<br>
```bash
claude mcp add --transport stdio --scope user yandex-metrica -- npx -y mcp-yandex-metrica@latest
```
Проверьте сервер командой:
```bash
claude mcp list
```
Затем начните диалог с просьбы подключить Метрику.
[Документация Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp)
</details>
<details>
<summary><strong>Claude Desktop</strong></summary>
<br>
Откройте **Settings → Developer → Edit Config** и добавьте сервер в `claude_desktop_config.json`:
```json
{
"mcpServers": {
"yandex-metrica": {
"command": "npx",
"args": ["-y", "mcp-yandex-metrica@latest"]
}
}
}
```
После сохранения откройте новый диалог и попросите подключить Метрику.
</details>
<details>
<summary><strong>Cursor</strong></summary>
<br>
Для всех проектов создайте `~/.cursor/mcp.json`; только для текущего проекта — `.cursor/mcp.json`:
```json
{
"mcpServers": {
"yandex-metrica": {
"command": "npx",
"args": ["-y", "mcp-yandex-metrica@latest"]
}
}
}
```
В чате Cursor сервер появится среди доступных инструментов. Попросите подключить Метрику и пройдите вход через Яндекс.
[Документация Cursor](https://docs.cursor.com/context/model-context-protocol)
</details>
<details>
<summary><strong>VS Code</strong></summary>
<br>
Откройте палитру команд и выполните **MCP: Open User Configuration**. Добавьте в `mcp.json`:
```json
{
"servers": {
"yandex-metrica": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-yandex-metrica@latest"]
}
}
}
```
Проверьте запуск командой **MCP: List Servers**, затем откройте чат и попросите подключить Метрику.
[Документация VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
</details>
## Что можно поручить
### Понять, что происходит с сайтом
- «Сколько было визитов, пользователей и просмотров за последнюю неделю?»
- «Покажи динамику посещаемости по дням за июнь».
- «На каких устройствах доля отказов выше?»
### Найти источник трафика и оценить его качество
- «Покажи источники трафика за месяц и отсортируй по визитам».
- «Сравни органический поиск и рекламу по пользователям и отказам».
- «Какие источники дали больше всего переходов на этой неделе?»
### Разобраться с конверсиями
- «Какие цели настроены в счётчике?»
- «Какая конверсия по цели „Оформление заказа“ за 30 дней?»
- «Покажи источники, которые принесли больше всего достижений цели».
### Проверить доступ и точность данных
- «Какие счётчики мне доступны?»
- «Покажи статус подключения к Метрике».
- «Данные в этом отчёте точные или Метрика использовала выборку?»
## Как это работает
Сервер работает с тремя привычными сущностями:
| Сущность | Что можно узнать |
|---|---|
| **Счётчик** | Название сайта, его идентификатор и доступность для вашего аккаунта. |
| **Цель** | Настроенные на счётчике конверсии и их идентификаторы. |
| **Отчёт** | Метрики и срезы за период: например, визиты по дням, источникам или устройствам. |
Обычно ассистент сначала находит доступный счётчик, затем — при необходимости — цель, и только после этого строит отчёт. В ответе Метрики есть итог по всем строкам, размер выдачи и признак выборки.
## Что может изменить данные
| Действие | Что происходит |
|---|---|
| Список счётчиков, целей и отчёты | Только чтение данных Метрики. |
| Подключение | Сохраняет токен доступа локально на вашем компьютере и проверяет его чтением счётчиков. В Метрике ничего не меняет. |
| Отключение | Удаляет только сохранённый на компьютере токен. Доступ приложения в Яндекс ID остаётся; его можно отозвать там отдельно. |
| Произвольный запрос к API | `GET` читает данные. `POST` и `DELETE` могут менять реальные объекты Метрики и выполняются только с `confirmWrite=true`. |
Сервер помечает произвольную запись как потенциально разрушительное действие. Как именно AI-приложение запрашивает подтверждение, зависит от самого приложения; перед таким запросом проверьте путь, метод и данные.
## Подключение и настройка
Для обычного использования токен заранее не нужен:
1. В чате попросите подключить Яндекс Метрику.
2. Откройте ссылку на Яндекс OAuth под аккаунтом с доступом к нужным счётчикам.
3. Подтвердите доступ и пришлите код ассистенту. Он действует 10 минут и меняется на токен только внутри работающего сервера.
Сервер использует PKCE: код из чата сам по себе нельзя обменять на токен. Полученный токен хранится локально в `~/.config/mcp-yandex-metrica/credentials.json` с правами только для владельца. При сохранённом refresh-токене доступ продлевается автоматически.
Для CI и нестандартных установок доступна настройка через переменные окружения:
| Переменная | Назначение |
|---|---|
| `YANDEX_METRIKA_TOKEN` | Готовый OAuth-токен с правом `metrika:read`; имеет приоритет над подключением из чата. |
| `YANDEX_METRIKA_COUNTER_ID` | Счётчик по умолчанию для запросов без `counterId`. |
| `YANDEX_METRIKA_OAUTH_CLIENT_ID` | Client ID собственного OAuth-приложения вместо приложения Ask Ads. |
| `YANDEX_METRIKA_LANG` | Язык подписей в ответах API; по умолчанию `ru`. |
| `YANDEX_METRIKA_TIMEOUT_MS` | Таймаут запроса; по умолчанию 60 000 мс. |
| `YANDEX_METRIKA_MAX_RETRIES` | Число повторов при временных ошибках; по умолчанию 3. |
| `YANDEX_METRIKA_API_BASE` | Базовый адрес API; по умолчанию `https://api-metrika.yandex.net`. |
Если используете собственное OAuth-приложение, запросите в нём право **«Получение статистики, чтение параметров своих и доверенных счётчиков»** (`metrika:read`).
## Данные и телеметрия
По умолчанию сервер отправляет анонимную техническую телеметрию: случайный идентификатор установки, имя события или инструмента, версию сервера, версию Node.js, ОС и сведения о подключившемся AI-клиенте. В неё не попадают токен, данные счётчиков, аргументы инструментов, ваши сообщения и значения переменных окружения.
Чтобы отключить телеметрию для MCP-серверов Ask Ads, задайте переменную окружения:
```bash
ASKADS_TELEMETRY=0
```
## Ограничения
- **Выборка Метрики.** На больших периодах или сложных отчётах API может вернуть приблизительные данные. Смотрите поля `sampled` и `sample_share`; для более точного расчёта сузьте период или используйте `accuracy: "full"`.
- **Размер отчёта.** Один запрос возвращает до 10 000 строк. Автоматическая пагинация останавливается не более чем на 100 страницах, 100 000 строках или примерно 1 МБ данных и помечает неполный ответ полем `_truncated`.
- **Повторы запросов.** Таймаут одного запроса — 60 секунд. Сервер делает до трёх повторов при временной ошибке: `GET` — при сетевой ошибке, `429` и `5xx`; `POST` и `DELETE` — только при `429`, чтобы не повторить изменяющее действие. Задержка учитывает `Retry-After` и не превышает 30 секунд.
- **Боевые данные.** У Метрики нет песочницы. Специализированные инструменты читают данные, но `POST` и `DELETE` через произвольный запрос меняют реальные объекты.
- **Нет фонового наблюдения.** Сервер работает, когда его вызывает AI-приложение, и сам не следит за показателями. Если приложение поддерживает запланированные задания, можно настроить в нём периодический запрос отчёта.
## Техническая документация
- [Каталог MCP-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента.
- [Все инструменты](./docs/TOOLS.md) — параметры, ответы и границы каждого инструмента.
- [Документация по разработке](./docs/DEVELOPMENT.md) — устройство проекта и работа с демо.
- [Пакет в npm](https://www.npmjs.com/package/mcp-yandex-metrica).
- [API Яндекс Метрики](https://yandex.ru/dev/metrika/).
## Поддержка
Нашли ошибку или не хватает сценария? [Создайте issue](https://github.com/askads/mcp-yandex-metrica/issues) или напишите в [Telegram](http://t.me/gistrec).