DirectAI MCP

Локальный MCP-сервер для Яндекс Директа: ИИ-ассистент читает статистику и управляет вашими кампаниями через официальный API. Сервер работает на вашем компьютере, для одного пользователя и ничего не выставляет в интернет.

Поддерживается Windows 11 и PowerShell. macOS и Linux не тестировались. Сервер бесплатный; нужен только одобренный доступ к API Директа.

Работает с MCP-клиентами: OpenCode, Codex, Claude Code, Claude Desktop, Hermes и другими.

ИИ-агент? Следуй AGENTS.md.

Что умеет

• Статистика и аналитика. Показы, клики, расход, конверсии по кабинетам, кампаниям, группам, объявлениям, фразам, запросам, регионам, площадкам и устройствам. Сравнение периодов, произвольные отчёты.

• Управление кампаниями. Создание и изменение кампаний, групп, объявлений и фраз; ставки, корректировки, минус-фразы, быстрые ссылки; ключевые цели, дневной бюджет, расписание показов.

• Яндекс Метрика. Визиты, отказы, цели и CR по источникам; связка расходов Директа с заявками и CPA; запись целей счётчика.

• Wordstat и исследование спроса. Частотность, динамика, регионы, прогноз ставок по существующим фразам и спрос по новым.

• Ретаргетинг и аудитории. Условия, привязки к группам, сегменты; запись по умолчанию выключена.

• Аудит и журнал. Разбор кампании с планом улучшений, история правок, снимки результатов, заметки и проверка ручных изменений.

Полный список (57 действий чтения и 25 записи) — в docs/actions.md.

Related MCP server: MCP «Яндекс Директ»

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

1. Требования. Windows 11, аккаунт Директа с кампанией, приложение на oauth.yandex.ru и одобренная заявка на доступ к API. Начните с заявки: одобрение занимает до нескольких дней.

2. Установка.

   winget install --id Git.Git -e --accept-package-agreements --accept-source-agreements
   winget install --id astral-sh.uv -e --accept-package-agreements --accept-source-agreements
   cd $env:USERPROFILE
   git clone https://github.com/perejaslav/directai-mcp.git directai-mcp
   cd $env:USERPROFILE\directai-mcp
   uv tool install --editable .
   uv tool update-shell
   directai-mcp init

3. Аккаунты. Впишите реальный логин в %USERPROFILE%\.directai\accounts.toml ([auth] login и [aliases.*] вместо демо-примеров).

4. Токен. Получите его по ссылке из пройденной авторизации и введите скрытым полем в своём терминале:

   directai-mcp set-token --login ВАШ_ЛОГИН

   Токен хранится в Credential Manager Windows. Не передавайте его в чат, аргументы командной строки или файлы репозитория.

5. Проверка.

   directai-mcp check
   directai-mcp probe

   check обращается к API Директа (мало баллов: проверка доступа и список кампаний) и показывает OK по каждому аккаунту. probe — локальная проверка MCP без обращения к рекламному API: две строки OK (версия сервера и найденный инструмент), баллы не тратятся.

6. Подключение клиента — см. раздел ниже, затем перезапустите харнес.

Подробная процедура: создание OAuth-приложения, подача заявки, отдельные токены Метрики, Вебмастера и Wordstat — в docs/getting-started.md.

Подключение к ИИ-агенту

Команда запуска везде одна — directai-mcp без аргументов (STDIO). Пример для OpenCode, файл %USERPROFILE%\.config\opencode\opencode.json:

{
  "mcp": {
    "directai-mcp": {
      "type": "local",
      "command": ["directai-mcp"],
      "enabled": true
    }
  }
}

Готовые блоки для Codex, Claude Desktop, Claude Code и Hermes — в examples/harness-configs.md. Если клиент не видит команду, укажите полный путь: (Get-Command directai-mcp).Source.

Примеры

Расходы и конверсии за неделю.

Покажи расход, клики и конверсии по всем аккаунтам за последние 7 дней и сравни с предыдущей неделей.

Агент вызовет stats_summary и stats_compare — цифры должны совпасть с веб-интерфейсом Директа.

Аудит кампании.

Разбери кампанию 900000456: что изменилось за месяц, где потери, что улучшить.

Агент прочитает журнал, настройки и статистику, покажет отчёт и план улучшений — без записи.

Расписание показов.

Включи показы в субботу с 12 до 13, остальные дни не трогай.

{"name": "campaigns_update",
 "params": {"account": "active", "campaign_ids": [900000456],
            "schedule": {"days": [6], "from_hour": 12, "to_hour": 13}}}

Меняются только указанные дни; Пн–Пт сохраняются. Правила расписания — в docs/actions.md.

Любая запись проходит предварительный просмотр «было → станет» и ваше явное подтверждение: plan_write → согласие → apply_write. Прямых изменений без плана нет.

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

• Guard. Защита включена по умолчанию и сверяет живое имя кампании через API. В режиме block политические запреты (бюджеты, стратегия, ключевые цели, переименование, модерация, пауза кампаний, правки вне тестовых) блокируют операцию. В режиме confirm те же операции допускаются только через план с пометкой «⚠ ОПАСНАЯ ОПЕРАЦИЯ» и явное подтверждение владельца на этот план.

• Обычные боевые правки идут через план в обоих режимах: фразы (добавление, пауза/запуск), объявления (создание, тексты, ссылки), ссылки и уточнения, регионы групп, минус-фразы (добавление), ставки и корректировки (кроме удаления), ExcludedSites (добавление), расписание. Правка набора минус-фраз кампании и пауза объявлений сюда не входят — это политические операции.

• Жёсткие ограничения от режима не зависят: объект не найден, поле read_only, выключенные Аудитории и ретаргетинг, сегмент без префикса [TEST DirectAI], неизвестное действие.

• План и проверка. План живёт 15 минут и применяется ровно один раз. После записи сервер сам перечитывает объект (read-back) и сверяет результат; неясный итог помечается unverified и вручную проверяется.

• Журнал. Все операции DirectAI пишутся в journal.sqlite; ручные правки в кабинете видны через changes_check.

• Токены. Только Credential Manager или переменная окружения. В логи и URL не попадают; текст блокировки guard — защита, а не ошибка, обходить её нельзя.

Подробно: docs/safety.md.

Документация

Лицензия — LICENSE, авторство части знаний — NOTICE.md.