yandex-mcp
An MCP server for querying Yandex analytics (Metrika, Webmaster, Direct, Wordstat) in natural language — read-only apart from one recrawl action, with built-in OAuth login and token storage.
Metrika: period summaries (visits, users, bounce rate, depth, goal reaches), arbitrary Reporting API reports with custom metrics/dimensions/filters, period-over-period comparisons, and listing available counters.
Yandex Webmaster: site health (ИКС, pages in search, excluded pages, active problems), search queries with impressions/clicks/avg position, indexing history over time, sitemap status, and submitting up to 20 URLs for recrawl (requires
confirm: true).Yandex Direct: campaign list plus API points balance, and performance reports (cost, impressions, clicks, CTR) by campaign, ad group, ad, or search query — with async report waiting and date ranges.
Wordstat: monthly search frequency for up to 10 phrases plus related queries, filtered by region.
Auth: start login (link), submit the confirmation code, and check connection status/expiry — PKCE-based, tokens kept in OS keychain/secret-tool/0600 file, scrubbed from all output.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yandex-mcp как изменился трафик за последний месяц и откуда пришёл рост?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
yandex-mcp
Спрашивай свою аналитику Яндекса словами. Метрика, Вебмастер, Директ и Вордстат в одном MCP-сервере.
> Как изменился трафик за последний месяц и откуда пришёл рост?
> По каким запросам мы на второй странице — там, где до топа осталось чуть-чуть?
> Сколько стоила заявка в Директе на прошлой неделе по каждой кампании?Как это работает
Сервер — обычная программа на твоём компьютере. Агент просит у неё данные, она идёт в API Яндекса и возвращает готовый текст. Никаких промежуточных серверов: твой токен и твои цифры не проходят через чужие руки.
Зависимостей нет вообще — ни одной сторонней библиотеки. Через этот процесс идёт доступ к твоей аналитике и рекламному кабинету, и чем меньше здесь чужого кода, тем лучше.
Related MCP server: yandex-mcp
Установка
Claude Code — две команды, вместе с сервером ставятся скиллы:
/plugin marketplace add nozikov/yandex-mcp
/plugin install yandex-mcp@nozikovCodex 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 | Вход |
«Для авторизации пользователей» | свой: |
|
«Для доступа к API или отладки» | зафиксирован Яндексом |
|
В разделе «Доступ к данным» добавь права по названию:
metrika:read
webmaster:hostinfo
webmaster:verify
direct:api ← нужна заявка в кабинете Директа, рассматривают до 7 днейВход просит все права разом. Если direct:api ещё не одобрен, Яндекс откажет — сервер
это заметит, войдёт без Директа и скажет об этом. Метрика и Вебмастер заработают сразу,
а когда заявку одобрят, повторный вход подхватит Директ.
Команды в терминале: setup, login, status, logout.
Что умеет
Метрика
| Сводка за период: визиты, посетители, отказы, глубина, достижения всех целей |
| Сравнение двух периодов — по итогам или построчно по источникам, устройствам, страницам |
| Любой отчёт: свои метрики, измерения и фильтры |
| Какие счётчики доступны |
Вебмастер
| ИКС, страниц в поиске, исключено, активные проблемы |
| Поисковые запросы: показы, клики, средняя позиция |
| Как менялось число страниц в поиске |
| Какие карты сайта видит Яндекс и есть ли в них ошибки |
| Поставить страницы на переобход. Единственное действие, а не чтение — требует явного подтверждения |
Директ и Вордстат
| Кампании и остаток баллов API |
| Расход, показы, клики, CTR — по кампаниям, объявлениям, группам или запросам |
| Частотности: сколько раз в месяц ищут фразу и что ищут вместе с ней |
Подключение
| Начать вход — выдаёт ссылку |
| Завершить вход — принимает код |
| Что подключено и когда истекает |
Скиллы
Ставятся вместе с плагином 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, и это постоянный налог на каждый диалог.
Оставлено то, на что реально смотрят: цифры и их динамика. Управлять кампаниями и ставками отсюда нельзя — для этого есть кабинет Директа, и цена ошибки там другая.
Переменные окружения
Переменная | Зачем |
| Счётчик Метрики по умолчанию |
| ID приложения Яндекса, если не хочешь держать его в хранилище |
|
|
| Готовый токен мимо хранилища (Docker, CI) |
|
|
| Логин клиента для агентских аккаунтов |
| Сколько секунд ждать отчёт Вордстата, по умолчанию 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 toolsdirect_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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Read-only Yandex Metrika MCP. Query visits, sources, geo, devices and more in plain language.
Analyze Yandex Metrica traffic and conversions in ChatGPT with read-only access.
Read-only Google Search Console and Google Analytics for AI agents.
MCP for Yandex Direct: manage ad campaigns & analytics from Claude or ChatGPT
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceConnects 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- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseBqualityBmaintenanceEnables 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.222MIT
- AlicenseBqualityBmaintenanceEnables 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.7MIT