yandex-mcp

Спрашивай свою аналитику словами. MCP-сервер к Яндекс Метрике, Вебмастеру, Директу и Вордстату: 15 инструментов, ноль зависимостей, токен лежит в хранилище ОС и не появляется ни в одном ответе.

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

Кому это

Безопасность в трёх фразах

Сервер работает только на вашем компьютере: он ходит в API Яндекса напрямую, никаких посредников. Токен хранится в Keychain, GNOME Keyring или файле с правами 0600 — и не появляется ни в ответе инструмента, ни в тексте ошибки. Единственное необратимое действие — постановка страниц на переобход — требует явного confirm: true.

Установка

Claude Code — плагин, две команды

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

Плагин ставит сервер и скиллы разом, обновляется через /plugin update, а пути подставляет сам. Нужен только Python 3.8+, установка пакета не требуется.

Любой MCP-клиент — из PyPI

uvx yandex-mcp              # запуск без установки
# или: pipx install yandex-mcp

claude mcp add yandex -s user -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_DEFAULT_COUNTER опционален: без него counter_id придётся передавать в каждом вызове явно.

Вход

Терминал не нужен — просто попросите агента:

> Подключи Яндекс

Он вызовет yandex_login, покажет ссылку, вы подтвердите доступ в браузере и вернёте код в чат. Токен ляжет в хранилище ОС, перезапускать сервер не нужно.

Если предпочитаете терминал:

yandex-mcp setup     # регистрация приложения Яндекса, по шагам
yandex-mcp login     # вход в браузере
yandex-mcp status    # какие токены есть, где лежат, когда истекут
yandex-mcp logout    # удалить токены из хранилища

Приложение Яндекса

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

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

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

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

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

Если нужен least privilege — login --service metrika выдаст отдельный узкий токен только на неё; такой токен имеет приоритет над общим.

Инструменты

Скиллы

Ставятся вместе с плагином, вызываются как обычные слэш-команды:

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

Спецификация инструментов уходит в контекст модели при каждом запросе, пока сервер подключён. У нас это ≈1 800 токенов. У серверов со 130–150 инструментами — 40 000 и больше, причём 85% приходится на JSON-схемы параметров. Это постоянный налог на каждый диалог и лишний шум при выборе инструмента.

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

Где лежат токены

Хранилище выбирается автоматически, по убыванию защищённости:

Принудительно — переменной YANDEX_MCP_KEYSTORE=keychain|secret-tool|file.

Все записи лежат под префиксом yandex-mcp-, чтобы в глобальном пространстве имён Keychain ничего не пересекалось и logout не задел чужое:

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

Любой секрет можно прокинуть через окружение, минуя хранилище: yandex-mcp-metrika-token → YANDEX_MCP_SECRET_METRIKA_TOKEN, общий токен → YANDEX_MCP_SECRET_TOKEN. Это основной способ для Docker и CI.

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

Принципы

• Токен не хранится в открытом виде там, где есть системное хранилище, и не появляется ни в одном ответе инструмента, ни в тексте ошибки — есть отдельный scrub(), вычищающий Bearer/OAuth-заголовки и Яндекс-токены (y0_..., y1_...) из любого текста. status печатает только sha256-отпечаток.
• Почти всё — чтение. Единственный мутирующий вызов — webmaster_recrawl, ограниченный 20 URL за раз и требующий confirm: true: у Вебмастера квота 150 в сутки на весь сайт.
• Данные из API считаются недоверенными. Поисковые фразы, UTM-метки и названия кампаний пишут посторонние люди; каждый ответ снабжается пометкой, что это данные для анализа, а не инструкции агенту.
• Официальный MCP SDK не используется намеренно — он тянет httpx, pydantic, anyio и их транзитивные зависимости, а через этот процесс проходит OAuth-токен к вашей аналитике и рекламному кабинету. Меньше чужого кода в рантайме — меньше supply-chain поверхность.

Структура проекта

src/yandex_mcp/
  cli.py               # yandex-mcp: без аргументов сервер, с аргументами настройка
  server.py            # JSON-RPC поверх stdio
  registry.py          # реестр инструментов: сборка TOOLS/HANDLERS
  httpclient.py        # urllib-обёртка: заголовки, единая обработка ошибок
  scrub.py             # вычищение секретов из ответов и ошибок
  auth/
    store.py           # выбор хранилища: Keychain / secret-tool / файл 0600
    tokens.py          # токен сервиса, с фолбэком на общий
    flow.py            # PKCE-вход: begin/complete — тихие, save_tokens — терминальный
    callback.py        # приём redirect на localhost
  tools/               # по модулю на сервис: metrika, webmaster, direct, wordstat, auth
tests/
  conftest.py          # изолированное файловое хранилище вместо системного
  auth/ tools/         # структура повторяет исходники
.claude/skills/        # скиллы, которые ставятся вместе с плагином
.claude-plugin/        # манифесты плагина и маркетплейса Claude Code

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

Разработка

pip install -e ".[dev]"
pytest

Тесты не ходят в сеть и не трогают системное хранилище: сеть и Keychain подменяются через monkeypatch, секреты пишутся во временный файл. CI гоняет их на Linux, macOS и Windows.

Ограничения

• direct_campaigns, direct_report и wordstat_phrases требуют одобренного доступа к API Директа — до одобрения Директ отвечает кодом ошибки 58.
• wordstat_phrases: отчёт готовится у Яндекса около трёх минут. Если вызов вернул «ещё готовится» — повторите его с теми же фразами, готовый результат подхватится сразу.
• direct_report при офлайн-обработке может готовиться минуты — тул сам ждёт, но упирается в квоту Директа: не больше 5 офлайн-отчётов в очереди на аккаунт.
• webmaster_sitemaps отдаёт первые 100 sitemap хоста (без пагинации).
• Ответ каждого инструмента обрезается до 20000 символов — для больших выгрузок сужайте период или limit.
• Файловое хранилище (Windows, headless, Docker) держит токен в открытом виде под правами 0600 — уровень ~/.aws/credentials или SSH-ключа без пароля. На Windows права наследуются от профиля пользователя, chmod там условен.
• На macOS запись в Keychain идёт через security add-generic-password -w <value>, то есть на время работы подпроцесса значение видно в ps — ограничение самого CLI. На Linux secret-tool читает значение из stdin, там этой проблемы нет.
• Обновление токена (refresh) у Яндекса требует client_secret, которого у PKCE-приложения нет. Практического значения это не имеет: выданный так токен живёт около года, после чего достаточно повторить yandex-mcp login.

Лицензия

MIT