# yandex-direct-mcp

**Open-source MCP-сервер для [Яндекс Директ](https://direct.yandex.ru/)** — ~80 инструментов, чтобы ИИ (Claude, Cursor, Claude Code, Grok, Windsurf…) мог **смотреть и (по явному разрешению) менять** рекламный кабинет: поиск, РСЯ, ключи, минуса, бюджеты, автотаргетинг, поисковые запросы, max-conv, видео-расширения.

Сделано в проде [Arckep](https://arckep.ru) (AI-студия).  
**Статья с установкой:** https://arckep.ru/blog/how-to/yandex-direct-mcp-open-source

> 🤖 **Агенту:** прочитай [`AGENTS.md`](./AGENTS.md) и разверни MCP сам.

---

## Зачем

Кабинет Директа — ручной и медленный. MCP даёт агенту безопасный контур:

- **Read** — кампании, группы, ключи, объявления, минуса, exclude-площадки, device/demo, стратегия, funds  
- **Stats** — cost/clicks/CTR, breakdown по Placement/Device/…, **поисковые запросы (SQ)**  
- **Write** (только `allow_write=true`) — бюджет, suspend/resume, минуса, exclude, гео, ставки, AT, max-conv, тексты объявлений, launch pack  
- **Escape** — `direct_rpc` на любой `service.method` API v5/v501  

Один OAuth-токен = весь кабинет. Несколько брендов размечаются в `projects.json`, чтобы случайно не потрогать чужой продукт.

---

## Быстрый старт

```bash
git clone https://github.com/gmen1057/yandex-direct-mcp.git
cd yandex-direct-mcp
npm install
cp .env.example .env
# YANDEX_DIRECT_TOKEN=...
npm run smoke
```

### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "yandex-direct": {
      "command": "node",
      "args": ["/полный/путь/yandex-direct-mcp/index.mjs"],
      "env": {
        "YANDEX_DIRECT_TOKEN": "ваш_токен"
      }
    }
  }
}
```

Остальные клиенты — в [`AGENTS.md`](./AGENTS.md) и `examples/`.

---

## Токен Директа

1. Зарегистрируйте приложение: https://oauth.yandex.ru/  
2. Права: **Яндекс Директ API**  
3. Получите токен: [документация](https://yandex.ru/dev/direct/doc/dg/concepts/auth-token.html)  
4. Положите в `.env` как `YANDEX_DIRECT_TOKEN=...` (права `600`)  
5. Для агентского доступа: `YANDEX_DIRECT_CLIENT_LOGIN=login_клиента`

API: `https://api.direct.yandex.com/json/v501` + Reports v5.

---

## projects.json

```json
{
  "projects": {
    "shop": {
      "label": "Интернет-магазин",
      "name_prefixes": ["[shop]"],
      "campaign_ids": [123456789]
    }
  }
}
```

- **Write** требует `project=shop` (или другой ваш ключ) — не `all`.  
- Префиксы в `Name` кампании (`[shop] …`) помогают авторазметке.

---

## Безопасность write

| Правило | Смысл |
|---------|--------|
| `allow_write=true` | без флага — только dry-run план |
| `project=<ключ>` | нельзя `all` на мутациях |
| dry_run | явно посмотреть payload |
| логи | `logs/*.jsonl` при write |

**Не** включайте write «чтобы проверить». Сначала `direct_ping` / `direct_list_campaigns` / `direct_report`.

---

## Что умеет (кратко)

| Класс | Примеры tools |
|-------|----------------|
| Read | `direct_ping`, `list_campaigns`, `get_campaign`, `list_keywords`, `list_ads`, `get_negatives`, `list_bidmodifiers` |
| Отчёты | `direct_report`, `report_breakdown`, **`report_search_queries`**, `report_raw` |
| Бюджет / state | `set_daily_budget`, `set_search_weekly_budget`, `set_network_weekly_budget`, `suspend/resume/archive/unarchive` |
| Качество | `set_excluded_sites`, `set_negatives`, `set_group_negatives`, `set_region_excludes`, device/demo bidmods |
| Ключи / AT | `add/delete/set_keyword_*`, **`get/set_autotargeting`**, `get_keyword_bids` |
| Стратегия | **`set_max_conv`**, `set_strategy`, `set_priority_goals`, `get_strategy` |
| Креатив | `add_ads`, **`update_ad_text`**, `update_ad_href`, `upload_adimage`, sitelinks/callouts, **video** |
| Launch | **`direct_launch_pack`** — кампания → группы → ключи → ads → moderate → pin |
| Escape | `direct_rpc` |

Полный список — при старте MCP (~80 tools).

---

## Gotchas (РФ / Директ)

- Деньги API в **микросах**: 1 ₽ = 1 000 000; tools принимают **рубли**.  
- `DailyBudget` + `WeeklySpendLimit` в одном `campaigns.update` → ошибка **4004** — два шага.  
- Soft **Conversions** в отчётах ≠ оплаты в CRM.  
- ЕПК / UNIFIED: ≤3 ads в группе; `ACCEPTED OFF` часто пул, не бан.  
- В заголовках: не `₽`, длинное тире `—`, слово VPN — модерация.  
- Ad Id — **int64**, не терять точность.  
- AT: `AutotargetingCategories` — plain array; ставки AT через `keywordbids.set`.

---

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

- Node.js ≥ 18  
- Сеть до `api.direct.yandex.com`  
- Units API (дневной лимит кабинета)

---

## Лицензия

MIT — см. [LICENSE](./LICENSE).

Не аффилирован с Яндексом. «Яндекс» и «Директ» — товарные знаки правообладателей.

---

## Связанное

- [Arckep](https://arckep.ru) — AI image/video/chat  
- [Wordstat](https://yandex.ru/support2/wordstat/) — спрос (отдельный API, не этот MCP)  
- [Yandex Direct API](https://yandex.ru/dev/direct/)