Yandex Direct MCP Server

Model Context Protocol (MCP) сервер, который превращает Claude в профессионального директолога. Полное управление рекламой в Яндекс.Директе через официальный API v5 — прямо из диалога с AI, с защитой от случайных денежных действий.

!status !python !protocol !api

---

Проблема

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

Решение

MCP-сервер отдаёт Claude 20 инструментов поверх Yandex Direct API v5. Теперь рекламой можно управлять на естественном языке:

«Покажи кампании с расходом за неделю, найди ключи с CTR ниже 2% и предложи, какие ставки снизить.»

Claude сам выбирает нужные инструменты, строит отчёт, предлагает изменения — но никогда не вносит правки без явного подтверждения (см. dry-run ниже).

Чем это интересно как инженерная работа

Дизайн безопасного агентного интерфейса к деньгам: каждый мутирующий вызов по умолчанию ничего не делает, пока человек не подтвердит.
Работа с «неудобным» внешним API: асинхронные отчёты с поллингом, микро-единицы валюты, песочница vs прод.
Чистый MCP-сервер на официальном SDK, подключается и к Claude Desktop, и к Claude Code.

---

Архитектура

┌─────────────────┐     MCP (stdio)      ┌──────────────────────┐    HTTPS / JSON     ┌─────────────────────┐
│  Claude          │ ◄──────────────────► │  yandex-direct-mcp   │ ◄─────────────────► │  Yandex Direct       │
│  (Desktop / Code)│   20 tools           │  src/server.py       │   API v5            │  API (sandbox/prod)  │
└─────────────────┘                       └──────────────────────┘                     └─────────────────────┘
                                               │
                                               ├─ dry-run guard (confirm=False по умолчанию)
                                               ├─ micros-конвертация (1 ₽ = 1 000 000 micros)
                                               ├─ async-отчёты с поллингом (до 5 мин)
                                               └─ переключатель окружения YDIRECT_ENV (sandbox/production)

Транспорт: stdio MCP — сервер запускается локально, токен живёт только в env на машине пользователя, наружу не уходит.
Окружение: один флаг YDIRECT_ENV переключает между песочницей и боевым аккаунтом.

Стек

Python 3.11+ · MCP SDK (mcp[cli]) · httpx · Yandex Direct API v5

---

Инструменты (20)

Чтение — безопасно, без подтверждения

| Инструмент | Что делает | |---|---| | list_campaigns | Кампании с фильтрами по статусу/типу | | list_ad_groups | Группы объявлений по кампаниям | | list_ads | Объявления по группам или кампаниям | | list_keywords | Ключевые слова с текущими ставками | | get_balance | Баланс и финансы аккаунта | | get_report | Универсальный отчёт (async polling, до 5 мин) |

Кампании — с dry-run защитой

| Инструмент | Что делает | |---|---| | add_campaigns | Создать кампании (TEXT_CAMPAIGN, стратегии на выбор) | | update_campaigns | Название, даты, бюджет, стратегия | | suspend_campaigns / resume_campaigns | Пауза / возобновление | | archive_campaigns | Архивировать (необратимо) |

Группы, объявления, ключи — с dry-run защитой

| Инструмент | Что делает | |---|---| | add_ad_groups | Создать группы (с геотаргетингом) | | add_ads / update_ads | Создать / изменить объявления | | moderate_ads / delete_ads | Модерация / удаление | | add_keywords / update_keywords / delete_keywords | Управление ключами | | set_keyword_bids | Массовое изменение ставок (bulk) | | add_negative_keywords | Минус-слова для кампаний и групп |

Защита от ошибок (ключевая фича)

Все мутирующие инструменты по умолчанию работают в dry-run (confirm=False) — показывают план запроса, но ничего не отправляют. Реальное выполнение — только с confirm=True. Claude физически не может потратить бюджет без явного подтверждения человека.

Все ставки и бюджеты — в микро-единицах (1 ₽ = 1 000 000 micros); напоминание встроено в каждый «денежный» инструмент.

---

Установка

git clone https://github.com/OlegRadinuk/yandex-direct-mcp.git
cd yandex-direct-mcp
uv venv && uv pip install -e .

Получение OAuth-токена

На https://oauth.yandex.ru/ создать приложение, платформа «Веб-сервисы», Redirect URI https://oauth.yandex.ru/verification_code.
Права: «Яндекс Директ» → direct:api.
Открыть https://oauth.yandex.ru/authorize?response_type=token&client_id=ВАШ_CLIENT_ID — access_token из адресной строки и есть токен.
Для песочницы — включить API-доступ к sandbox в настройках Директа.

Подключение к Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "yandex-direct": {
      "command": "uv",
      "args": ["--directory", "/path/to/yandex-direct-mcp", "run", "python", "src/server.py"],
      "env": { "YDIRECT_TOKEN": "ваш_токен", "YDIRECT_ENV": "sandbox" }
    }
  }
}

Перезапустить Claude Desktop. Когда готовы к боевым кампаниям — "YDIRECT_ENV": "production".

⚠️ Токен — секрет. Хранится только в env на вашей машине, никогда не коммитьте его в репозиторий.

---

Примеры сессий

Запуск кампании с нуля: add_campaigns (dry-run → проверить → confirm) → add_ad_groups → add_ads → add_keywords → add_negative_keywords → moderate_ads → resume_campaigns.

Анализ и оптимизация: get_report (статистика) → list_keywords → set_keyword_bids (скорректировать ставки) → list_ads (найти низкий CTR) → update_ads.

Ограничения

Поддержан тип TEXT_CAMPAIGN; UNIFIED_CAMPAIGN / MOBILE_APP_CAMPAIGN — в планах.
Токен передаётся через env (не через параметры) — на одну конфигурацию один аккаунт.
Нет автотестов против sandbox (в roadmap).
Валидация входных данных — базовая (Pydantic-модели в планах).

Roadmap

[ ] keywords_research — оценка частотности (KeywordsResearch service)
[ ] UNIFIED_CAMPAIGN и MOBILE_APP_CAMPAIGN
[ ] Pydantic-модели для валидации входа
[ ] MCP Resources: регионы, языки, часовые пояса (справочники с кэшем)
[ ] Тесты против sandbox

License

MIT — см. LICENSE.

Yandex Direct MCP Server