Yandex Analytics

io.github.nozikovPublished by GitHub account nozikovv2.1.0Updated Oct 25, 2026

Read-only Yandex analytics for AI agents: Metrika, Webmaster, Direct and Wordstat.

VerifiedSTDIODesktop onlyData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

Read-only Yandex analytics MCP server that lets an assistant query Metrika, Webmaster, Direct and Wordstat data in plain language.

What you can do
  • Query Metrika: period summaries, two-period comparisons, custom reports and available counters
  • Inspect Webmaster data: site summary, search queries, indexing history and sitemaps
  • Read Direct advertising: campaigns, API points balance and cost/click/CTR reports
  • Look up Wordstat phrase frequencies and related queries
  • Manage the Yandex connection: start login, submit the code, check auth status
  • Request a page recrawl in Webmaster, the only write action, requiring explicit confirmation
When to use it
Useful when you want an assistant to answer questions about a Yandex-verified site's traffic, search visibility, ad spend or keyword demand without opening the Yandex dashboards. Suited to recurring SEO and advertising reporting rather than campaign management.
Requirements
Runs locally as a Python package (uvx yandex-mcp) over stdio. Needs a self-registered Yandex OAuth application with metrika:read, webmaster:hostinfo, webmaster:verify and direct:api scopes; Direct and Wordstat additionally need an approved Direct API application. Optional environment variables include YANDEX_MCP_DEFAULT_COUNTER, YANDEX_MCP_CLIENT_ID and YANDEX_MCP_KEYSTORE. Network access to Yandex APIs is required.
Before you install
Handles a Yandex OAuth token granting access to your analytics and ad account; it is stored in the OS keystore or, where none exists, in a 0600 file, and can also be supplied via YANDEX_MCP_SECRET_TOKEN. The token expires after about six months and must be renewed by logging in again. Recrawl requests change data on Yandex's side and are quota-limited. Direct and Wordstat calls consume API points and require an approved application.

Installation

In SourceWeft

  1. Open Yandex Analytics in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

yandex-mcp

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

[tests] [PyPI] [Python] [License: MIT]

[Yandex Analytics MCP server]

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

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

[Клиент и сервер работают на твоём компьютере и ходят в API Яндекса напрямую]

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

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

Установка

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

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

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

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

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

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

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

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

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

Вход

[Три шага входа: попросить агента, подтвердить в браузере, вернуть код в чат]

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

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

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

bash
yandex-mcp setup --client-id <ClientID>
Что вписать при регистрации приложения

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

ТипRedirect URIВход
«Для авторизации пользователей»свой: http://localhost:8765/callbackyandex-mcp login
«Для доступа к API или отладки»зафиксирован Яндексомyandex-mcp login --manual

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

metrika:readwebmaster:hostinfowebmaster:verifydirect: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Запросы на границе топа: где до первой страницы осталось немного

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

[Хранилище выбирается автоматически: переменная окружения, Keychain, secret-tool, файл 0600]

Ничего настраивать не нужно — подходящее хранилище выбирается само. Форсировать можно переменной 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_IDID приложения Яндекса, если не хочешь держать его в хранилище
YANDEX_MCP_KEYSTOREkeychain, secret-tool или file — выбрать хранилище вручную
YANDEX_MCP_SECRET_TOKENГотовый токен мимо хранилища (Docker, CI)
YANDEX_MCP_DIRECT_SANDBOX1 — Директ отвечает из песочницы, баллы 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-метки и названия кампаний пишут посторонние люди. К каждому ответу добавляется пометка, что это данные для анализа, а не инструкции агенту.

Разработка

bash
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

Source: README.md at commit 4856f68

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v2.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts