This MCP server provides access to the Yandex Direct API for managing advertising resources. It supports operations covering campaigns, ads, keywords, bids, and reports, and can be used with authentication flows including Click.ru or OAuth. The server is focused on Yandex Direct integrations for developers building tooling around these entities.

🛠️ Key Features

Yandex Direct API integration
Campaigns, ads, keywords, bids, and reports support
Authentication options: Click.ru or OAuth

🚀 Use Cases

Create or manage Yandex Direct advertising campaigns
Maintain ad and keyword structures
Review bid settings and generate reports
Build developer tools that automate Yandex Direct workflows

⚡ Developer Benefits

Centralized MCP access to Yandex Direct resources
Direct coverage of common Direct entities (campaigns, ads, keywords, bids, reports)
Works with Click.ru or OAuth-based authentication

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

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

Что это

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

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

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

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

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

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

Инструменты

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

Область	Инструменты	Что позволяют сделать
Кампании	get, add, update, delete, suspend, resume	Создавать и вести текстовые кампании и ЕПК; задавать стратегии для поиска и РСЯ, недельный бюджет и потолок ставки; привязывать счётчики Метрики, приоритетные цели и модель атрибуции
Группы объявлений	get, add, update, delete	Создавать группы с регионами показа и минус-фразами; создавать группы ЕПК; добавлять UTM-параметры
Объявления	get, add, add_responsive, update, delete, suspend, resume, moderate	Создавать текстово-графические и комбинаторные объявления, править их, останавливать, возобновлять и отправлять на модерацию
Изображения	add, get	Загружать изображения с обрезкой 1:1 или 16:9 и получать список загруженных файлов
Ставки по фразам	set, get	Выставлять ставки по фразе, группе или кампании и читать данные аукциона
Корректировки ставок	demographics, get	Задавать корректировки по полу и возрасту и читать действующие корректировки
Ключевые фразы	get, add, update, delete, suspend, resume	Добавлять и править фразы, останавливать и возобновлять показы
Отчёты	campaign, ad, search_queries	Получать статистику по кампаниям и объявлениям и отчёт по поисковым запросам
Справочники	regions, currencies, interests, all	Получать идентификаторы регионов, валюты, интересы и другие справочные данные

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

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

Агент:

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

Человек:

выбирает стратегию, бюджет, целевые CPA и CRR и режим работы с сетями;
подтверждает план изменения до вызова инструмента;
заранее создаёт или находит идентификаторы целей и счётчиков Метрики, быстрых ссылок, уточнений, видеодополнений и профиля организации;
готовит креативы и выдаёт OAuth-токен Яндекса или ключи Click.ru.

Ограничения

Сервер не подбирает семантику и не заменяет Вордстат. Данные аукциона доступны только по фразам, уже добавленным в кампанию.
Сервер не управляет Метрикой как отдельным сервисом: он только привязывает к кампании готовые счётчики и цели по их идентификаторам.
Быстрые ссылки, уточнения, видеодополнения и профиль организации нужно создать заранее; сервер принимает их готовые идентификаторы.
На запись доступны только корректировки ставок по полу и возрасту.
Комбинаторное объявление можно создать, но нельзя обновить — для изменения его нужно пересоздать.
Доступны три отчёта с фиксированными полями и выгрузкой в TSV.
Расписание показов, минус-слова уровня аккаунта и настройки за пределами перечисленных инструментов остаются в кабинете Директа.

Требования

Bun 1.1+

Установка

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

bash

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

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

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

bash

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-токен Яндекса не нужен:

bash

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-токен Яндекс.Директа (единственный режим с песочницей):

bash

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

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

Запуск

bash

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

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

bash

bun run scripts/sandbox-e2e.ts

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

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

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

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

code

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

bash

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

Лицензия

Apache License 2.0

io.github.ai-hub-open/yandex-direct-mcp

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

Topics

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

Что это

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

Инструменты

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

Ограничения

Требования

Установка

Настройка

Запуск

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

HTTP-режим

Docker

Лицензия

Install

Configuration