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

Related MCP server: yandex-marketing-mcp

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

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

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

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

Полный список — при старте 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