yandex-direct-mcp

Управляйте Яндекс.Директом из Claude Code, ChatGPT или любой LLM — через промпты.

Не нужны сервисы за 5–50 тыс. ₽/мес. Не нужно разбираться в сложных интерфейсах. Напишите промпт — нейросеть сама соберёт статистику, поменяет ставки, отключит дорогие объявления и пришлёт понятный отчёт.

Open-source · бесплатно · работает локально

Быстрый старт

1. Подключите маркетплейс (один раз):

/plugin marketplace add etopro/plugin-marketplace

2. Установите плагин:

/plugin install yandex-direct@plugin-marketplace

3. Авторизуйтесь в Яндексе:

auth_login()

Откроется браузер → войдите в Яндекс → токен сохранится автоматически.

4. Готово. Пишите промпт:

Покажи кампании за последнюю неделю, отключи объявления,
где заявка дороже 1500 ₽, а там, где дешёвые — подними бюджет на 20%.

Перед первой авторизацией нужно один раз создать приложение Яндекс.

Что умеет

• Кампании — просмотр, создание, редактирование, включение/отключение, архивация
• Объявления — текстовые, динамические, смарт-объявления, видеодополнения
• Ставки и бюджеты — ручные и автоматические ставки, лимиты, корректировки
• Ключевые слова — подбор, дедупликация, проверка объёма, минус-слова
• Отчёты — произвольные отчёты, статистика по конверсиям с целями Метрики
• Финансы — баланс, пополнение, выставление счетов, переводы между аккаунтами
• Справочники — регионы, валюты, площадки
• Яндекс Аудитории — сегменты, пиксели, доступы и представители (второй транспорт yac)
• Написание объявлений — скилл, который умеет писать объявления под требования Директа

Всего 202 инструмента. Полный список: docs/TOOLS.md. В чате: tool_help() — все инструменты, tool_help('campaigns_get') — справка по конкретному.

Примеры промптов

покажи активные кампании

сколько я потратил за эту неделю?

отключи кампанию «Ретаргет ДРР» — она сливает бюджет

подними ставку на 15 руб для ключевика 99999

покажи объявления, где CTR ниже 2%

баланс аккаунта

напиши три варианта объявления для доставки пиццы

цели Метрики для кампании 12345

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

Плагин работает только на вашем компьютере. Токен и данные аккаунта не уходят на чужие серверы. Исходный код открыт — можно проверить.

Все изменения требуют подтверждения: нейросеть покажет, что собирается сделать, и дождётся вашего «ок».

Другие платформы

Платформа	Как подключить
Claude Code	/plugin marketplace add etopro/plugin-marketplace → /plugin install yandex-direct@plugin-marketplace
Codex	Маркетплейс-манифест: .agents/plugins/marketplace.json
ChatGPT / локальные LLM	Любой MCP-клиент → python -m server.main (stdio)
Разработка	git clone + pip install -e ".[dev]"

Настройка инструментов

По умолчанию зарегистрировано 202 инструмента (включая browser-инструменты Мастеров и 28 инструментов Яндекс Аудиторий; browser-инструменты работают headless, нужен настроенный браузерный профиль — см. ниже). Можно ограничить набор через переменные окружения:

Переменная	Что делает
YANDEX_DIRECT_TOOL_PROFILE	Пресет: full (по умолчанию), core (10), analytics (28), campaign-editor (36)
YANDEX_DIRECT_ENABLED_GROUPS	Включить только эти группы
YANDEX_DIRECT_DISABLED_GROUPS	Исключить группы (например, browser — вся browser-область, audience — всё из Яндекс Аудиторий)
YANDEX_DIRECT_ENABLED_TOOLS / _DISABLED_TOOLS	Точечные переопределения
YANDEX_DIRECT_OPTIONAL_TOOLS	Какие browser/local-reference бандлы грузить: browser, trackingparams, комбинация или all; без переменной грузятся все

Настройка развёртывания browser-инструментов (это env сервера, а не параметры тулов):

Переменная	Что делает
YANDEX_DIRECT_BROWSER_PROFILE_DIR	Каталог постоянного профиля браузера; по умолчанию используется профиль CLI
YANDEX_DIRECT_BROWSER_CHROME_PROFILE	Выбор профиля внутри каталога
YANDEX_DIRECT_BROWSER_HEADFUL	1 — показывать окно браузера вместо headless-режима
YANDEX_DIRECT_BROWSER_TIMEOUT	Таймаут браузерных команд в секундах (положительное целое)

// ~/.claude/settings.json — только аналитика
{ "env": { "YANDEX_DIRECT_TOOL_PROFILE": "analytics" } }

Подробнее: docs/token-budget.md.

Создание приложения Яндекс

Делается один раз перед первой авторизацией.

Шаг 1. OAuth-приложение

1. Откройте https://oauth.yandex.ru/client/new
2. Заполните:
   • Название — любое (например, My Direct Plugin)
   • Платформа — «Веб-сервисы»
   • Redirect URI — https://oauth.yandex.ru/verification_code
   • Доступы — добавьте «Использование API Яндекс Директа» (direct:api)
