yandex-direct-mcp-plus
# yandex-direct-mcp-plus
Ведение контекстной рекламы Яндекс.Директа из диалога с ассистентом: собрать кампанию, разобрать поисковые запросы, вычистить минус-фразы, поправить ставки и посмотреть расход — не переключаясь между разделами кабинета. Работает в любом MCP-клиенте: Claude Code, Claude Desktop, Cursor и другие.
[](https://www.npmjs.com/package/yandex-direct-mcp-plus)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://nodejs.org)
- **Вход из диалога.** Ассистент даёт ссылку, вы входите своим аккаунтом Яндекса и присылаете код — без регистрации приложения, заявки на доступ к API и ручного токена.
- **68 инструментов**, из них 27 только читают. Кампании и стратегии, группы, объявления и модерация, ключевые фразы и ставки, прогноз по фразам без кампании, минус-фразы и общие наборы, запрещённые площадки и IP, быстрые ссылки, уточнения, изображения, визитки, корректировки ставок, ретаргетинг, аудиторные и динамические цели, фиды, расписание показов, статистика, поисковые запросы, баланс и справочники.
- **Деньги — в рублях**, на вводе и на выводе; в микроединицы API сервер переводит сам. Поддержан агентский режим (`Client-Login`).
- **ID — строками** (`"1915016273214320641"`): 64-битные идентификаторы Директа не помещаются в число JavaScript и молча теряют точность.
- **Реклама боевая.** Тестовой среды у Директа больше нет — какие инструменты тратят деньги и что удаляют необратимо, перечислено в разделе [Что меняет данные](#что-меняет-данные).
- **Телеметрии нет.** Сервер не отправляет никуда ничего, кроме запросов к API Яндекса.
## Содержание
- [Что можно делать](#что-можно-делать) — примеры запросов обычным текстом
- [Установка](#установка) — Claude Code, Claude Desktop, Cursor, из исходников
- [Подключение к Директу](#подключение-к-директу) — вход из диалога или свой токен
- [Что меняет данные](#что-меняет-данные) — что тратит бюджет и что необратимо
- [Инструменты](#инструменты) — полный список с описаниями
- [Разработка](#разработка) — сборка, тесты, архитектура
## Что можно делать
Обычным текстом в чате — инструменты сервер подставляет сам:
```text
Собери кампанию «Летняя распродажа»: бюджет 5000 ₽/день, старт 1 мая, показы будни 9–21
Добавь минус-фразы «бесплатно» и «скачать» в кампанию 12345, не затерев остальные
Посмотри поисковые запросы за месяц и предложи, что заминусовать
Подними ставку до 25 ₽ там, где CTR выше 8%, а показов меньше сотни
Что изменилось в кампаниях со вчера?
Покажи расход по кампаниям за неделю и баланс аккаунта
Найди код региона для Новосибирска
```
Полный список — в разделе [Инструменты](#инструменты).
## Установка
Понадобится Node.js не ниже 22. Отдельно ставить сервер не нужно: клиент сам запускает пакет через `npx` и общается с ним по stdio. Токен заранее не нужен — вход делается из диалога ([как](#подключение-к-директу)).
### Claude Code
```bash
claude mcp add yandex-direct -- npx -y yandex-direct-mcp-plus
```
### Claude Desktop, Cursor и другие клиенты
В конфиг MCP-серверов клиента (`claude_desktop_config.json`, `.cursor/mcp.json` и т. п.) добавляется запись:
```json
{
"mcpServers": {
"yandex-direct": {
"command": "npx",
"args": ["-y", "yandex-direct-mcp-plus"]
}
}
}
```
Агентскому аккаунту в `env` нужен ещё `YANDEX_DIRECT_LOGIN` — см. [Подключение к Директу](#подключение-к-директу).
### Из исходников
```bash
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](docs/deploy.md).
## Подключение к Директу
### Вход из диалога
Достаточно попросить ассистента подключиться к Директу. Он вызовет `start_login` и покажет ссылку на вход в Яндекс — входите аккаунтом, у которого есть доступ к нужному кабинету. Яндекс покажет код подтверждения; его нужно прислать в чат, и ассистент передаст его в `finish_login`.
- Вход идёт через приложение этого сервера с одобренным доступом к API, поэтому своё приложение и заявка не нужны. Баллы API тратит ваш аккаунт, как и при собственном токене.
- Код одноразовый и без ключа, который хранится только в запущенном сервере, бесполезен — присылать его в чат безопасно.
- Токен сохраняется в `~/.config/yd-mcp/credentials.json` (или `$XDG_CONFIG_HOME/yd-mcp/`), файл доступен только владельцу. Срок продлевается сам.
- Кто подключён и до когда — `auth_status`. Выйти — `logout`: он удаляет сохранённый вход. Отозвать доступ совсем — в Яндекс ID, раздел «Устройства, сервисы и пароли».
### Свой токен
Если токен уже есть — например, для CI или удалённого сервера, — его можно передать в окружении, и тогда он главнее входа из диалога. Токен выпускается для приложения, зарегистрированного в [Яндекс OAuth](https://oauth.yandex.ru/), с доступом к API Директа: [регистрация приложения и получение токена](https://yandex.ru/dev/direct/doc/ru/token), доступ [запрашивается в интерфейсе Директа](https://yandex.ru/dev/direct/doc/ru/access-request) — заявку рассматривают от часа до нескольких суток.
```bash
claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y yandex-direct-mcp-plus
```
В JSON-конфиге клиента — `"env": { "YANDEX_DIRECT_TOKEN": "ваш_токен" }` рядом с `args`.
### Переменные окружения
- `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. Такие объекты заводятся в интерфейсе Директа, а дальше сервер с ними работает: кампании читает и правит, визитки читает и удаляет. Единую перфоманс-кампанию сервер пока только читает.
## Инструменты
В таблицах — первое предложение описания, которое сервер отдаёт модели; таблицы собираются из кода, поэтому список всегда полный.
<!-- tools:start — генерируется npm run docs:tools, руками не править -->
### Подключение
| Инструмент | Описание |
| ------------ | ---------- |
| `start_login` | Первый шаг входа из диалога, без ручного токена: возвращает ссылку на вход в Яндекс. |
| `finish_login` | Второй шаг входа: меняет код подтверждения от пользователя на токен и сохраняет его на этом компьютере. |
| `auth_status` | Откуда сервер берёт токен (переменная окружения, вход из диалога или запрос) и до когда он действует. |
| `logout` | Удаляет сохранённый вход из диалога с этого компьютера. |
### Кампании и стратегии
| Инструмент | Описание |
| ------------ | ---------- |
| `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). |
| `update_ad_group` | Изменить группу объявлений без пересоздания: название, регионы показа (полный список, заменяет прежний) и/или UTM-разметку ссылок. |
| `delete_ad_groups` | Удалить группы объявлений по их ID. |
### Объявления
| Инструмент | Описание |
| ------------ | ---------- |
| `list_ads` | Объявления: все заголовки и тексты, ссылки, статусы, тип и подтип объявления, привязанные сайтлинки, изображения и видео. |
| `create_responsive_ad` | Создать комбинаторное объявление: от 1 до 7 заголовков (≤56 символов), от 1 до 3 текстов (≤81) и ссылка; варианты показа Директ собирает из них сам. |
| `update_responsive_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_keyword_forecast` | Прогноз трафика и цены клика по списку фраз без кампании — для подбора семантики. |
### Минус-фразы
| Инструмент | Описание |
| ------------ | ---------- |
| `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` | Заменить привязки общих наборов минус-фраз у кампаний и/или групп объявлений. |
### Запреты показа
| Инструмент | Описание |
| ------------ | ---------- |
| `set_campaign_excluded_sites` | Площадки РСЯ и приложения, на которых кампания не показывается (до 1000). |
| `set_campaign_blocked_ips` | IP-адреса, которым кампания не показывается (до 25, одиночные публичные IPv4). |
### Ассеты объявления
| Инструмент | Описание |
| ------------ | ---------- |
| `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; с goals — конверсии и CPA по целям Метрики (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. |
<!-- tools:end -->
## Разработка
```bash
npm ci # зависимости строго по lock-файлу
npm run dev # сервер из исходников, без сборки
npm run build # dist/ — то, что запускает MCP-клиент
npm test # юнит-тесты, сеть подменена
npm run lint # Biome: формат и линт
npm run typecheck # типы в src, тестах и конфигах
npm run lint:md # markdownlint: README и docs по правилам форматтера IDE
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:
```powershell
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](docs/architecture.md).
## Происхождение и благодарности
Проект начат на коде [`theYahia/yandex-direct-mcp`](https://github.com/theYahia/yandex-direct-mcp) под лицензией MIT. Расширение с 20 до 48 инструментов и перевод ID на строки — работа [**Maxim (DrSeedon)**](https://github.com/DrSeedon), [PR #7](https://github.com/theYahia/yandex-direct-mcp/pull/7); в npm эта версия не публиковалась. Дальше проект развивается самостоятельно и апстрим не отслеживает.
История изменений с отделения от апстрима — в [CHANGELOG.md](CHANGELOG.md).
## Лицензия
Copyright © 2026 Pavelsiba. [GNU AGPL-3.0-only](LICENSE).
Пользоваться сервером, изменять его и разворачивать у себя можно свободно, в том числе в работе с клиентами. Кто предоставляет изменённый сервер другим людям по сети, обязан дать им исходный код своей версии (раздел 13 лицензии).
Версии до 1.7.0 включительно вышли под MIT и под ней остаются.
Pull request'ы принимаются вместе с передачей прав на вклад автору проекта (CLA) — без этого проект не сможет распоряжаться своим кодом. Перед большой правкой лучше завести issue.
TDQS
Scored across 68 tools
Many tools target distinct resources and actions, but there is real overlap: update_campaign also handles SUSPEND/RESUME/ARCHIVE while manage_campaigns covers launch/stop/archive/unarchive/delete; manage_ads includes moderate while moderate_ads exists separately; keyword bidding is split across update_keywords, manage_keywords, set_keyword_bids, and set_auto_keyword_bids. The long descriptions usually clarify scope, but at 68 tools the boundaries require careful reading.
All names are snake_case and mostly follow verb_noun, but conventions vary: list_campaigns is plural while get_campaign is singular, create_ad_group is singular while list_ad_groups/delete_ad_groups are plural, set_sitelinks actually creates a new set, and login/auth tools use start/finish/logout/auth_status. The set is still readable, but it is not a consistently predictable pattern.
68 tools is far above the well-scoped 3-15 range and creates a very heavy selection surface for an agent. Yandex Direct is a broad domain, but this is an extreme tool count and should be split or consolidated.
Coverage is broad across campaigns, ad groups, ads, keywords, bids, strategies, targeting, negative keywords, sitelinks, vcards, images, audience/retargeting, bid adjustments, statistics, references, and authentication. Some gaps remain, such as update_ad_extensions, vcard creation that the API disallows, and limited creation support for some campaign types, but most core workflows are represented.