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

v0.5.0

Published

17 days ago

MCP server for Yandex Direct API (JSON v5) — Bun/TypeScript port

0High
0Medium
0Low

dmitry-zhokhov

akainq

mcp model-context-protocol yandex-direct ppc advertising click-ru bun

Yandex Direct MCP

MCP-сервер для Yandex Direct JSON API v5 на Bun + TypeScript.

50 инструментов: кампании (включая ЕПК, стратегии торгов и цели Метрики), группы объявлений, объявления (текстовые и комбинаторные), расширения (быстрые ссылки, уточнения), изображения, ставки и прогноз цены клика, корректировки ставок, ключевые фразы, отчёты, справочники.

Требования

Bun 1.1+

Установка

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

Настройка

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

A. Прямой режим — свой OAuth-токен Яндекс.Директа:

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

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

B. Через прокси Click.ru — 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 Яндекса (песочница недоступна).

Запуск

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

В HTTP-режиме MCP_AUTH_TOKEN обязателен — см. HTTP-режим.

Тесты

Обязательный гейт перед изменениями — мок-тесты (тела запросов к API, без сети) и тесты HTTP-транспорта (авторизация, CORS):

bun run test

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

bun run test:sandbox

Ограничения песочницы Яндекса (в проде их нет; часть лечится пересозданием песочницы в кабинете — Инструменты → Настройки API → Песочница). E2E помечает такие шаги как «пропуск», а не как ошибку:

adgroups.add возвращает ID, но группа не появляется в adgroups.get, а ads.add отвечает «Группа объявлений не найдена» — заливка объявлений в песочнице непроверяема;
bidmodifiers.add возвращает ID, но bidmodifiers.get всегда пуст при любом фильтре;
сервис sitelinks отвечает «Сервис временно недоступен».

Подключение к 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 MCP_AUTH_TOKEN=<секрет> bun run src/index.ts

MCP_AUTH_TOKEN обязателен: без него сервер не стартует, потому что открытый эндпоинт даёт полный доступ к рекламному кабинету. Запросы должны нести Authorization: Bearer <секрет>. Если сервер закрыт reverse-proxy или слушает только localhost, запуск без авторизации подтверждается явно: MCP_ALLOW_ANONYMOUS=true.

Переменные: MCP_PORT (3000), MCP_HOST (0.0.0.0), MCP_AUTH_TOKEN, MCP_ALLOW_ANONYMOUS, MCP_ALLOWED_ORIGIN. CORS-заголовки по умолчанию не выдаются (MCP-клиенты ходят не из браузера) — разрешите конкретный источник через MCP_ALLOWED_ORIGIN, если он действительно нужен.

| Метод + путь | Назначение | |---|---| | POST /mcp | JSON-RPC 2.0 запрос (или батч) | | GET /healthz | health check | | GET /mcp/tools | список инструментов (отладка) |

Multi-tenant: креды можно передавать заголовками на каждый запрос (перекрывают .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: <логин Директа>
                                     X-Click-Ru-Base-Url: <база API Click.ru>

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

⚠️ Безопасность: при публикации в сеть держите MCP_AUTH_TOKEN заданным и закройте порт за reverse-proxy с TLS. Запуск с MCP_ALLOW_ANONYMOUS=true на MCP_HOST=0.0.0.0 открывает кабинет всем, кто дотянется до порта.

Docker

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

Инструменты (50)

Campaigns: get / add / update / delete / suspend / resume — текстовые кампании и ЕПК (единая перформанс-кампания), стратегии торгов с недельным бюджетом, счётчики Метрики и приоритетные цели
AdGroups: get / add / update / delete — включая группы ЕПК (UnifiedAdGroup)
Ads: get / add / add_responsive (комбинаторное объявление ЕПК) / update (текстовые и комбинаторные) / delete / suspend / resume / moderate
AdImages: add (с кропом) / get
Sitelinks: add / get / delete — наборы быстрых ссылок
AdExtensions: add / get / delete — уточнения
BidModifiers: devices / regional / retargeting / demographics / set / delete / get — корректировки ставок на запись и чтение
Keywords: get / add / update / delete / suspend / resume
KeywordBids: set / get — ставки по фразам и данные аукциона (объёмы трафика, цены)
Forecast: forecast_bids — прогноз цены клика и трафика по произвольным фразам без создания кампании
Reports: campaign / ad / search_queries / custom (произвольный тип и набор столбцов)
Dictionaries: regions / currencies / interests / all

Предпросмотр записи (dry-run)

Любой инструмент, меняющий кабинет, принимает dry_run: true — вернёт тело запроса, которое ушло бы в API, и ничего не изменит. Валидация параметров при этом выполняется полностью, так что предпросмотр ловит ошибки до записи:

{ "name": "yandex_direct_campaigns_add", "arguments": { "name": "Тест", "start_date": "2026-08-01", "dry_run": true } }

Отказы API

Любой отказ Директа возвращается агенту помеченным как ошибка, с причиной и следующим шагом — включая частичные отказы, когда запрос выполнен, но отдельные объекты не приняты. Пример реального ответа:

Запрос к API Яндекс.Директа отклонён (код 152).
Причина: Недостаточно баллов
Баллы API: потрачено 0, осталось 0 из 64000
Что делать: Закончились баллы API (units) — это дневной лимит на обращения
к Директу, а не проблема моста. Баллы начисляются раз в 60 минут...

Ниже подсказки всегда идёт полный ответ API — для разбора нестандартных случаев.

Расход контекста

Полное описание инструментов (tools/list) занимает около 16 800 токенов — 8,4% окна на 200k и 1,7% на 1M. Три четверти веса приходятся на JSON-схемы параметров, на текстовые описания — 17%.

Сокращённый режим (отдельные методы «список / описание / вызов») решено не вводить: выигрыш не оправдывает потерю штатной валидации аргументов на стороне клиента и лишние round-trip'ы, а доля окна не критична. Решение пересмотреть, если число инструментов заметно вырастет.

Замер воспроизводится:

bun run scripts/measure-context.ts

Что осознанно вне этого моста

Мост покрывает только API Яндекс.Директа. Смежные задачи живут в других контурах и сюда не встраиваются:

Вордстат (подбор семантики, частота запросов, спрос) — отдельный API Яндекса, не Директ. Остаётся за скиллом или отдельным MCP. Граница проходит по смыслу данных: частота и спрос — там, аукционные деньги (прогноз цены клика) — здесь, инструментом forecast_bids.
Метрика как сервис (создание целей, чтение статистики, сегменты) — отдельный API Метрики. Мост Директа привязывает цель по готовому ID (counter_ids, priority_goals, goal_id в стратегиях) — на этом граница.

Причина: «одно подключение к Яндексу = Директ + Метрика + Вордстат» — это уровень пакета или прокси (например Click.ru), а не одного сервера. Смешение трёх API в одном мосте увеличивает связность и зону отказа.

Лицензия

Apache License 2.0