# yandex-direct-mcp-plus

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

[![npm](https://img.shields.io/npm/v/yandex-direct-mcp-plus.svg)](https://www.npmjs.com/package/yandex-direct-mcp-plus)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node](https://img.shields.io/badge/node-%3E%3D22-green.svg)](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). Уведомление об авторских правах исходного проекта сохранено.