yandex-direct-mcp

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

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

🤖 Агенту: прочитай 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, чтобы случайно не потрогать чужой продукт.

---

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

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:

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

Остальные клиенты — в AGENTS.md и examples/.

---

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

1. Зарегистрируйте приложение: https://oauth.yandex.ru/
2. Права: Яндекс Директ API
3. Получите токен: документация
4. Положите в .env как YANDEX_DIRECT_TOKEN=... (права 600)
5. Для агентского доступа: YANDEX_DIRECT_CLIENT_LOGIN=login_клиента

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

---

projects.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.

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

---

Связанное

• Arckep — AI image/video/chat
• Wordstat — спрос (отдельный API, не этот MCP)
• Yandex Direct API