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

MCP-сервер на Bun и TypeScript, который даёт ИИ-агенту прямой доступ к API Яндекс Директа.

Что это

Вы работаете с Директом обычными репликами агенту: «заведи перформанс-кампанию с оплатой за конверсии по этой цели», «выставь ставки по этим фразам», «покажи, что аукцион отдаёт по семантике», «сними отчёт за две недели». Сервер переводит запросы в вызовы API: создаёт и правит кампании, группы, объявления и ключевые фразы, назначает ставки, читает данные аукциона и выгружает статистику.

Мост берёт на себя механическую часть ведения кампаний — повторяющиеся операции с точными полями и пересчётами. Стратегические решения, тексты и подтверждение изменений остаются за вами и агентом.

Related MCP server: yandex-direct-mcp

Как проходит работа

MCP — это набор инструментов, которыми агент пользуется по ходу задачи, а не пошаговый мастер настройки. Одна операция проходит так:

1. Подключение и авторизация. Сервер запускается один раз в среде ИИ-агента. Авторизоваться можно через Click.ru или своим OAuth-токеном Яндекс Директа. Песочница доступна только в прямом режиме; через Click.ru сервер работает с боевым кабинетом.

2. Чтение состояния. Перед изменением агент получает кампании со статусами и статистикой, группы, объявления, фразы, ставки с данными аукциона, корректировки и справочники.

3. Изменение. Агент создаёт и правит текстовые кампании и единые перформанс-кампании, стратегии торгов, группы, объявления, фразы, ставки и демографические корректировки, а также привязывает счётчики и цели Метрики.

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

Сервер исполняет команды в кабинете сразу: встроенного предпросмотра или отмены нет. Настройте агента так, чтобы перед изменениями он показывал план и ждал вашего подтверждения. Для безопасной проверки есть сквозной прогон по песочнице.

Инструменты

В сервере 37 инструментов.

Скрипт scripts/sandbox-e2e.ts создаёт в песочнице цепочку ЕПК, проверяет группы, объявления, фразы, ставки, корректировки и отчёты, а затем удаляет созданное.

Что делает агент, а что остаётся человеку

Агент:

• переводит задачу в корректные вызовы API и заполняет обязательные поля;

• проверяет входные данные до отправки;

• читает состояние кабинета и справочники;

• после изменения перечитывает объект и проверяет результат по отчёту.

Человек:

• выбирает стратегию, бюджет, целевые CPA и CRR и режим работы с сетями;

• подтверждает план изменения до вызова инструмента;

• заранее создаёт или находит идентификаторы целей и счётчиков Метрики, быстрых ссылок, уточнений, видеодополнений и профиля организации;

• готовит креативы и выдаёт OAuth-токен Яндекса или ключи Click.ru.

Ограничения

• Сервер не подбирает семантику и не заменяет Вордстат. Данные аукциона доступны только по фразам, уже добавленным в кампанию.

• Сервер не управляет Метрикой как отдельным сервисом: он только привязывает к кампании готовые счётчики и цели по их идентификаторам.

• Быстрые ссылки, уточнения, видеодополнения и профиль организации нужно создать заранее; сервер принимает их готовые идентификаторы.

• На запись доступны только корректировки ставок по полу и возрасту.

• Комбинаторное объявление можно создать, но нельзя обновить — для изменения его нужно пересоздать.

• Доступны три отчёта с фиксированными полями и выгрузкой в TSV.

• Расписание показов, минус-слова уровня аккаунта и настройки за пределами перечисленных инструментов остаются в кабинете Директа.

Требования

• Bun 1.1+

Установка

Из npm — одной командой (нужен установленный Bun):

bunx @ai-hub-open/yandex-direct-mcp

Для подключения в конфиге MCP-клиента: "command": "bunx", "args": ["@ai-hub-open/yandex-direct-mcp"] плюс переменные окружения из раздела «Настройка».

Или из исходников:

git clone https://github.com/ai-hub-open/yandex-direct-mcp.git
cd yandex-direct-mcp
bun install

Настройка

Скопируйте .env.example в .env и заполните один из двух режимов (переменные окружения имеют приоритет над .env):