3. Сохраните Client ID и Client Secret

Шаг 2. Заявка на доступ к API

1. Войдите в https://direct.yandex.ru → Инструменты → API → Мои заявки
2. Нажмите «Новая заявка», укажите Client ID из Шага 1
3. Дождитесь подтверждения

Без Шага 2 все запросы вернут ошибку incomplete_registration.

Использование своего OAuth-приложения

direct auth login --client-id "ваш-client-id" --client-secret "ваш-client-secret"

Авторизация Мастеров кампаний

В версиях плагина, где доступны masters_get и masters_targetactions_get, эти инструменты отличаются от остальных: Мастера кампаний доступны только в веб-интерфейсе Директа, поэтому direct-cli читает их через браузер под управлением Playwright. OAuth-токен из auth_login() или ~/.direct-cli/auth.json для этого не используется и не заменяет браузерную сессию. Проверьте наличие инструментов через tool_help(); если их нет, сначала обновите плагин до версии с поддержкой read-only Masters.

Перед первым вызовом masters-инструмента выполните в обычном терминале, вне MCP-сессии:

direct auth login browser

Команда открывает видимое окно Chromium с Яндекс Паспортом и ждёт ручного входа. Она сохраняет сессию в единственное хранилище CLI ~/.direct-cli/playwright/session.json. Браузерные команды при отсутствии, повреждении или истечении envelope сами импортируют живую сессию из Chrome (headless, без окна) — окно открывает только direct auth login browser. Запускайте команду от того же пользователя и с тем же HOME, под которым работает MCP-сервер.

Тот же вход доступен и из MCP-сессии тулом auth_browser_login() — оно открывает такое же видимое окно либо импортирует уже залогиненную сессию Chrome (source="chrome").

Для direct auth login browser нужны browser extra direct-cli и Chromium для Playwright. Установите их в то же окружение и для той же закреплённой версии CLI, которую выбирает MCP-сервер. Для установки из Claude marketplace по умолчанию:

DIRECT_BIN="${YANDEX_DIRECT_CLI_PATH:-${CLAUDE_PLUGIN_DATA:-$HOME/.claude/plugins/data/yandex-direct}/venv/bin/direct}"
DIRECT_PY="$(dirname "$DIRECT_BIN")/python3"
DIRECT_VERSION="$("$DIRECT_PY" -c 'import importlib.metadata as m; print(m.version("direct-cli"))')"
"$DIRECT_PY" -m pip install "direct-cli[browser]==$DIRECT_VERSION"
"$DIRECT_PY" -m playwright install chromium
"$DIRECT_BIN" auth login browser

Если используется другой MCP-клиент или собственный YANDEX_DIRECT_CLI_PATH, задайте DIRECT_BIN и DIRECT_PY путями из одного и того же окружения. Не направляйте MCP на случайную или незакреплённую системную версию direct-cli: она станет транспортом для всех инструментов плагина, а не только Masters.

Интерактивный вход нельзя выполнить из MCP tool-call, headless-сессии, удалённого процесса без GUI/TTY или CI. После ручной настройки сами read-only-инструменты могут запускать браузер без окна, если им доступны тот же профиль и установленный Chromium. Не рассчитывайте на эту схему в эфемерных или sandboxed-окружениях, где домашний каталог не сохраняется.

Импорт из уже авторизованного Chrome: source="chrome" у auth_browser_login (или автоимпорт любой browser-командой при отсутствии/ повреждении envelope) копирует Yandex cookies из выбранного Chrome-профиля в ~/.direct-cli/playwright/session.json. На macOS для расшифровки cookies потребуется разрешить чтение ключа Chrome Safe Storage из Keychain. Для безопасной диагностики без входа и записи файлов используйте direct auth doctor — скрытый legacy-алиас direct playwright doctor deprecated (direct playwright login тоже deprecated — используйте direct auth login browser).

Браузерные тулы авторизуют аккаунт, открытый в браузере; OAuth-профиль и YANDEX_DIRECT_LOGIN не переключают masters-инструменты на другой клиентский аккаунт. Хранилище содержит живую Яндекс-сессию — не копируйте и не публикуйте его. Удалить сохранённую сессию можно командой direct auth logout browser или тулом auth_browser_logout внутри MCP-сессии.

Скиллы

Скилл	Что делает
/yandex-direct:yandex-direct	Управление кампаниями — стратегия, оптимизация, лимиты
/yandex-direct:direct-ads	Написание объявлений для Яндекс.Директ
/yandex-direct:direct-eda	Разведочный анализ рекламной статистики

Разработка

pytest                    # тесты (кассеты, без токена)
pytest -m mocks           # edge-case моки
pytest -m integration     # живой API (нужен токен)
ruff check . && ruff format .  # линт
mypy .                    # типы

Архитектура, тестовая инфраструктура, конвенции: CLAUDE.md.

Лицензия

MIT