yandex-direct-mcp

# MCP «Яндекс Директ»

<!-- mcp-name: io.github.ai-hub-open/yandex-direct-mcp -->

MCP-сервер на Bun и TypeScript, который даёт ИИ-агенту прямой доступ к [API Яндекс Директа](https://yandex.ru/dev/direct/).

## Что это

Вы работаете с Директом обычными репликами агенту: «заведи перформанс-кампанию с оплатой за конверсии по этой цели», «выставь ставки по этим фразам», «покажи, что аукцион отдаёт по семантике», «сними отчёт за две недели». Сервер переводит запросы в вызовы API: создаёт и правит кампании, группы, объявления и ключевые фразы, назначает ставки, читает данные аукциона и выгружает статистику.

Мост берёт на себя механическую часть ведения кампаний — повторяющиеся операции с точными полями и пересчётами. Стратегические решения, тексты и подтверждение изменений остаются за вами и агентом.

## Как проходит работа

MCP — это набор инструментов, которыми агент пользуется по ходу задачи, а не пошаговый мастер настройки. Одна операция проходит так:

1. **Подключение и авторизация.** Сервер запускается один раз в среде ИИ-агента. Авторизоваться можно через Click.ru или своим OAuth-токеном Яндекс Директа. Песочница доступна только в прямом режиме; через Click.ru сервер работает с боевым кабинетом.
2. **Чтение состояния.** Перед изменением агент получает кампании со статусами и статистикой, группы, объявления, фразы, ставки с данными аукциона, корректировки и справочники.
3. **Изменение.** Агент создаёт и правит текстовые кампании и единые перформанс-кампании, стратегии торгов, группы, объявления, фразы, ставки и демографические корректировки, а также привязывает счётчики и цели Метрики.
4. **Проверка.** После изменения агент перечитывает объект и снимает отчёт, чтобы убедиться, что настройки применились.

Сервер исполняет команды в кабинете сразу: встроенного предпросмотра или отмены нет. Настройте агента так, чтобы перед изменениями он показывал план и ждал вашего подтверждения. Для безопасной проверки есть сквозной прогон по песочнице.

## Инструменты

В сервере 37 инструментов.

| Область | Инструменты | Что позволяют сделать |
|---|---|---|
| **Кампании** | get, add, update, delete, suspend, resume | Создавать и вести текстовые кампании и ЕПК; задавать стратегии для поиска и РСЯ, недельный бюджет и потолок ставки; привязывать счётчики Метрики, приоритетные цели и модель атрибуции |
| **Группы объявлений** | get, add, update, delete | Создавать группы с регионами показа и минус-фразами; создавать группы ЕПК; добавлять UTM-параметры |
| **Объявления** | get, add, add_responsive, update, delete, suspend, resume, moderate | Создавать текстово-графические и комбинаторные объявления, править их, останавливать, возобновлять и отправлять на модерацию |
| **Изображения** | add, get | Загружать изображения с обрезкой 1:1 или 16:9 и получать список загруженных файлов |
| **Ставки по фразам** | set, get | Выставлять ставки по фразе, группе или кампании и читать данные аукциона |
| **Корректировки ставок** | demographics, get | Задавать корректировки по полу и возрасту и читать действующие корректировки |
| **Ключевые фразы** | get, add, update, delete, suspend, resume | Добавлять и править фразы, останавливать и возобновлять показы |
| **Отчёты** | campaign, ad, search_queries | Получать статистику по кампаниям и объявлениям и отчёт по поисковым запросам |
| **Справочники** | regions, currencies, interests, all | Получать идентификаторы регионов, валюты, интересы и другие справочные данные |

Скрипт `scripts/sandbox-e2e.ts` создаёт в песочнице цепочку ЕПК, проверяет группы, объявления, фразы, ставки, корректировки и отчёты, а затем удаляет созданное.

## Что делает агент, а что остаётся человеку

**Агент:**

- переводит задачу в корректные вызовы API и заполняет обязательные поля;
- проверяет входные данные до отправки;
- читает состояние кабинета и справочники;
- после изменения перечитывает объект и проверяет результат по отчёту.

**Человек:**

- выбирает стратегию, бюджет, целевые CPA и CRR и режим работы с сетями;
- подтверждает план изменения до вызова инструмента;
- заранее создаёт или находит идентификаторы целей и счётчиков Метрики, быстрых ссылок, уточнений, видеодополнений и профиля организации;
- готовит креативы и выдаёт OAuth-токен Яндекса или ключи Click.ru.

## Ограничения

- Сервер не подбирает семантику и не заменяет Вордстат. Данные аукциона доступны только по фразам, уже добавленным в кампанию.
- Сервер не управляет Метрикой как отдельным сервисом: он только привязывает к кампании готовые счётчики и цели по их идентификаторам.
- Быстрые ссылки, уточнения, видеодополнения и профиль организации нужно создать заранее; сервер принимает их готовые идентификаторы.
- На запись доступны только корректировки ставок по полу и возрасту.
- Комбинаторное объявление можно создать, но нельзя обновить — для изменения его нужно пересоздать.
- Доступны три отчёта с фиксированными полями и выгрузкой в TSV.
- Расписание показов, минус-слова уровня аккаунта и настройки за пределами перечисленных инструментов остаются в кабинете Директа.

## Требования

- [Bun](https://bun.sh) 1.1+

## Установка

Из npm — одной командой (нужен установленный Bun):

```bash
bunx @ai-hub-open/yandex-direct-mcp
```

Для подключения в конфиге MCP-клиента: `"command": "bunx", "args": ["@ai-hub-open/yandex-direct-mcp"]` плюс переменные окружения из раздела «Настройка».

Или из исходников:

```bash
git clone https://github.com/ai-hub-open/yandex-direct-mcp.git
cd yandex-direct-mcp
bun install
```

## Настройка

Скопируйте `.env.example` в `.env` и заполните **один из двух режимов** (переменные окружения имеют приоритет над `.env`):

**A. Через [Click.ru](https://click.ru) — основной путь: токен без заявок на доступ к API, OAuth-токен Яндекса не нужен:**

```bash
CLICK_RU_PROXY=true
CLICK_RU_TOKEN=<API-токен из профиля click.ru>
CLICK_RU_CLIENT_LOGIN=<логин аккаунта Яндекс.Директа>
CLICK_RU_USER_ID=<ID пользователя click.ru>   # только при работе из мастер-аккаунта
```

Токен создаётся в профиле `https://click.ru/userinfo.html` → поле «API Token» → «Создать». Аккаунт Яндекс.Директа должен быть подключён в Click.ru. Справка: `https://help.click.ru/81`, `https://api.click.ru/V0/docs/`.

> Прокси Click.ru работает только с боевым API Яндекса (песочница недоступна).

**B. Прямой режим — свой OAuth-токен Яндекс.Директа (единственный режим с песочницей):**

```bash
YANDEX_DIRECT_TOKEN=y0__...
YANDEX_DIRECT_SANDBOX=false   # true — песочница
```

По умолчанию используется версия API **v501** (обязательна для ЕПК); переключить можно через `YANDEX_DIRECT_API_VERSION=v5`.


## Запуск

```bash
bun run src/index.ts          # stdio — для локальных MCP-клиентов
bun run src/index.ts --http   # HTTP-сервер на :3000
```

E2E-прогон на песочнице (создаёт и удаляет тестовые кампании; нужны `YANDEX_DIRECT_TOKEN` и `YANDEX_DIRECT_SANDBOX=true`):

```bash
bun run scripts/sandbox-e2e.ts
```

## Подключение к Claude Code

`.mcp.json` в корне вашего проекта (см. также `.mcp.json.example`):

```json
{
  "mcpServers": {
    "yandex-direct": {
      "command": "bun",
      "args": ["run", "/абсолютный/путь/к/yandex-direct-mcp/src/index.ts"],
      "env": {
        "CLICK_RU_PROXY": "true",
        "CLICK_RU_TOKEN": "<ваш токен>",
        "CLICK_RU_CLIENT_LOGIN": "<логин Директа>"
      }
    }
  }
}
```

Для прямого режима в `env` вместо `CLICK_RU_*` укажите `YANDEX_DIRECT_TOKEN`.

**📋 Инструкция для AI-агента** — скопируйте и передайте своему агенту (Claude Code / Codex), подставив ключи:

> Установи и подключи MCP-сервер «Yandex Direct»: склонируй `https://github.com/ai-hub-open/yandex-direct-mcp.git`, проверь Bun (`bun --version`, если нет — установи с https://bun.sh), выполни `bun install` в корне репозитория. Зарегистрируй локальный stdio-MCP: команда `bun`, аргументы `run <абсолютный_путь_к_репо>/src/index.ts`, переменные окружения — мои ключи: `CLICK_RU_PROXY=true`, `CLICK_RU_TOKEN=<...>`, `CLICK_RU_CLIENT_LOGIN=<...>` (или `YANDEX_DIRECT_TOKEN=<...>` для прямого режима). Проверь `tools/list` и сообщи результат.

## HTTP-режим

```bash
MCP_TRANSPORT=http MCP_PORT=3000 bun run src/index.ts
```

Переменные: `MCP_PORT` (3000), `MCP_HOST` (0.0.0.0), `MCP_AUTH_TOKEN` (если задан — запросы должны нести `Authorization: Bearer <token>`), `MCP_ALLOWED_ORIGIN` (CORS).

| Метод + путь | Назначение |
|---|---|
| `POST /mcp` | JSON-RPC 2.0 запрос (или батч) |
| `GET /healthz` | health check |
| `GET /mcp/tools` | список инструментов (отладка) |

**Несколько аккаунтов:** данные доступа можно передавать в заголовках каждого запроса; они имеют приоритет над `.env`. Один сервер может обслуживать несколько клиентов:

```
X-Yandex-Token: <OAuth>              X-Click-Ru-Token: <токен>
X-Yandex-Sandbox: true|false         X-Click-Ru-User-Id: <ID>
X-Yandex-Api-Version: v501|v5        X-Client-Login: <логин Директа>
```

В режиме Click.ru по HTTP обязательны все три заголовка. Сервер можно запустить без данных доступа в `.env` — тогда они передаются в каждом запросе.

**⚠️ Безопасность:** при публикации в сеть задайте `MCP_AUTH_TOKEN` и закройте порт за обратным прокси-сервером с TLS.

## Docker

```bash
cp .env.example .env   # заполните ключи и MCP_AUTH_TOKEN
docker compose up -d --build
curl http://localhost:3000/healthz
```

## Лицензия

[Apache License 2.0](LICENSE)