Яндекс.Директ
API Яндекс.Директа v5: кампании, объявления, фразы, ставки, минус-фразы, статистика
Open source Open in the app JSON README (API)
About
API Яндекс.Директа v5: кампании, объявления, фразы, ставки, минус-фразы, статистика
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- pavelsiba
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.6.1
- Stars
- 1
- Last push
- 2026-09-13T14:57:31Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-09-13 15:42:55
- Updated
- 2026-09-13 15:42:55
- Origin id
io.github.Pavelsiba/yandex-direct-mcp-plus
README
# yandex-direct-mcp-plus
Ведение контекстной рекламы Яндекс.Директа из диалога с ассистентом: собрать кампанию, разобрать поисковые запросы, вычистить минус-фразы, поправить ставки и посмотреть расход — не переключаясь между разделами кабинета. Работает в любом MCP-клиенте: Claude Code, Claude Desktop, Cursor и другие.
[](https://www.npmjs.com/package/yandex-direct-mcp-plus)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
- **60 инструментов**, из них 25 только читают. Кампании и стратегии, группы, объявления и модерация, ключевые фразы и ставки, минус-фразы и общие наборы, быстрые ссылки, уточнения, изображения, визитки, корректировки ставок, ретаргетинг, аудиторные и динамические цели, фиды, расписание показов, статистика, поисковые запросы, баланс и справочники.
- **Деньги — в рублях**, на вводе и на выводе; в микроединицы API сервер переводит сам. Поддержан агентский режим (`Client-Login`).
- **ID — строками** (`"1915016273214320641"`): 64-битные идентификаторы Директа не помещаются в число JavaScript и молча теряют точность. Здесь это стережёт правило линтера, а не внимательность.
- **Реклама боевая.** Тестовой среды у Директа больше нет — какие инструменты тратят деньги и что удаляют необратимо, перечислено в разделе [Что меняет данные](#что-меняет-данные).
- **Телеметрии нет.** Сервер не отправляет никуда ничего, кроме запросов к API Яндекса.
## Содержание
- [Что можно делать](#что-можно-делать) — примеры запросов обычным текстом
- [Установка](#установка) — Claude Code, Claude Desktop, Cursor, из исходников
- [Токен](#токен) — как получить и какие переменные окружения нужны
- [Что меняет данные](#что-меняет-данные) — что тратит бюджет и что необратимо
- [Инструменты](#инструменты-60) — полный список с описаниями
- [Разработка](#разработка) — сборка, тесты, архитектура
## Что можно делать
Обычным текстом в чате — инструменты сервер подставляет сам:
```
Собери кампанию «Летняя распродажа»: бюджет 5000 ₽/день, старт 1 мая, показы будни 9–21
Добавь минус-фразы «бесплатно» и «скачать» в кампанию 12345, не затерев остальные
Посмотри поисковые запросы за месяц и предложи, что заминусовать
Подними ставку до 25 ₽ там, где CTR выше 8%, а показов меньше сотни
Что изменилось в кампаниях со вчера?
Покажи расход по кампаниям за неделю и баланс аккаунта
Найди код региона для Новосибирска
```
Полный список — [60 инструментов](#инструменты-60) ниже.
## Установка
Нужен Node.js 22+ и OAuth-токен Яндекс.Директа — [как его получить](#токен).
### Claude Code
```bash
claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y yandex-direct-mcp-plus
```
### Claude Desktop, Cursor и другие клиенты
```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](https://oauth.yandex.ru/), с доступом к API Директа. Подробности — [регистрация приложения и получение токена](https://yandex.ru/dev/direct/doc/ru/token). Доступ к API нужно [запросить в интерфейсе Директа](https://yandex.ru/dev/direct/doc/ru/access-request) — заявку рассматривают от часа до нескольких суток.
| Переменная | Обязательна | Назначение |
|------------|:-----------:|------------|
| `YANDEX_DIRECT_TOKEN` | да | OAuth-токен Яндекс.Директ |
| `YANDEX_DIRECT_LOGIN` | нет | Логин клиента для агентских токенов (заголовок `Client-Login`). Обязателен, если токен агентский |
| `YANDEX_DIRECT_POLYGON_CAMPAIGN_ID` | нет | Только для `npm run test:int`: ID кампании-полигона, оставленной черновиком. Сетевые тесты пишут в неё и ни во что другое; без переменной они пропускаются |
## Что меняет данные
Тестовой среды у Яндекс.Директа больше нет: песочница отключена с июля 2026, и любой вызов идёт по боевому аккаунту. Отлаживать сценарии приходится на отдельной кампании, оставленной черновиком, — показов она не даёт и потому не тратит бюджет, пока не пройдёт модерацию и не будет включена.
Граница проходит не по «чтение или запись», а по скорости, с которой действие превращается в деньги.
**25 инструментов только читают** — все `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` убирают цели стратегии, а любая смена целей перезапускает её обучение.
Остальные инструменты создают и правят объекты. Пока кампания не прошла модерацию и не включена, показов по ней нет и бюджет не расходуется.
## Инструменты (60)
**Кампании**
| Инструмент | Описание |
|------------|----------|
| `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` | Получить виртуальные визитки |
| `add_vcard` | Создать виртуальную визитку |
| `delete_vcards` | Удалить визитки по ID |
| `list_businesses` | Получить профили организаций Яндекс Бизнеса |
| `get_account_balance` | Баланс аккаунта (Live API v4) |
| `get_regions` | Справочник кодов регионов (225 = Россия), с вложенностью по запросу |
| `list_time_zones` | Справочник часовых поясов для расписания показов |
## Разработка
```bash
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
```
Код разложен по слоям `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 эта версия не публиковалась. Дальше проект развивается самостоятельно и апстрим не отслеживает.
История до отделения от апстрима (версии 3.0.0–5.0.0, включая вклад DrSeedon) — в [docs/CHANGELOG-upstream.md](docs/CHANGELOG-upstream.md); дальнейшие изменения — в [CHANGELOG.md](CHANGELOG.md). План — в [docs/roadmap.md](docs/roadmap.md), архитектура — в [docs/architecture.md](docs/architecture.md).
## Лицензия
MIT — см. [LICENSE](LICENSE). Уведомление об авторских правах исходного проекта сохранено.