# Yandex Direct MCP Server

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

![status](https://img.shields.io/badge/status-working-success)
![python](https://img.shields.io/badge/python-3.11%2B-blue)
![protocol](https://img.shields.io/badge/MCP-1.2%2B-8A2BE2)
![api](https://img.shields.io/badge/Yandex%20Direct-API%20v5-FC3F1D)

---

## Проблема

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

---

## Установка

```bash
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`:

```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](LICENSE).