yandex-direct-mcp-plus

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

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

Содержание

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

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

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

Code

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

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

Установка

Нужен Node.js 22+ и OAuth-токен Яндекс.Директа — как его получить.

Claude Code

Terminal

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

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

config.json

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

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

bash

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

Дальше тот же конфиг, но "command": "node" и путь к dist/app/index.js вместо npx.

Токен

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

Переменная	Обязательна	Назначение
`YANDEX_DIRECT_TOKEN`	да	OAuth-токен Яндекс.Директ
`YANDEX_DIRECT_LOGIN`	нет	Логин клиента для агентских токенов (заголовок `Client-Login`). Обязателен, если токен агентский

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

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

У каждого пишущего инструмента есть параметр dry_run. С dry_run: true вызов проверяет параметры схемой, выполняет нужные ему чтения и возвращает тела запросов, которые ушли бы в Директ, ничего не отправляя.

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

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

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

Инструмент	Чем именно
`manage_campaigns`	`resume` — включает показы остановленной кампании
`manage_ads`	`resume` и `moderate` — возвращает объявления в показ
`moderate_ads`	Отправляет объявления на модерацию, после неё начнутся показы
`update_campaign`	Меняет дневной бюджет
`set_keyword_bids`	Меняет ставки, то есть цену клика
`set_strategy`	Меняет стратегию — переписывает всю экономику кампании
`add_bid_adjustments`	Заводит корректировку: +N% к ставке на срезе аудитории
`set_bid_adjustments`	Меняет коэффициент существующей корректировки

Удаляют необратимо — эти инструменты помечены аннотацией 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. Такие объекты заводятся в интерфейсе Директа, а дальше сервер с ними работает: кампании читает и правит, визитки читает и удаляет. Единую перфоманс-кампанию сервер пока только читает.

Инструменты

Кампании

Инструмент	Описание
`list_campaigns`	Список кампаний (фильтр по статусу/типу, пагинация)
`get_campaign`	Детальная информация о кампании по ID
`create_campaign`	Создать текстово-графическую кампанию (бюджет в рублях, выбор стратегии, часовой пояс, UTM-разметка)
`update_campaign`	Обновить название/бюджет/UTM-разметку и/или статус (SUSPEND/RESUME/ARCHIVE/UNARCHIVE)
`manage_campaigns`	suspend/resume/archive/unarchive/delete для списка кампаний
`get_strategy`	Получить стратегию текстово-графической кампании
`set_strategy`	Сменить стратегию: ручная, максимум кликов, средняя цена клика/конверсии, оплата за конверсию
`set_priority_goals`	Цели стратегии и их ценность в рублях: добавить, убрать или заменить список
`get_time_targeting`	Расписание показов: часовой пояс, часы по дням недели, праздники
`set_time_targeting`	Задать расписание показов и почасовые коэффициенты (заменяет целиком)

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

Инструмент	Описание
`list_ad_groups`	Группы объявлений выбранных кампаний
`create_ad_group`	Создать группу с таргетингом по регионам
`delete_ad_groups`	Удалить группы по ID
`set_ad_group_negative_keywords`	Минус-фразы группы: `mode` обязателен — `replace`, `add` или `remove`

Объявления

Инструмент	Описание
`list_ads`	Объявления в группах
`create_text_ad`	Создать текстовое объявление (≤56/≤30/≤81)
`update_text_ad`	Обновить заголовок/текст/ссылку
`manage_ads`	suspend/resume/archive/unarchive/moderate/delete
`moderate_ads`	Отправить объявления на модерацию

Ключевые слова и ставки

Инструмент	Описание
`list_keywords`	Ключевые фразы в группах (ставки в рублях)
`add_keywords`	Добавить ключевые фразы
`update_keywords`	Изменить текст фразы и подстановочные переменные `{param1}`/`{param2}`
`set_keyword_bids`	Установить ставки (поиск/сети, рубли) на фразах/группах/кампаниях
`get_keyword_auction`	Аукцион по фразам: ставки и списываемые цены по позициям, ставки конкурентов, цена входа (рубли)
`manage_keywords`	suspend/resume/delete
`set_campaign_negative_keywords`	Минус-фразы кампании: `mode` обязателен — `replace`, `add` или `remove`
`get_campaign_negative_keywords`	Получить минус-фразы кампаний

Быстрые ссылки, уточнения и корректировки

Инструмент	Описание
`list_sitelinks`	Получить наборы быстрых ссылок
`set_sitelinks`	Создать новый набор быстрых ссылок
`delete_sitelinks`	Удалить наборы быстрых ссылок
`list_ad_extensions`	Получить уточнения (callouts)
`add_ad_extensions`	Создать уточнения
`delete_ad_extensions`	Удалить уточнения
`manage_ad_images`	Загрузить, получить или удалить изображения
`get_bid_adjustments`	Получить корректировки: устройства, пол и возраст, аудитории, регионы, платёжеспособность, размещение
`add_bid_adjustments`	Создать корректировки на кампаниях или группах
`set_bid_adjustments`	Изменить коэффициенты существующих корректировок
`delete_bid_adjustments`	Удалить корректировки по ID

Аудитории, цели и фиды

Инструмент	Описание
`list_retargeting_lists`	Получить условия ретаргетинга и подбора аудитории
`add_retargeting_list`	Создать условие ретаргетинга
`update_retargeting_lists`	Изменить название, описание и правила условий (правила заменяются целиком)
`delete_retargeting_lists`	Удалить условия ретаргетинга
`list_audience_targets`	Получить аудиторные цели
`set_audience_targets`	add/set_bids/suspend/resume/delete аудиторных целей
`list_dynamic_targets`	Получить динамические цели
`manage_dynamic_targets`	add/set_bids/suspend/resume/delete динамических целей
`list_feeds`	Получить товарные фиды
`list_negative_keyword_shared_sets`	Получить общие наборы минус-фраз
`manage_negative_keyword_shared_sets`	add/update/delete общих наборов
`link_negative_keyword_sets`	Привязать общие наборы к кампаниям и группам объявлений

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

Инструмент	Описание
`get_statistics`	Статистика за период (показы, клики, расход, CTR, CPC)
`get_search_queries`	Фактические поисковые запросы для подбора минус-фраз
`get_changes`	Проверить изменения кампаний, групп, объявлений и справочников
`list_vcards`	Получить виртуальные визитки
`delete_vcards`	Удалить визитки по ID
`list_businesses`	Получить профили организаций Яндекс Бизнеса
`get_account_balance`	Баланс аккаунта (Live API v4)
`get_regions`	Справочник кодов регионов (225 = Россия), с вложенностью по запросу
`list_time_zones`	Справочник часовых поясов для расписания показов

Разработка

Terminal

npm install
npm run build      # tsc → dist/
npm test           # vitest (моки fetch)
npm run dev        # tsx --conditions=development src/app/index.ts
npm run lint       # biome
npm run typecheck  # tsc --noEmit
npm run lint:dead  # knip

Сетевые тесты (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 эта версия не публиковалась. Дальше проект развивается самостоятельно и апстрим не отслеживает.

История до отделения от апстрима (версии 3.0.0–5.0.0, включая вклад DrSeedon) — в docs/CHANGELOG-upstream.md; дальнейшие изменения — в CHANGELOG.md.

Лицензия

MIT — см. LICENSE. Уведомление об авторских правах исходного проекта сохранено.