Skip to main content
Glama
yandex-mcp

yandex-mcp

by nozikov

yandex-mcp

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

tests PyPI Python License: MIT

Yandex Analytics MCP server

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

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

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

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

Related MCP server: yandex-mcp

Установка

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>

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

Тип

Redirect URI

Вход

«Для авторизации пользователей»

свой: http://localhost:8765/callback

yandex-mcp login

«Для доступа к API или отладки»

зафиксирован Яндексом

yandex-mcp login --manual

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

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

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

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

Что умеет

Метрика

metrika_summary

Сводка за период: визиты, посетители, отказы, глубина, достижения всех целей

metrika_compare

Сравнение двух периодов — по итогам или построчно по источникам, устройствам, страницам

metrika_report

Любой отчёт: свои метрики, измерения и фильтры

metrika_counters

Какие счётчики доступны

Вебмастер

webmaster_summary

ИКС, страниц в поиске, исключено, активные проблемы

webmaster_queries

Поисковые запросы: показы, клики, средняя позиция

webmaster_indexing

Как менялось число страниц в поиске

webmaster_sitemaps

Какие карты сайта видит Яндекс и есть ли в них ошибки

webmaster_recrawl

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

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

direct_campaigns

Кампании и остаток баллов API

direct_report

Расход, показы, клики, CTR — по кампаниям, объявлениям, группам или запросам

wordstat_phrases

Частотности: сколько раз в месяц ищут фразу и что ищут вместе с ней

Подключение

yandex_login

Начать вход — выдаёт ссылку

yandex_submit_code

Завершить вход — принимает код

yandex_auth_status

Что подключено и когда истекает

Скиллы

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

/yandex-mcp:site-weekly

Недельный отчёт по сайту: трафик, источники, поиск, реклама — и что делать

/yandex-mcp:seo-opportunities

Запросы на границе топа: где до первой страницы осталось немного

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

Ничего настраивать не нужно — подходящее хранилище выбирается само. Форсировать можно переменной 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, и это постоянный налог на каждый диалог.

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

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

Переменная

Зачем

YANDEX_MCP_DEFAULT_COUNTER

Счётчик Метрики по умолчанию

YANDEX_MCP_CLIENT_ID

ID приложения Яндекса, если не хочешь держать его в хранилище

YANDEX_MCP_KEYSTORE

keychain, secret-tool или file — выбрать хранилище вручную

YANDEX_MCP_SECRET_TOKEN

Готовый токен мимо хранилища (Docker, CI)

YANDEX_MCP_DIRECT_SANDBOX

1 — Директ отвечает из песочницы, баллы API не тратятся

YANDEX_MCP_DIRECT_CLIENT_LOGIN

Логин клиента для агентских аккаунтов

YANDEX_MCP_WORDSTAT_WAIT

Сколько секунд ждать отчёт Вордстата, по умолчанию 170

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

  • Инструменты Директа и Вордстата требуют одобренной заявки на 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

Available Tools

15 tools
direct_campaignsB

Список кампаний Яндекс Директа (только чтение) и остаток баллов API. Пока не подана заявка на доступ к API Директа, вернёт код 58.

Inputs: limit, client_login.

direct_reportA

Отчёт по расходу/показам/кликам Директа (Reports API v5) — то, чего нет в direct_campaigns: реальные цифры эффективности по кампаниям, объявлениям, группам или поисковым запросам. Период — либо готовый диапазон Директа (date_range, по умолчанию LAST_30_DAYS: LAST_7_DAYS, THIS_MONTH, ALL_TIME и т.д.), либо явные date1/date2 в формате YYYY-MM-DD (относительные вроде 30daysAgo, как в Метрике, не поддерживаются). Отчёт может готовиться асинхронно — тул сам ждёт и повторяет запрос, суммарно до нескольких минут.

Inputs: date1, date2, fields, date_range, +3 more.

metrika_compareA

Сравнение метрик между двумя периодами — для вопросов вроде «как изменился трафик за последний месяц». Период B по умолчанию: такой же длины, вплотную перед периодом A (можно задать явно через prev_date1/prev_date2). Если задан dimensions — сравнение построчно по значениям измерения, иначе только по итогам.

Inputs: metrics (required), date1, date2, limit, +5 more.

metrika_countersB

Список доступных счётчиков Метрики с их сайтами и статусом.

Inputs: no named parameters.

metrika_reportB

