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

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

Зарегистрируйте приложение: https://oauth.yandex.ru/
Права: Яндекс Директ API
Получите токен: документация
Положите в .env как YANDEX_DIRECT_TOKEN=... (права 600)
Для агентского доступа: 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