Яндекс.Директ

yandex-direct-mcp-plus

Ведение контекстной рекламы Яндекс.Директа из диалога с ассистентом: собрать кампанию, разобрать поисковые запросы, вычистить минус-фразы, поправить ставки и посмотреть расход — не переключаясь между разделами кабинета. Работает в любом MCP-клиенте: Claude Code, Claude Desktop, Cursor и другие.

• 60 инструментов, из них 25 только читают. Кампании и стратегии, группы, объявления и модерация, ключевые фразы и ставки, минус-фразы и общие наборы, быстрые ссылки, уточнения, изображения, визитки, корректировки ставок, ретаргетинг, аудиторные и динамические цели, фиды, расписание показов, статистика, поисковые запросы, баланс и справочники.
• Деньги — в рублях, на вводе и на выводе; в микроединицы API сервер переводит сам. Поддержан агентский режим (Client-Login).
• ID — строками ("1915016273214320641"): 64-битные идентификаторы Директа не помещаются в число JavaScript и молча теряют точность.
• Реклама боевая. Тестовой среды у Директа больше нет — какие инструменты тратят деньги и что удаляют необратимо, перечислено в разделе Что меняет данные.
• Телеметрии нет. Сервер не отправляет никуда ничего, кроме запросов к API Яндекса.

Содержание

• Что можно делать — примеры запросов обычным текстом
• Установка — Claude Code, Claude Desktop, Cursor, из исходников
• Токен — как получить и какие переменные окружения нужны
• Что меняет данные — что тратит бюджет и что необратимо
• Инструменты — полный список с описаниями
• Разработка — сборка, тесты, архитектура

Что можно делать

Обычным текстом в чате — инструменты сервер подставляет сам:

Собери кампанию «Летняя распродажа»: бюджет 5000 ₽/день, старт 1 мая, показы будни 9–21
Добавь минус-фразы «бесплатно» и «скачать» в кампанию 12345, не затерев остальные
Посмотри поисковые запросы за месяц и предложи, что заминусовать
Подними ставку до 25 ₽ там, где CTR выше 8%, а показов меньше сотни
Что изменилось в кампаниях со вчера?
Покажи расход по кампаниям за неделю и баланс аккаунта
Найди код региона для Новосибирска

Полный список — в разделе Инструменты.

Установка

Понадобятся Node.js не ниже 22 и OAuth-токен Директа (где взять). Отдельно ставить сервер не нужно: клиент сам запускает пакет через npx и общается с ним по stdio.

Claude Code

claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y yandex-direct-mcp-plus

Claude Desktop, Cursor и другие клиенты

В конфиг MCP-серверов клиента (claude_desktop_config.json, .cursor/mcp.json и т. п.) добавляется запись:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "yandex-direct-mcp-plus"],
      "env": { "YANDEX_DIRECT_TOKEN": "ваш_токен" }
    }
  }
}

Агентскому токену в env нужен ещё YANDEX_DIRECT_LOGIN — см. Токен.

Из исходников

git clone git@github.com:Pavelsiba/yandex-direct-mcp-plus.git
cd yandex-direct-mcp-plus
npm ci
npm run build

В конфиге клиента вместо npx тогда стоит "command": "node", а в args — абсолютный путь к dist/app/index.js.

Удалённый сервер

Тот же сервер можно поднять по HTTP на своей машине — в Docker, за nginx с HTTPS — и подключаться к нему по адресу из claude.ai, с телефона или из Claude Desktop без установки Node. Вход закрыт секретом. Настройка — docs/deploy.md.

Токен

OAuth-токен выпускается для приложения, зарегистрированного в Яндекс OAuth, с доступом к API Директа. Подробности — регистрация приложения и получение токена. Доступ к API нужно запросить в интерфейсе Директа — заявку рассматривают от часа до нескольких суток.

Сервер берёт настройки только из окружения процесса, которое ему передаёт клиент:

• YANDEX_DIRECT_TOKEN — OAuth-токен. Без него сервер запускается, но любой вызов инструмента возвращает ошибку.
• YANDEX_DIRECT_LOGIN — логин рекламодателя, уходит в заголовок Client-Login. Нужен только агентскому токену: без него запросы идут в собственный кабинет агентства, а не в кабинет клиента.

Что меняет данные

Тестовой среды у Яндекс.Директа больше нет: песочница отключена с июля 2026, и любой вызов идёт по боевому аккаунту. Отлаживать сценарии приходится на отдельной кампании, оставленной черновиком, — показов она не даёт и потому не тратит бюджет, пока не пройдёт модерацию и не будет включена.