Произвольный отчёт Reporting API Метрики. Метрики: ym:s:visits, ym:s:users, ym:s:bounceRate, ym:s:goalreaches, ym:s:goalconversionRate, ym:pv:pageviews. Измерения: ym:s:lastsignTrafficSource, ym:s:lastsignSourceEngine, ym:s:searchPhrase, ym:s:startURLPath, ym:pv:URLPath, ym:s:regionCity, ym:s:deviceCategory, ym:s:UTMSource, ym:s:UTMCampaign, ym:s:date, ym:s:referalSource. ID целей смотри через metrika_summary — там они перечислены с достижениями.

Inputs: metrics (required), sort, date1, date2, +4 more.

metrika_summaryB

Сводка Яндекс Метрики за период: визиты, посетители, отказы, длительность, глубина и достижения всех целей счётчика.

Inputs: date1, date2, counter_id.

webmaster_indexingB

Динамика количества страниц сайта в поиске Яндекса по датам (GET .../search-urls/in-search/history) — рост/падение индексации во времени.

Inputs: date_to, date_from.

webmaster_queriesB

Поисковые запросы, по которым сайт показывается в Яндексе: показы, клики, средняя позиция.

Inputs: limit.

webmaster_recrawlA

Ставит URL в очередь на переобход Яндексом (POST, мутирующий вызов — единственный в этом сервере). До 20 URL за раз, квота Вебмастера 150 в сутки на весь сайт. Необратимо: требует confirm: true, и перед этим список URL нужно показать пользователю.

Inputs: urls (required), confirm.

webmaster_sitemapsB

Sitemap-файлы, которые видит Яндекс для сайта: URL, число адресов в нём, количество ошибок, дата последнего обращения робота.

Inputs: limit.

webmaster_summaryB

Состояние сайтов в Яндекс Вебмастере: ИКС, страниц в поиске, исключено, список активных проблем диагностики.

Inputs: no named parameters.

wordstat_phrasesA

Частотности Яндекс Вордстата: сколько раз в месяц ищут фразу и что ищут вместе с ней. Работает через Live v4 API Директа по тому же токену. Отчёт готовится у Яндекса около трёх минут; если вызов вернул «ещё готовится» — повтори его с теми же фразами, результат подхватится.

Inputs: phrases (required), top, geo_id.

yandex_auth_statusA

Что уже подключено: какое хранилище секретов используется, есть ли ClientID приложения и токены, когда они истекают. Сам токен не показывается — только отпечаток. Вызывай первым, если какой-то инструмент ответил «нет токена».

Inputs: no named parameters.

yandex_loginA

Шаг 1 входа в Яндекс: выдаёт ссылку авторизации, которую нужно показать пользователю. Терминал не нужен. После подтверждения вызови yandex_submit_code.

Inputs: mode, services.

yandex_submit_codeA

Шаг 2 входа: обменивает код подтверждения на токен и кладёт его в хранилище ОС. В режиме localhost вызывается без аргументов.

Inputs: code.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, helped by service prefixes (metrika_, webmaster_, direct_, wordstat_, yandex_). Within each service, the operations are well separated, such as summary vs. custom report vs. period comparison vs. counter listing. No overlapping tools cause meaningful misselection risk.

    Naming Consistency5/5

    All tool names use consistent snake_case with a predictable service prefix followed by a noun or action. The pattern is clear across Metrika, Webmaster, Direct, Wordstat, and auth tools. There are no mixed conventions or vague naming styles.

    Tool Count5/5

    The 15 tools are well-scoped for a multi-service Yandex integration, with only a few focused tools per service. Each tool appears to earn its place without excessive surface area. This falls comfortably in the appropriate range.

    Completeness4/5

    The server covers core read/analytics workflows across Metrika, Webmaster, Direct, Wordstat, and authentication, including one mutation for Webmaster recrawl. Minor gaps exist, such as Direct campaign management and possible auth token refresh/revoke operations, but the main agent workflows are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI assistants to SEO data from Yandex Webmaster, Google Search Console, Yandex Metrica, and Topvisor, enabling natural language analysis of search performance, indexation, positions, and audits.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to work with Yandex Webmaster, Direct, and Metrika data through natural language, including managing sites, sitemaps, recrawls, ad campaigns with write-safety guards, and pulling traffic, conversion, and ad statistics.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables SEO and AI-search visibility analysis for Russian websites through Yandex APIs, including keyword research from Wordstat, live SERP results, position tracking with history, technical audits, content briefs, and checks of AI search citations.
      22
      2
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to read Yandex Direct statistics and manage campaigns, ad groups, ads, keywords, bids, and other account settings locally on a single-user Windows PC.
      7
      MIT