Yandex Analytics

yandex-mcp

Спрашивай свою аналитику Яндекса словами. Метрика, Вебмастер, Директ и Вордстат в одном MCP-сервере.

> Как изменился трафик за последний месяц и откуда пришёл рост?
> По каким запросам мы на второй странице — там, где до топа осталось чуть-чуть?
> Сколько стоила заявка в Директе на прошлой неделе по каждой кампании?

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

Сервер — обычная программа на твоём компьютере. Агент просит у неё данные, она идёт в API Яндекса и возвращает готовый текст. Никаких промежуточных серверов: твой токен и твои цифры не проходят через чужие руки.

Зависимостей нет вообще — ни одной сторонней библиотеки. Через этот процесс идёт доступ к твоей аналитике и рекламному кабинету, и чем меньше здесь чужого кода, тем лучше.

Установка

Claude Code — две команды, вместе с сервером ставятся скиллы:

/plugin marketplace add nozikov/yandex-mcp
/plugin install yandex-mcp@nozikov

Codex CLI — дописать в ~/.codex/config.toml и перезапустить Codex:

[mcp_servers.yandex]
command = "uvx"
args = ["yandex-mcp"]
env = { YANDEX_MCP_DEFAULT_COUNTER = "12345678" }

Любой другой клиент — через PyPI:

claude mcp add yandex -e YANDEX_MCP_DEFAULT_COUNTER=12345678 -- uvx yandex-mcp

Или вручную в конфиге, см. .mcp.json.example:

{
  "mcpServers": {
    "yandex": {
      "command": "uvx",
      "args": ["yandex-mcp"],
      "env": { "YANDEX_MCP_DEFAULT_COUNTER": "12345678" }
    }
  }
}

Счётчик указывать необязательно — без него его придётся называть в каждом вопросе.

Вход

Терминал не нужен: скажи агенту «подключи Яндекс», и он проведёт по шагам.

Один раз перед этим нужно зарегистрировать своё приложение в Яндексе — это бесплатно и занимает пять минут. Команда yandex-mcp setup откроет нужную страницу и подскажет, что заполнять. Пароль от приложения не понадобится: используется PKCE.

Единственный шаг, который агент не сделает за тебя, — сама регистрация: это твой аккаунт. А полученный ClientID можно просто продиктовать ему, он не секрет:

yandex-mcp setup --client-id <ClientID>

Что вписать при регистрации приложения

Яндекс спросит тип приложения. Подходят оба, разница только в способе входа:

В разделе «Доступ к данным» добавь права по названию:

metrika:read
webmaster:hostinfo
webmaster:verify
direct:api           ← нужна заявка в кабинете Директа, рассматривают до 7 дней

Вход просит все права разом. Если direct:api ещё не одобрен, Яндекс откажет — сервер это заметит, войдёт без Директа и скажет об этом. Метрика и Вебмастер заработают сразу, а когда заявку одобрят, повторный вход подхватит Директ.

Команды в терминале: setup, login, status, logout.

Что умеет

Метрика

Вебмастер

Директ и Вордстат

Подключение

Скиллы

Ставятся вместе с плагином Claude Code:

Где лежит токен

Ничего настраивать не нужно — подходящее хранилище выбирается само. Форсировать можно переменной YANDEX_MCP_KEYSTORE.

Записи лежат под общим префиксом, чтобы logout не задел чужое:

yandex-mcp-token             общий токен
yandex-mcp-metrika-token     токен одного сервиса, если нужен узкий доступ
yandex-mcp-client-id         ID приложения Яндекса

Токен можно передать и напрямую, минуя хранилище: YANDEX_MCP_SECRET_TOKEN для общего, YANDEX_MCP_SECRET_METRIKA_TOKEN для узкого. Так удобно в Docker и CI.

Почему 15 инструментов, а не 130

Описания всех инструментов уходят в контекст модели при каждом запросе, пока сервер подключён. Здесь это около 1 800 токенов. У серверов со 130–150 инструментами — за 40 000, и это постоянный налог на каждый диалог.

Оставлено то, на что реально смотрят: цифры и их динамика. Управлять кампаниями и ставками отсюда нельзя — для этого есть кабинет Директа, и цена ошибки там другая.

Переменные окружения

О чём стоит знать

• Инструменты Директа и Вордстата требуют одобренной заявки на API Директа. До неё Директ отвечает ошибкой 58.
• Отчёт Вордстата готовится у Яндекса около трёх минут. Если вернулось «ещё готовится» — повтори запрос с теми же фразами, готовый результат подхватится сразу.
• Отчёт Директа тоже может готовиться минутами. Сервер ждёт сам, но в очереди Яндекса помещается не больше пяти таких отчётов на аккаунт.
• Переобход страниц ограничен: 20 URL за вызов при суточной квоте 150 на сайт.
• Ответ обрезается на 20 000 символах. Для больших выгрузок сужай период.
• Токен живёт около полугода, потом нужно войти заново. Обновлять его автоматически Яндекс разрешает только приложениям с паролем, а у PKCE-приложения его нет.
• Там, где системного хранилища нет (Windows, сервер без графики, контейнер), токен лежит в файле с правами 0600 — как ~/.aws/credentials или SSH-ключ без пароля.

Безопасность

Токен не появляется ни в ответе инструмента, ни в тексте ошибки: есть отдельный фильтр, вычищающий его из любого текста. status показывает только отпечаток.

Почти всё — чтение. Единственное изменяющее действие, переобход страниц, требует явного подтверждения в аргументах вызова.

Данные из API считаются недоверенными: поисковые фразы, UTM-метки и названия кампаний пишут посторонние люди. К каждому ответу добавляется пометка, что это данные для анализа, а не инструкции агенту.

Разработка

pip install -e ".[dev]"
pytest

Тесты не ходят в сеть и не трогают системное хранилище. CI гоняет их на Linux, macOS и Windows, на Python от 3.8 до 3.14.

src/yandex_mcp/
  cli.py         точка входа: без аргументов сервер, с аргументами настройка
  server.py      JSON-RPC поверх stdio
  registry.py    сборка списка инструментов
  httpclient.py  запросы к Яндексу
  scrub.py       вычищение секретов из ответов
  auth/          хранилище, токены, вход по PKCE
  tools/         по модулю на сервис

Код лежит в src/, чтобы import yandex_mcp брал установленный пакет, а не случайно подхваченную рабочую директорию — иначе тесты могут проходить на коде, которого нет в собранном колесе.

Диаграммы в docs/ собираются из scripts/make_diagrams.py, а scripts/check_metadata.py следит, чтобы README не разошёлся с кодом: версии, список инструментов и переменные окружения проверяются на каждом прогоне CI.

Лицензия

MIT