Yandex Metrica MCP

Яндекс Метрика MCP

[npm] [CI] [Glama] [License: MIT]

Яндекс Метрика MCP подключает AI-приложение к веб-аналитике сайта. Спросите на естественном языке, откуда приходят посетители, как меняется конверсия или где растёт доля отказов — ассистент возьмёт данные из вашего счётчика и объяснит результат. Подключение начинается прямо в диалоге: не нужно заранее создавать токен или редактировать конфигурацию.

• Восемь инструментов. Счётчики, цели и отчёты Метрики, подключение и отключение доступа, а также один универсальный запрос к API.
• Отчёты и конверсии. Визиты, пользователи, просмотры, отказы, длительность визита, источники, устройства и цели за выбранный период.
• Подключение в чате. Яндекс откроет страницу входа; одноразовый код действует 10 минут, а сервер проверит доступ к счётчикам сразу после подключения.
• Обычные запросы — только чтение. Специализированные инструменты не меняют счётчики, цели или данные Метрики.
• Без молчаливого обрезания. В отчёте видны итоговые значения и признак выборки; при большой выдаче сервер отмечает, если упёрся в лимит.

Попробуйте первым сообщением:

Сколько визитов, пользователей и отказов было у моего сайта за последнюю неделю?

Подключить сервер · Посмотреть сценарии · Открыть техническую документацию

Увидеть работу за минуту

Вы: Подключи Яндекс Метрику.

Ассистент: Даёт ссылку на вход в Яндекс. Откройте её под аккаунтом, у которого есть доступ к нужным счётчикам, подтвердите доступ и пришлите показанный код.

Вы: Отправляет код из страницы Яндекса.

Ассистент: Подключает Метрику, проверяет, видны ли счётчики, и сообщает результат. Перезапускать приложение не нужно.

Вы: За последние 30 дней покажи источники трафика и конверсию по цели «Оформление заказа».

Ассистент: Находит цель, строит отчёт по источникам и показывает визиты, достижения цели и конверсию. Если Метрика применила выборку, отмечает, что цифры приблизительные.

Содержание

• Быстрый старт
• Что можно поручить
• Как это работает
• Что может изменить данные
• Подключение и настройка
• Данные и телеметрия
• Ограничения
• Техническая документация
• Поддержка

Быстрый старт

Нужен Node.js 20 или новее. Сервер запускается через npx, поэтому отдельно устанавливать пакет не требуется.

1. Добавьте сервер в AI-приложение — ниже открыт пример для Codex, остальные приложения собраны в сворачиваемые инструкции.
2. Напишите: «Подключи Яндекс Метрику». Ассистент проведёт через вход в Яндекс и сразу проверит, что ему видны ваши счётчики.
3. Задайте первый вопрос, например: «Какие источники дали больше всего визитов за прошлый месяц?»

codex mcp add yandex-metrica -- npx -y mcp-yandex-metrica@latest

codex mcp list

claude mcp add --transport stdio --scope user yandex-metrica -- npx -y mcp-yandex-metrica@latest

claude mcp list

{  "mcpServers": {    "yandex-metrica": {      "command": "npx",      "args": ["-y", "mcp-yandex-metrica@latest"]    }  }}

{  "mcpServers": {    "yandex-metrica": {      "command": "npx",      "args": ["-y", "mcp-yandex-metrica@latest"]    }  }}

{  "servers": {    "yandex-metrica": {      "type": "stdio",      "command": "npx",      "args": ["-y", "mcp-yandex-metrica@latest"]    }  }}

Что можно поручить

Понять, что происходит с сайтом

• «Сколько было визитов, пользователей и просмотров за последнюю неделю?»
• «Покажи динамику посещаемости по дням за июнь».
• «На каких устройствах доля отказов выше?»

Найти источник трафика и оценить его качество

• «Покажи источники трафика за месяц и отсортируй по визитам».
• «Сравни органический поиск и рекламу по пользователям и отказам».
• «Какие источники дали больше всего переходов на этой неделе?»

Разобраться с конверсиями

• «Какие цели настроены в счётчике?»
• «Какая конверсия по цели „Оформление заказа“ за 30 дней?»
• «Покажи источники, которые принесли больше всего достижений цели».

Проверить доступ и точность данных

• «Какие счётчики мне доступны?»
• «Покажи статус подключения к Метрике».
• «Данные в этом отчёте точные или Метрика использовала выборку?»

Как это работает

Сервер работает с тремя привычными сущностями:

Обычно ассистент сначала находит доступный счётчик, затем — при необходимости — цель, и только после этого строит отчёт. В ответе Метрики есть итог по всем строкам, размер выдачи и признак выборки.

Что может изменить данные

Сервер помечает произвольную запись как потенциально разрушительное действие. Как именно AI-приложение запрашивает подтверждение, зависит от самого приложения; перед таким запросом проверьте путь, метод и данные.

Подключение и настройка

Для обычного использования токен заранее не нужен:

1. В чате попросите подключить Яндекс Метрику.
2. Откройте ссылку на Яндекс OAuth под аккаунтом с доступом к нужным счётчикам.
3. Подтвердите доступ и пришлите код ассистенту. Он действует 10 минут и меняется на токен только внутри работающего сервера.

Сервер использует PKCE: код из чата сам по себе нельзя обменять на токен. Полученный токен хранится локально в ~/.config/mcp-yandex-metrica/credentials.json с правами только для владельца. При сохранённом refresh-токене доступ продлевается автоматически.

Для CI и нестандартных установок доступна настройка через переменные окружения:

Если используете собственное OAuth-приложение, запросите в нём право «Получение статистики, чтение параметров своих и доверенных счётчиков» (metrika:read).

Данные и телеметрия

По умолчанию сервер отправляет анонимную техническую телеметрию: случайный идентификатор установки, имя события или инструмента, версию сервера, версию Node.js, ОС и сведения о подключившемся AI-клиенте. При вызове инструмента сервер также отправляет его исход, а при ошибке - фрагмент её текста: код и сообщение, в которых e-mail, адреса, токены, числа от 4 цифр и текст в кавычках заменены на «#». Если в тексте ошибки есть значение из запроса, оно тоже может попасть во фрагмент. В телеметрию не попадают токен, данные счётчиков, аргументы инструментов, ваши сообщения и значения переменных окружения.

Чтобы отключить телеметрию для MCP-серверов Ask Ads, задайте переменную окружения:

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-возможностей — страницы по пользовательским задачам для каждого инструмента.
• Все инструменты — параметры, ответы и границы каждого инструмента.
• Документация по разработке — устройство проекта и работа с демо.
• Пакет в npm.
• API Яндекс Метрики.

Поддержка

Нашли ошибку или не хватает сценария? Создайте issue или напишите в Telegram.