Yandex Direct MCP Server

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

---

Проблема

Управление контекстной рекламой — это рутина: десятки кампаний, сотни объявлений и ключей, ставки в неудобных микро-единицах, отчёты через асинхронный 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-токена

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