Яндекс.Директ
API Яндекс.Директа v5: кампании, объявления, фразы, ставки, минус-фразы, статистика
Runs on your machine from its package; the steps are below.
What it does
- Reads
- Writes
- High impact
At most: moves money, runs code or commands, deletes data, or sends messages for you.
What it costs
FreeOdel charges nothing per call. The publisher may charge for its own service.
Runs locally over stdio
This server isn't hosted — your MCP client launches it from a package registry. Use one of the commands below, or drop the config into your client (e.g. Claude Desktop).
Run
npx -y yandex-direct-mcp-plus
MCP client config
{
"mcpServers": {
"server": {
"command": "npx",
"args": [
"-y",
"yandex-direct-mcp-plus"
]
}
}
}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, из исходников
- Токен — как получить и какие переменные окружения нужны
- Что меняет данные — что тратит бюджет и что необратимо
- Инструменты — полный список с описаниями
- Разработка — сборка, тесты, архитектура
Что можно делать
Обычным текстом в чате — инструменты сервер подставляет сам:
Собери кампанию «Летняя распродажа»: бюджет 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, и любой вызов идёт по боевому аккаунту. Отлаживать сценарии приходится на отдельной кампании, оставленной черновиком, — показов она не даёт и потому не тратит бюджет, пока не пройдёт модерацию и не будет включена.
У каждого пишущего инструмента есть параметр 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: бюджет (руб), статус и пояснение к нему, даты, статистика, 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 | Установить ставки (поиск/сети, в рублях) на уровне фраз, групп или кампаний (сервис Bids). |
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 docs:tools # таблицы инструментов в README из реестра
Таблицы инструментов выше руками не правятся: после смены описания инструмента — 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.
