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%.
Перед первой авторизацией нужно один раз создать приложение Яндекс.
Что умеет
- Кампании — просмотр, создание, редактирование, включение/отключение, архивация
- Объявления — текстовые, динамические, смарт-объявления, видеодополнения
- Ставки и бюджеты — ручные и автоматические ставки, лимиты, корректировки
- Ключевые слова — подбор, дедупликация, проверка объёма, минус-слова
- Отчёты — произвольные отчёты, статистика по конверсиям с целями Метрики
- Финансы — баланс, пополнение, выставление счетов, переводы между аккаунтами
- Справочники — регионы, валюты, площадки
- Написание объявлений — скилл, который умеет писать объявления под требования Директа
Всего 174 инструмента. Полный список: 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]" |
Настройка инструментов
По умолчанию зарегистрировано 174 инструмента (включая browser-инструменты Мастеров; они работают headless, нужен настроенный браузерный профиль — см. ниже). Можно ограничить набор через переменные окружения:
| Переменная | Что делает |
|---|
YANDEX_DIRECT_TOOL_PROFILE | Пресет: full (по умолчанию), core (10), analytics (28), campaign-editor (36) |
YANDEX_DIRECT_ENABLED_GROUPS | Включить только эти группы |
YANDEX_DIRECT_DISABLED_GROUPS | Исключить группы (например, browser — вся browser-область) |
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-приложение
- Откройте https://oauth.yandex.ru/client/new
- Заполните:
- Название — любое (например,
My Direct Plugin)
- Платформа — «Веб-сервисы»
- Redirect URI —
https://oauth.yandex.ru/verification_code
- Доступы — добавьте «Использование API Яндекс Директа» (
direct:api)
- Сохраните Client ID и Client Secret
Шаг 2. Заявка на доступ к API
- Войдите в https://direct.yandex.ru → Инструменты → API → Мои заявки
- Нажмите «Новая заявка», укажите Client ID из Шага 1
- Дождитесь подтверждения
Без Шага 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 playwright doctor (legacy-команда 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
