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

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

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

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

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

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

---

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

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

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

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

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

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

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

Содержание

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

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

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

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

Через интерфейс приложения:

1. Откройте Settings → Plugins → MCP servers.
2. Нажмите Add server.
3. Добавьте команду запуска npx -y mcp-yandex-metrica@latest.

Через командную строку:

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

Проверьте подключение:

codex mcp list

Затем в чате Codex попросите: «Подключи Яндекс Метрику».

Официальная инструкция Codex

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

Проверьте сервер командой:

claude mcp list

Затем начните диалог с просьбы подключить Метрику.

Документация Claude Code

Откройте Settings → Developer → Edit Config и добавьте сервер в claude_desktop_config.json:

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

После сохранения откройте новый диалог и попросите подключить Метрику.

Для всех проектов создайте ~/.cursor/mcp.json; только для текущего проекта — .cursor/mcp.json:

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

В чате Cursor сервер появится среди доступных инструментов. Попросите подключить Метрику и пройдите вход через Яндекс.

Документация Cursor

Откройте палитру команд и выполните MCP: Open User Configuration. Добавьте в mcp.json:

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

Проверьте запуск командой MCP: List Servers, затем откройте чат и попросите подключить Метрику.

Документация VS Code

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

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

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

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

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

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

• «Какие цели настроены в счётчике?»
• «Какая конверсия по цели „Оформление заказа“ за 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, задайте переменную окружения:

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.