Yandex Metrica MCP
MCP server for Yandex Metrica API: list counters, goals and pull web-analytics statistics.
Яндекс Метрика MCP
Яндекс Метрика MCP подключает AI-приложение к веб-аналитике сайта. Спросите на естественном языке, откуда приходят посетители, как меняется конверсия или где растёт доля отказов — ассистент возьмёт данные из вашего счётчика и объяснит результат. Подключение начинается прямо в диалоге: не нужно заранее создавать токен или редактировать конфигурацию.
- Восемь инструментов. Счётчики, цели и отчёты Метрики, подключение и отключение доступа, а также один универсальный запрос к API.
- Отчёты и конверсии. Визиты, пользователи, просмотры, отказы, длительность визита, источники, устройства и цели за выбранный период.
- Подключение в чате. Яндекс откроет страницу входа; одноразовый код действует 10 минут, а сервер проверит доступ к счётчикам сразу после подключения.
- Обычные запросы — только чтение. Специализированные инструменты не меняют счётчики, цели или данные Метрики.
- Без молчаливого обрезания. В отчёте видны итоговые значения и признак выборки; при большой выдаче сервер отмечает, если упёрся в лимит.
Попробуйте первым сообщением:
Сколько визитов, пользователей и отказов было у моего сайта за последнюю неделю?
Подключить сервер · Посмотреть сценарии · Открыть техническую документацию
Увидеть работу за минуту
Вы: Подключи Яндекс Метрику.
Ассистент: Даёт ссылку на вход в Яндекс. Откройте её под аккаунтом, у которого есть доступ к нужным счётчикам, подтвердите доступ и пришлите показанный код.
Вы: Отправляет код из страницы Яндекса.
Ассистент: Подключает Метрику, проверяет, видны ли счётчики, и сообщает результат. Перезапускать приложение не нужно.
Вы: За последние 30 дней покажи источники трафика и конверсию по цели «Оформление заказа».
Ассистент: Находит цель, строит отчёт по источникам и показывает визиты, достижения цели и конверсию. Если Метрика применила выборку, отмечает, что цифры приблизительные.
Содержание
- Быстрый старт
- Что можно поручить
- Как это работает
- Что может изменить данные
- Подключение и настройка
- Данные и телеметрия
- Ограничения
- Техническая документация
- Поддержка
Быстрый старт
Нужен Node.js 20 или новее. Сервер запускается через npx, поэтому отдельно устанавливать пакет не требуется.
- Добавьте сервер в AI-приложение — ниже открыт пример для Codex, остальные приложения собраны в сворачиваемые инструкции.
- Напишите: «Подключи Яндекс Метрику». Ассистент проведёт через вход в Яндекс и сразу проверит, что ему видны ваши счётчики.
- Задайте первый вопрос, например: «Какие источники дали больше всего визитов за прошлый месяц?»
Codex
Через интерфейс приложения:
- Откройте Settings → Plugins → MCP servers.
- Нажмите Add server.
- Добавьте команду запуска
npx -y mcp-yandex-metrica@latest.
Через командную строку:
codex mcp add yandex-metrica -- npx -y mcp-yandex-metrica@latest
Проверьте подключение:
codex mcp list
Затем в чате Codex попросите: «Подключи Яндекс Метрику».
Claude Code
claude mcp add --transport stdio --scope user yandex-metrica -- npx -y mcp-yandex-metrica@latest
Проверьте сервер командой:
claude mcp list
Затем начните диалог с просьбы подключить Метрику.
Claude Desktop
Откройте Settings → Developer → Edit Config и добавьте сервер в claude_desktop_config.json:
{
"mcpServers": {
"yandex-metrica": {
"command": "npx",
"args": ["-y", "mcp-yandex-metrica@latest"]
}
}
}
После сохранения откройте новый диалог и попросите подключить Метрику.
Cursor
Для всех проектов создайте ~/.cursor/mcp.json; только для текущего проекта — .cursor/mcp.json:
{
"mcpServers": {
"yandex-metrica": {
"command": "npx",
"args": ["-y", "mcp-yandex-metrica@latest"]
}
}
}
В чате Cursor сервер появится среди доступных инструментов. Попросите подключить Метрику и пройдите вход через Яндекс.
VS Code
Откройте палитру команд и выполните MCP: Open User Configuration. Добавьте в mcp.json:
{
"servers": {
"yandex-metrica": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-yandex-metrica@latest"]
}
}
}
Проверьте запуск командой MCP: List Servers, затем откройте чат и попросите подключить Метрику.
Что можно поручить
Понять, что происходит с сайтом
- «Сколько было визитов, пользователей и просмотров за последнюю неделю?»
- «Покажи динамику посещаемости по дням за июнь».
- «На каких устройствах доля отказов выше?»
Найти источник трафика и оценить его качество
- «Покажи источники трафика за месяц и отсортируй по визитам».
- «Сравни органический поиск и рекламу по пользователям и отказам».
- «Какие источники дали больше всего переходов на этой неделе?»
Разобраться с конверсиями
- «Какие цели настроены в счётчике?»
- «Какая конверсия по цели „Оформление заказа“ за 30 дней?»
- «Покажи источники, которые принесли больше всего достижений цели».
Проверить доступ и точность данных
- «Какие счётчики мне доступны?»
- «Покажи статус подключения к Метрике».
- «Данные в этом отчёте точные или Метрика использовала выборку?»
Как это работает
Сервер работает с тремя привычными сущностями:
| Сущность | Что можно узнать |
|---|---|
| Счётчик | Название сайта, его идентификатор и доступность для вашего аккаунта. |
| Цель | Настроенные на счётчике конверсии и их идентификаторы. |
| Отчёт | Метрики и срезы за период: например, визиты по дням, источникам или устройствам. |
Обычно ассистент сначала находит доступный счётчик, затем — при необходимости — цель, и только после этого строит отчёт. В ответе Метрики есть итог по всем строкам, размер выдачи и признак выборки.
Что может изменить данные
| Действие | Что происходит |
|---|---|
| Список счётчиков, целей и отчёты | Только чтение данных Метрики. |
| Подключение | Сохраняет токен доступа локально на вашем компьютере и проверяет его чтением счётчиков. В Метрике ничего не меняет. |
| Отключение | Удаляет только сохранённый на компьютере токен. Доступ приложения в Яндекс ID остаётся; его можно отозвать там отдельно. |
| Произвольный запрос к API | GET читает данные. POST и DELETE могут менять реальные объекты Метрики и выполняются только с confirmWrite=true. |
Сервер помечает произвольную запись как потенциально разрушительное действие. Как именно AI-приложение запрашивает подтверждение, зависит от самого приложения; перед таким запросом проверьте путь, метод и данные.
Подключение и настройка
Для обычного использования токен заранее не нужен:
- В чате попросите подключить Яндекс Метрику.
- Откройте ссылку на Яндекс OAuth под аккаунтом с доступом к нужным счётчикам.
- Подтвердите доступ и пришлите код ассистенту. Он действует 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.
Installation
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y mcp-yandex-metricaSet up in your AI client
Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-askads-mcp-yandex-metrica": {
"command": "npx",
"args": [
"-y",
"mcp-yandex-metrica"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencePackage
Compatible MCP Clients
Yandex Metrica MCP works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
- Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect. - Cursor
~/.cursor/mcp.jsonRestart Cursor for changes to take effect. - VS Code
.vscode/mcp.jsonReload VS Code window for changes to take effect. - Windsurf
~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect. - Claude Code
.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.