# yandex-direct-mcp **Category:** 💻 Developer Tools **Repository:** https://github.com/ai-hub-open/yandex-direct-mcp **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/yandex-direct-mcp ## Description MCP server for Yandex Direct API: campaigns, ads, keywords, bids, reports. Click.ru or OAuth. ## Claude Desktop Quick Installation Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "yandex-direct-mcp": { "command": "npx", "args": ["-y","yandex-direct-mcp"] } } ``` ## Documentation & README # Yandex Direct MCP MCP-сервер для [Yandex Direct JSON API v5](https://yandex.ru/dev/direct/) на Bun + TypeScript. 50 инструментов: кампании (включая ЕПК, стратегии торгов и цели Метрики), группы объявлений, объявления (текстовые и комбинаторные), расширения (быстрые ссылки, уточнения), изображения, ставки и прогноз цены клика, корректировки ставок, ключевые фразы, отчёты, справочники. ## Требования - [Bun](https://bun.sh) 1.1+ ## Установка ```bash git clone https://github.com/ai-hub-open/yandex-direct-mcp.git cd yandex-direct-mcp bun install ``` ## Настройка Скопируйте `.env.example` в `.env` и заполните **один из двух режимов** (переменные окружения имеют приоритет над `.env`): **A. Прямой режим — свой OAuth-токен Яндекс.Директа:** ```bash YANDEX_DIRECT_TOKEN=y0__... YANDEX_DIRECT_SANDBOX=false # true — песочница ``` По умолчанию используется версия API **v501** (обязательна для ЕПК); переключить можно через `YANDEX_DIRECT_API_VERSION=v5`. **B. Через прокси [Click.ru](https://click.ru) — OAuth-токен Яндекса не нужен:** ```bash CLICK_RU_PROXY=true CLICK_RU_TOKEN= CLICK_RU_CLIENT_LOGIN=<логин аккаунта Яндекс.Директа> CLICK_RU_USER_ID= # только при работе из мастер-аккаунта ``` Токен создаётся в профиле `https://click.ru/userinfo.html` → поле «API Token» → «Создать». Аккаунт Яндекс.Директа должен быть подключён в Click.ru. Справка: `https://help.click.ru/81`, `https://api.click.ru/V0/docs/`. > Прокси Click.ru работает только с продакшн-API Яндекса (песочница недоступна). ## Запуск ```bash bun run src/index.ts # stdio — для локальных MCP-клиентов MCP_AUTH_TOKEN=<секрет> bun run src/index.ts --http # HTTP-сервер на :3000 ``` В HTTP-режиме `MCP_AUTH_TOKEN` обязателен — см. [HTTP-режим](#http-режим). ## Тесты Обязательный гейт перед изменениями — мок-тесты (тела запросов к API, без сети) и тесты HTTP-транспорта (авторизация, CORS): ```bash bun run test ``` ## Релизы Публикация автоматическая: при выпуске релиза на GitHub workflow прогоняет проверки, публикует пакет в npm и обновляет запись в реестре MCP. Тег релиза должен совпадать с версией в `package.json` (версия `0.5.0` → тег `v0.5.0`), иначе публикация останавливается. Версию поднимают в трёх местах: `package.json`, `server.json` (корневое поле и `packages[0].version`) и `CHANGELOG.md`. Авторизация в обоих реестрах идёт через доверенного издателя по GitHub OIDC — долгоживущих токенов в секретах нет. E2E-прогон на песочнице (создаёт и удаляет тестовые кампании; нужны `YANDEX_DIRECT_TOKEN` и `YANDEX_DIRECT_SANDBOX=true`): ```bash 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`): ```json { "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-режим ```bash 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: X-Click-Ru-Token: <токен> X-Yandex-Sandbox: true|false X-Click-Ru-User-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 ```bash 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, и **ничего не изменит**. Валидация параметров при этом выполняется полностью, так что предпросмотр ловит ошибки до записи: ```json { "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'ы, а доля окна не критична. Решение пересмотреть, если число инструментов заметно вырастет. Замер воспроизводится: ```bash 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](LICENSE)