# Яндекс Метрика MCP [![npm](https://img.shields.io/npm/v/mcp-yandex-metrica)](https://www.npmjs.com/package/mcp-yandex-metrica) [![CI](https://github.com/askads/mcp-yandex-metrica/actions/workflows/ci.yml/badge.svg)](https://github.com/askads/mcp-yandex-metrica/actions/workflows/ci.yml) [![Glama](https://glama.ai/mcp/servers/askads/mcp-yandex-metrica/badges/score.svg)](https://glama.ai/mcp/servers/askads/mcp-yandex-metrica) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) **Яндекс Метрика MCP** подключает AI-приложение к веб-аналитике сайта. Спросите на естественном языке, откуда приходят посетители, как меняется конверсия или где растёт доля отказов — ассистент возьмёт данные из вашего счётчика и объяснит результат. Подключение начинается прямо в диалоге: не нужно заранее создавать токен или редактировать конфигурацию. - **Восемь инструментов.** Счётчики, цели и отчёты Метрики, подключение и отключение доступа, а также один универсальный запрос к API. - **Отчёты и конверсии.** Визиты, пользователи, просмотры, отказы, длительность визита, источники, устройства и цели за выбранный период. - **Подключение в чате.** Яндекс откроет страницу входа; одноразовый код действует 10 минут, а сервер проверит доступ к счётчикам сразу после подключения. - **Обычные запросы — только чтение.** Специализированные инструменты не меняют счётчики, цели или данные Метрики. - **Без молчаливого обрезания.** В отчёте видны итоговые значения и признак выборки; при большой выдаче сервер отмечает, если упёрся в лимит. Попробуйте первым сообщением: > Сколько визитов, пользователей и отказов было у моего сайта за последнюю неделю? [Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация) --- ## Увидеть работу за минуту > **Вы:** Подключи Яндекс Метрику. > > **Ассистент:** Даёт ссылку на вход в Яндекс. Откройте её под аккаунтом, у которого есть доступ к нужным счётчикам, подтвердите доступ и пришлите показанный код. > > **Вы:** Отправляет код из страницы Яндекса. > > **Ассистент:** Подключает Метрику, проверяет, видны ли счётчики, и сообщает результат. Перезапускать приложение не нужно. > > **Вы:** За последние 30 дней покажи источники трафика и конверсию по цели «Оформление заказа». > > **Ассистент:** Находит цель, строит отчёт по источникам и показывает визиты, достижения цели и конверсию. Если Метрика применила выборку, отмечает, что цифры приблизительные. ## Содержание - [Быстрый старт](#быстрый-старт) - [Что можно поручить](#что-можно-поручить) - [Как это работает](#как-это-работает) - [Что может изменить данные](#что-может-изменить-данные) - [Подключение и настройка](#подключение-и-настройка) - [Данные и телеметрия](#данные-и-телеметрия) - [Ограничения](#ограничения) - [Техническая документация](#техническая-документация) - [Поддержка](#поддержка) ## Быстрый старт Нужен Node.js 20 или новее. Сервер запускается через `npx`, поэтому отдельно устанавливать пакет не требуется. 1. Добавьте сервер в AI-приложение — ниже открыт пример для Codex, остальные приложения собраны в сворачиваемые инструкции. 2. Напишите: «Подключи Яндекс Метрику». Ассистент проведёт через вход в Яндекс и сразу проверит, что ему видны ваши счётчики. 3. Задайте первый вопрос, например: «Какие источники дали больше всего визитов за прошлый месяц?»
Codex
**Через интерфейс приложения:** 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)
Claude Code
```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)
Claude Desktop
Откройте **Settings → Developer → Edit Config** и добавьте сервер в `claude_desktop_config.json`: ```json { "mcpServers": { "yandex-metrica": { "command": "npx", "args": ["-y", "mcp-yandex-metrica@latest"] } } } ``` После сохранения откройте новый диалог и попросите подключить Метрику.
Cursor
Для всех проектов создайте `~/.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)
VS Code
Откройте палитру команд и выполните **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)
## Что можно поручить ### Понять, что происходит с сайтом - «Сколько было визитов, пользователей и просмотров за последнюю неделю?» - «Покажи динамику посещаемости по дням за июнь». - «На каких устройствах доля отказов выше?» ### Найти источник трафика и оценить его качество - «Покажи источники трафика за месяц и отсортируй по визитам». - «Сравни органический поиск и рекламу по пользователям и отказам». - «Какие источники дали больше всего переходов на этой неделе?» ### Разобраться с конверсиями - «Какие цели настроены в счётчике?» - «Какая конверсия по цели „Оформление заказа“ за 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).