Граница проходит не по «чтение или запись», а по скорости, с которой действие превращается в деньги.

Только читают все list_*, get_* и справочники. Вызвать их безопасно всегда.

Тратят бюджет или запускают показы:

Удаляют необратимо — эти инструменты помечены аннотацией DESTRUCTIVE, и хороший MCP-клиент спросит подтверждение перед вызовом:

manage_campaigns (delete), manage_ads (delete), manage_keywords (delete), delete_ad_groups, delete_ad_extensions, delete_sitelinks, delete_vcards, delete_bid_adjustments, delete_retargeting_lists, manage_ad_images (delete), manage_dynamic_targets (delete), set_audience_targets (delete), manage_negative_keyword_shared_sets (delete).

Сюда же — set_campaign_negative_keywords и set_ad_group_negative_keywords в режиме replace: он затирает прежний список минус-фраз целиком. Именно поэтому у них нет режима по умолчанию — mode приходится назвать явно. Так же устроен set_priority_goals: replace и remove убирают цели стратегии, а любая смена целей перезапускает её обучение.

Остальные инструменты создают и правят объекты. Пока кампания не прошла модерацию и не включена, показов по ней нет и бюджет не расходуется.

Чего API не умеет. Смарт-баннеры и динамические объявления Директ через API не создаёт с 22 мая 2026, визитки — тоже: в WSDL методы есть, боевой API отвечает ошибкой 3500. Такие объекты заводятся в интерфейсе Директа, а дальше сервер с ними работает: кампании читает и правит, визитки читает и удаляет. Единую перфоманс-кампанию сервер пока только читает.

Инструменты

В таблицах — первое предложение описания, которое сервер отдаёт модели; таблицы собираются из кода, поэтому список всегда полный.

Кампании и стратегии

Группы объявлений

Объявления

Ключевые фразы и ставки

Минус-фразы

Ассеты объявления

Таргетинг и корректировки

Отчёты

Аккаунт и справочники

Разработка

npm ci               # зависимости строго по lock-файлу
npm run dev          # сервер из исходников, без сборки
npm run build        # dist/ — то, что запускает MCP-клиент
npm test             # юнит-тесты, сеть подменена
npm run lint         # Biome: формат и линт
npm run typecheck    # типы в src, тестах и конфигах
npm run lint:dead    # knip: неиспользуемый код и зависимости
npm run lint:workflows # actionlint + zizmor: корректность и безопасность workflow
npm run lint:secrets # gitleaks по всей истории
npm run docs:tools   # таблицы инструментов в README из реестра

gitleaks, actionlint, zizmor и shellcheck — не npm-пакеты; без них хуки pre-commit не пропустят коммит. На Windows:

winget install -e --id Gitleaks.Gitleaks
winget install -e --id rhysd.actionlint
winget install -e --id zizmor.zizmor
winget install -e --id koalaman.shellcheck

Без режима разработчика winget не создаёт ссылки в %LOCALAPPDATA%\Microsoft\WinGet\Links, и каталоги пакетов из %LOCALAPPDATA%\Microsoft\WinGet\Packages придётся добавить в PATH.

Таблицы инструментов выше руками не правятся: после смены описания инструмента — npm run docs:tools, иначе юнит-тест покажет расхождение.

Сетевые тесты (npm run test:int) идут по боевому аккаунту и пишут только в кампанию-полигон, оставленную черновиком: её ID задаётся переменной YANDEX_DIRECT_POLYGON_CAMPAIGN_ID. Без переменной они пропускаются.

Код разложен по слоям app → tools → shared; инструмент — это каталог src/tools/<домен>/ с schema.ts, handler.ts и tool.ts. Подробности — в docs/architecture.md.

Происхождение и благодарности

Проект начат на коде theYahia/yandex-direct-mcp под лицензией MIT. Расширение с 20 до 48 инструментов и перевод ID на строки — работа **Maxim (DrSeedon)**, PR #7; в npm эта версия не публиковалась. Дальше проект развивается самостоятельно и апстрим не отслеживает.

История изменений с отделения от апстрима — в CHANGELOG.md.

Лицензия

Copyright © 2026 Pavelsiba. GNU AGPL-3.0-only.

Пользоваться сервером, изменять его и разворачивать у себя можно свободно, в том числе в работе с клиентами. Кто предоставляет изменённый сервер другим людям по сети, обязан дать им исходный код своей версии (раздел 13 лицензии).

Версии до 1.7.0 включительно вышли под MIT и под ней остаются.

Pull request'ы принимаются вместе с передачей прав на вклад автору проекта (CLA) — без этого проект не сможет распоряжаться своим кодом. Перед большой правкой лучше завести issue.