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 [email protected]: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_* и справочники. Вызвать их безопасно всегда.
Тратят бюджет или запускают показы:
| Инструмент | Чем именно |
|---|---|
manage_campaigns | resume — включает показы остановленной кампании |
manage_ads | resume и moderate — возвращает объявления в показ |
moderate_ads | Отправляет объявления на модерацию, после неё начнутся показы |
update_campaign | Меняет дневной бюджет |
set_keyword_bids | Меняет ставки, то есть цену клика |
set_auto_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: бюджет (руб), статус и пояснение к нему, даты, статистика, UTM-разметка, цели и их ценность (PriorityGoals), счётчики Метрики, модель атрибуции и прочие настройки. |
create_campaign | Создать новую текстово-графическую кампанию. |
update_campaign | Обновить кампанию: название, бюджет (руб), UTM-разметку и/или статус (SUSPEND/RESUME/ARCHIVE/UNARCHIVE). |
manage_campaigns | Запустить, остановить, архивировать, разархивировать или удалить кампании. |
get_strategy | Получить текущую стратегию показов текстово-графической кампании вместе с целями (PriorityGoals), счётчиками и моделью атрибуции. |
set_strategy | Изменить стратегию текстово-графической кампании: ручная, максимум кликов, средняя цена клика или конверсии, оплата за конверсию. |
set_priority_goals | Задать цели стратегии кампании (PriorityGoals) и их ценность в рублях — по ним автостратегия оптимизирует ставки, в том числе «максимум конверсий» со служебным GoalId 13. |
get_time_targeting | Временной таргетинг кампании: часовой пояс, часы показов по дням недели, почасовые коэффициенты и настройка праздников. |
set_time_targeting | Задать расписание показов кампании: дни, часы, почасовые коэффициенты, праздники и часовой пояс. |
Группы объявлений
| Инструмент | Описание |
|---|---|
list_ad_groups | Группы объявлений выбранных кампаний: названия, регионы, статусы. |
create_ad_group | Создать группу объявлений в кампании с таргетингом по регионам (см. get_regions). |
delete_ad_groups | Удалить группы объявлений по их ID. |
Объявления
| Инструмент | Описание |
|---|---|
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} и настройки автотаргетинга. |
manage_keywords | Действие над ключевыми фразами: suspend/resume/delete. |
set_keyword_bids | Установить фиксированные ставки (поиск/сети, в рублях) на уровне фраз, групп или кампаний и включить или выключить автоставку автотаргетинга. |
set_auto_keyword_bids | Назначить ставки по правилу вместо суммы: на поиске — под желаемый объём трафика (5–100%), в сетях — под долю аудитории, с надбавкой в процентах и потолком в рублях. |
get_keyword_auction | Сколько стоит трафик по фразам: текущие ставки и торги на поиске и в сетях. |
Минус-фразы
| Инструмент | Описание |
|---|---|
get_campaign_negative_keywords | Получить текущие минус-фразы кампаний по их ID. |
set_campaign_negative_keywords | Минус-фразы на уровне кампании. |
set_ad_group_negative_keywords | Минус-фразы на уровне группы объявлений. |
list_negative_keyword_shared_sets | Получить общие наборы минус-фраз аккаунта. |
manage_negative_keyword_shared_sets | Создать, изменить или удалить общие наборы минус-фраз аккаунта. |
link_negative_keyword_sets | Заменить привязки общих наборов минус-фраз у кампаний и/или групп объявлений. |
Ассеты объявления
| Инструмент | Описание |
|---|---|
list_sitelinks | Получить все или выбранные наборы быстрых ссылок. |
set_sitelinks | Создать новый набор из 1–8 быстрых ссылок. |
delete_sitelinks | Удалить наборы быстрых ссылок по ID. |
list_ad_extensions | Получить уточнения (callouts) с их статусами и текстом. |
add_ad_extensions | Создать уточнения (callouts), каждый текст до 25 символов. |
delete_ad_extensions | Удалить уточнения по ID. |
manage_ad_images | Загрузить, получить или удалить изображения объявлений (AdImages). |
list_vcards | Получить виртуальные визитки по ID или найти их через объявления выбранных кампаний. |
delete_vcards | Удалить визитки по ID; удаление необратимо. |
Таргетинг и корректировки
| Инструмент | Описание |
|---|---|
list_audience_targets | Получить условия нацеливания на аудиторию по ID кампании, группы, ретаргетинга или интереса. |
set_audience_targets | Добавить, остановить, возобновить, удалить аудиторные цели или изменить их ставки. |
list_dynamic_targets | Получить условия нацеливания динамических текстовых объявлений. |
manage_dynamic_targets | Создать, изменить ставки, остановить, возобновить или удалить динамические цели. |
list_retargeting_lists | Получить условия ретаргетинга и подбора аудитории с правилами и областью применения. |
add_retargeting_list | Создать условие ретаргетинга из целей Метрики, сегментов или интересов. |
update_retargeting_lists | Изменить название, описание и правила условий ретаргетинга. |
delete_retargeting_lists | Удалить условия ретаргетинга и подбора аудитории по ID; удаление необратимо. |
get_bid_adjustments | Получить корректировки ставок кампании или группы: устройства, пол и возраст, аудитории, регионы, платёжеспособность, размещение. |
add_bid_adjustments | Создать корректировки ставок на кампаниях или группах. |
set_bid_adjustments | Изменить коэффициенты существующих корректировок по их ID. |
delete_bid_adjustments | Удалить корректировки по их ID. |
Отчёты
| Инструмент | Описание |
|---|---|
get_statistics | Статистика за период по кампаниям, группам, объявлениям, условиям показа или аккаунту: показы, клики, расход (руб), CTR, CPC (ReportService, TSV). |
get_search_queries | Отчёт по фактическим поисковым запросам для анализа и добавления минус-фраз. |
Аккаунт и справочники
| Инструмент | Описание |
|---|---|
get_account_balance | Баланс и финансовая информация аккаунта (Amount, Currency) через Live API v4. |
list_businesses | Получить доступные профили организаций из Яндекс Бизнеса. |
get_changes | Проверить изменения кампаний, групп и объявлений начиная с указанного времени, а также изменения справочников (mode=dictionaries) и текущее время сервера Директа. |
list_feeds | Получить товарные фиды, их источники, статусы обработки и связанные кампании. |
get_regions | Справочник кодов регионов (GeoRegions) для таргетинга. |
list_time_zones | Справочник часовых поясов (TimeZones) для set_time_targeting и create_campaign. |
Разработка
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.