A. Через Click.ru — основной путь: токен без заявок на доступ к API, OAuth-токен Яндекса не нужен:

CLICK_RU_PROXY=true
CLICK_RU_TOKEN=<API-токен из профиля click.ru>
CLICK_RU_CLIENT_LOGIN=<логин аккаунта Яндекс.Директа>
CLICK_RU_USER_ID=<ID пользователя click.ru>   # только при работе из мастер-аккаунта

Токен создаётся в профиле https://click.ru/userinfo.html → поле «API Token» → «Создать». Аккаунт Яндекс.Директа должен быть подключён в Click.ru. Справка: https://help.click.ru/81, https://api.click.ru/V0/docs/.

Прокси Click.ru работает только с боевым API Яндекса (песочница недоступна).

B. Прямой режим — свой OAuth-токен Яндекс.Директа (единственный режим с песочницей):

YANDEX_DIRECT_TOKEN=y0__...
YANDEX_DIRECT_SANDBOX=false   # true — песочница

По умолчанию используется версия API v501 (обязательна для ЕПК); переключить можно через YANDEX_DIRECT_API_VERSION=v5.

Запуск

bun run src/index.ts          # stdio — для локальных MCP-клиентов
bun run src/index.ts --http   # HTTP-сервер на :3000

E2E-прогон на песочнице (создаёт и удаляет тестовые кампании; нужны YANDEX_DIRECT_TOKEN и YANDEX_DIRECT_SANDBOX=true):

bun run scripts/sandbox-e2e.ts

Подключение к Claude Code

.mcp.json в корне вашего проекта (см. также .mcp.json.example):

{
  "mcpServers": {
    "yandex-direct": {
      "command": "bun",
      "args": ["run", "/абсолютный/путь/к/yandex-direct-mcp/src/index.ts"],
      "env": {
        "CLICK_RU_PROXY": "true",
        "CLICK_RU_TOKEN": "<ваш токен>",
        "CLICK_RU_CLIENT_LOGIN": "<логин Директа>"
      }
    }
  }
}

Для прямого режима в env вместо CLICK_RU_* укажите YANDEX_DIRECT_TOKEN.

📋 Инструкция для AI-агента — скопируйте и передайте своему агенту (Claude Code / Codex), подставив ключи:

Установи и подключи MCP-сервер «Yandex Direct»: склонируй https://github.com/ai-hub-open/yandex-direct-mcp.git, проверь Bun (bun --version, если нет — установи с https://bun.sh), выполни bun install в корне репозитория. Зарегистрируй локальный stdio-MCP: команда bun, аргументы run <абсолютный_путь_к_репо>/src/index.ts, переменные окружения — мои ключи: CLICK_RU_PROXY=true, CLICK_RU_TOKEN=<...>, CLICK_RU_CLIENT_LOGIN=<...> (или YANDEX_DIRECT_TOKEN=<...> для прямого режима). Проверь tools/list и сообщи результат.

HTTP-режим

MCP_TRANSPORT=http MCP_PORT=3000 bun run src/index.ts

Переменные: MCP_PORT (3000), MCP_HOST (0.0.0.0), MCP_AUTH_TOKEN (если задан — запросы должны нести Authorization: Bearer <token>), MCP_ALLOWED_ORIGIN (CORS).

Несколько аккаунтов: данные доступа можно передавать в заголовках каждого запроса; они имеют приоритет над .env. Один сервер может обслуживать несколько клиентов:

X-Yandex-Token: <OAuth>              X-Click-Ru-Token: <токен>
X-Yandex-Sandbox: true|false         X-Click-Ru-User-Id: <ID>
X-Yandex-Api-Version: v501|v5        X-Client-Login: <логин Директа>

В режиме Click.ru по HTTP обязательны все три заголовка. Сервер можно запустить без данных доступа в .env — тогда они передаются в каждом запросе.

⚠️ Безопасность: при публикации в сеть задайте MCP_AUTH_TOKEN и закройте порт за обратным прокси-сервером с TLS.

Docker

cp .env.example .env   # заполните ключи и MCP_AUTH_TOKEN
docker compose up -d --build
curl http://localhost:3000/healthz

Лицензия

Apache License 2.0