Яндекс.Директ

yandex-direct-mcp-plus

アシスタントとの対話から、Yandex.Direct のコンテキスト広告を管理できます。キャンペーンの作成、検索クエリの分析、除外キーワードの整理、入札単価の修正、費用の確認まで、管理画面のセクションを切り替える必要はありません。Claude Code、Claude Desktop、Cursor など、あらゆる MCP クライアントで動作します。

• 60 個のツールがあり、そのうち 25 個は読み取り専用です。キャンペーンと戦略、グループ、広告と審査、キーフレーズと入札単価、除外キーワードと共有セット、クイックリンク、補足文、画像、名刺、入札単価調整、リターゲティング、オーディエンスターゲットと動的ターゲット、フィード、配信スケジュール、統計、検索クエリ、残高、リファレンスデータを扱えます。
• 金額は入力時も出力時もルーブルです。API のマイクロ単位への変換はサーバーが行います。代理店モード（Client-Login）にも対応しています。
• ID は文字列（"1915016273214320641"）です。Direct の 64 ビット識別子は JavaScript の数値では正確に表せず、気付かないうちに精度が失われるためです。
• **実際の広告です。**Direct にはテスト環境がありません。費用が発生するツールと、取り消せない削除については、データを変更する操作のセクションに記載しています。
• **テレメトリはありません。**サーバーが送信するのは、Yandex API へのリクエストのみです。

目次

• できること — 自然な文章でのリクエスト例
• インストール — Claude Code、Claude Desktop、Cursor、ソースからのインストール
• トークン — 取得方法と必要な環境変数
• データを変更する操作 — 予算を消費する操作と取り消せない操作
• ツール — 説明付きの全一覧
• 開発 — ビルド、テスト、アーキテクチャ

できること

チャットで自然な文章を入力すると、サーバーが適切なツールを自動で選択します。

Собери кампанию «Летняя распродажа»: бюджет 5000 ₽/день, старт 1 мая, показы будни 9–21
Добавь минус-фразы «бесплатно» и «скачать» в кампанию 12345, не затерев остальные
Посмотри поисковые запросы за месяц и предложи, что заминусовать
Подними ставку до 25 ₽ там, где CTR выше 8%, а показов меньше сотни
Что изменилось в кампаниях со вчера?
Покажи расход по кампаниям за неделю и баланс аккаунта
Найди код региона для Новосибирска

全一覧はツールのセクションをご覧ください。

インストール

Node.js 22 以降と Direct の OAuth トークンが必要です（取得方法）。サーバーを別途インストールする必要はありません。クライアントが npx 経由でパッケージを起動し、stdio で通信します。

Claude Code

claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y yandex-direct-mcp-plus

Claude Desktop、Cursor などのクライアント

クライアントの MCP サーバー設定ファイル（claude_desktop_config.json、.cursor/mcp.json など）に、次のエントリを追加します。

{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "yandex-direct-mcp-plus"],
      "env": { "YANDEX_DIRECT_TOKEN": "ваш_токен" }
    }
  }
}

代理店トークンの場合、env に YANDEX_DIRECT_LOGIN も必要です。詳しくはトークンをご覧ください。

ソースからのインストール

git clone [email protected]:Pavelsiba/yandex-direct-mcp-plus.git
cd yandex-direct-mcp-plus
npm ci
npm run build

クライアントの設定では、npx の代わりに "command": "node" を指定し、args には dist/app/index.js の絶対パスを指定します。

リモートサーバー

同じサーバーを自分のマシン上で HTTP 経由で起動できます。Docker 内で起動したり、HTTPS 対応の nginx の背後に置いたりすれば、Node をインストールせずに claude.ai、スマートフォン、Claude Desktop からアドレスを指定して接続できます。アクセスはシークレットで保護されます。設定方法は docs/deploy.md をご覧ください。

トークン

OAuth トークンは、Yandex OAuth に登録したアプリケーションに Direct API へのアクセス権を付与して発行します。詳しくはアプリケーションの登録とトークンの取得をご覧ください。API へのアクセスはDirect のインターフェースから申請する必要があります。審査には 1 時間から数日かかります。

サーバーは、クライアントがプロセスに渡す環境変数からのみ設定を読み込みます。

• YANDEX_DIRECT_TOKEN — OAuth トークンです。これがなくてもサーバーは起動しますが、ツールを呼び出すとエラーが返されます。
• YANDEX_DIRECT_LOGIN — 広告主のログイン名です。Client-Login ヘッダーに設定されます。代理店トークンの場合のみ必要です。指定しない場合、リクエストはクライアントのアカウントではなく、代理店自身のアカウントに送信されます。

Что меняет данные

Тестовой среды у Яндекс.Директа больше нет: песочница отключена с июля 2026, и любой вызов идёт по боевому аккаунту. Отлаживать сценарии приходится на отдельной кампании, оставленной черновиком, — показов она не даёт и потому не тратит бюджет, пока не пройдёт модерацию и не будет включена.

Граница проходит не по «чтение или запись», а по скорости, с которой действие превращается в деньги.

Только читают все list_*, get_* и справочники. Вызвать их безопасно всегда.

Тратят бюджет или запускают показы:

Инструмент	Чем именно
manage_campaigns	resume — включает показы остановленной кампании
manage_ads	resume и moderate — возвращает объявления в показ
moderate_ads	Отправляет объявления на модерацию, после неё начнутся показы
update_campaign	Меняет дневной бюджет
set_keyword_bids	Меняет ставки, то есть цену клика
set_auto_keyword_bids	Пересчитывает ставки под цену нужного объёма трафика — до потолка, если он задан
set_strategy	Меняет стратегию — переписывает всю экономику кампании
add_bid_adjustments	Заводит корректировку: +N% к ставке на срезе аудитории
set_bid_adjustments	Меняет коэффициент существующей корректировки

Удаляют необратимо — эти инструменты помечены аннотацией DESTRUCTIVE, и хороший MCP-клиент спросит подтверждение перед вызовом:

manage_campaigns (delete), manage_ads (delete), manage_keywords (delete), delete_ad_groups, delete_ad_extensions, delete_sitelinks, delete_vcards, delete_bid_adjustments, delete_retargeting_lists, manage_ad_images (delete), manage_dynamic_targets (delete), set_audience_targets (delete), manage_negative_keyword_shared_sets (delete).

Сюда же — set_campaign_negative_keywords и set_ad_group_negative_keywords в режиме replace: он затирает прежний список минус-фраз целиком. Именно поэтому у них нет режима по умолчанию — mode приходится назвать явно. Так же устроен set_priority_goals: replace и remove убирают цели стратегии, а любая смена целей перезапускает её обучение.

Остальные инструменты создают и правят объекты. Пока кампания не прошла модерацию и не включена, показов по ней нет и бюджет не расходуется.

Чего API не умеет. Смарт-баннеры и динамические объявления Директ через API не создаёт с 22 мая 2026, визитки — тоже: в WSDL методы есть, боевой API отвечает ошибкой 3500. Такие объекты заводятся в интерфейсе Директа, а дальше сервер с ними работает: кампании читает и правит, визитки читает и удаляет. Единую перфоманс-кампанию сервер пока только читает.

Инструменты

В таблицах — первое предложение описания, которое сервер отдаёт модели; таблицы собираются из кода, поэтому список всегда полный.

Кампании и стратегии

Инструмент	Описание
list_campaigns	Список рекламных кампаний Яндекс.Директ с фильтрацией по статусу и типу.
get_campaign	Детальная информация о кампании по ID: бюджет (руб), статус и пояснение к нему, даты, статистика, UTM-разметка, цели и их ценность (PriorityGoals), счётчики Метрики, модель атрибуции и прочие настройки.
create_campaign	Создать новую текстово-графическую кампанию.
update_campaign	Обновить кампанию: название, бюджет (руб), UTM-разметку и/или статус (SUSPEND/RESUME/ARCHIVE/UNARCHIVE).
manage_campaigns	Запустить, остановить, архивировать, разархивировать или удалить кампании.
get_strategy	Получить текущую стратегию показов текстово-графической кампании вместе с целями (PriorityGoals), счётчиками и моделью атрибуции.
set_strategy	Изменить стратегию текстово-графической кампании: ручная, максимум кликов, средняя цена клика или конверсии, оплата за конверсию.
set_priority_goals	Задать цели стратегии кампании (PriorityGoals) и их ценность в рублях — по ним автостратегия оптимизирует ставки, в том числе «максимум конверсий» со служебным GoalId 13.
get_time_targeting	Временной таргетинг кампании: часовой пояс, часы показов по дням недели, почасовые коэффициенты и настройка праздников.
set_time_targeting	Задать расписание показов кампании: дни, часы, почасовые коэффициенты, праздники и часовой пояс.

Группы объявлений

Инструмент	Описание
list_ad_groups	Группы объявлений выбранных кампаний: названия, регионы, статусы.
create_ad_group	Создать группу объявлений в кампании с таргетингом по регионам (см. get_regions).
delete_ad_groups	Удалить группы объявлений по их ID.

Объявления

Инструмент	Описание
list_ads	Объявления: заголовки, тексты, ссылки, статусы, тип и подтип объявления, привязанные сайтлинки, визитка и изображение.
create_text_ad	Создать текстовое объявление: заголовок (≤56), второй заголовок (≤30), текст (≤81), ссылка.
update_text_ad	Обновить текстовое объявление: заголовок, текст, ссылка.
manage_ads	Действие над объявлениями: suspend/resume/archive/unarchive/moderate/delete.
moderate_ads	Отправить выбранные объявления на модерацию.

Ключевые фразы и ставки

Инструмент	Описание
list_keywords	Ключевые фразы в группах объявлений: фразы, ставки (руб), статусы.
add_keywords	Добавить ключевые фразы в группу объявлений.
update_keywords	Изменить текст ключевых фраз, подстановочные переменные {param1}/{param2} и настройки автотаргетинга.
manage_keywords	Действие над ключевыми фразами: suspend/resume/delete.
set_keyword_bids	Установить фиксированные ставки (поиск/сети, в рублях) на уровне фраз, групп или кампаний и включить или выключить автоставку автотаргетинга.
set_auto_keyword_bids	Назначить ставки по правилу вместо суммы: на поиске — под желаемый объём трафика (5–100%), в сетях — под долю аудитории, с надбавкой в процентах и потолком в рублях.
get_keyword_auction	Сколько стоит трафик по фразам: текущие ставки и торги на поиске и в сетях.

Минус-фразы

Инструмент	Описание
get_campaign_negative_keywords	Получить текущие минус-фразы кампаний по их ID.
set_campaign_negative_keywords	Минус-фразы на уровне кампании.
set_ad_group_negative_keywords	Минус-фразы на уровне группы объявлений.
list_negative_keyword_shared_sets	Получить общие наборы минус-фраз аккаунта.
manage_negative_keyword_shared_sets	Создать, изменить или удалить общие наборы минус-фраз аккаунта.
link_negative_keyword_sets	Заменить привязки общих наборов минус-фраз у кампаний и/или групп объявлений.

Ассеты объявления

Инструмент	Описание
list_sitelinks	Получить все или выбранные наборы быстрых ссылок.
set_sitelinks	Создать новый набор из 1–8 быстрых ссылок.
delete_sitelinks	Удалить наборы быстрых ссылок по ID.
list_ad_extensions	Получить уточнения (callouts) с их статусами и текстом.
add_ad_extensions	Создать уточнения (callouts), каждый текст до 25 символов.
delete_ad_extensions	Удалить уточнения по ID.
manage_ad_images	Загрузить, получить или удалить изображения объявлений (AdImages).
list_vcards	Получить виртуальные визитки по ID или найти их через объявления выбранных кампаний.
delete_vcards	Удалить визитки по ID; удаление необратимо.

Таргетинг и корректировки

Инструмент	Описание
list_audience_targets	Получить условия нацеливания на аудиторию по ID кампании, группы, ретаргетинга или интереса.
set_audience_targets	Добавить, остановить, возобновить, удалить аудиторные цели или изменить их ставки.
list_dynamic_targets	Получить условия нацеливания динамических текстовых объявлений.
manage_dynamic_targets	Создать, изменить ставки, остановить, возобновить или удалить динамические цели.
list_retargeting_lists	Получить условия ретаргетинга и подбора аудитории с правилами и областью применения.
add_retargeting_list	Создать условие ретаргетинга из целей Метрики, сегментов или интересов.
update_retargeting_lists	Изменить название, описание и правила условий ретаргетинга.
delete_retargeting_lists	Удалить условия ретаргетинга и подбора аудитории по ID; удаление необратимо.
get_bid_adjustments	Получить корректировки ставок кампании или группы: устройства, пол и возраст, аудитории, регионы, платёжеспособность, размещение.
add_bid_adjustments	Создать корректировки ставок на кампаниях или группах.
set_bid_adjustments	Изменить коэффициенты существующих корректировок по их ID.
delete_bid_adjustments	Удалить корректировки по их ID.

Отчёты

Инструмент	Описание
get_statistics	Статистика за период по кампаниям, группам, объявлениям, условиям показа или аккаунту: показы, клики, расход (руб), CTR, CPC (ReportService, TSV).
get_search_queries	Отчёт по фактическим поисковым запросам для анализа и добавления минус-фраз.

Аккаунт и справочники

Инструмент	Описание
get_account_balance	Баланс и финансовая информация аккаунта (Amount, Currency) через Live API v4.
list_businesses	Получить доступные профили организаций из Яндекс Бизнеса.
get_changes	Проверить изменения кампаний, групп и объявлений начиная с указанного времени, а также изменения справочников (mode=dictionaries) и текущее время сервера Директа.
list_feeds	Получить товарные фиды, их источники, статусы обработки и связанные кампании.
get_regions	Справочник кодов регионов (GeoRegions) для таргетинга.
list_time_zones	Справочник часовых поясов (TimeZones) для set_time_targeting и create_campaign.

Разработка

npm ci               # зависимости строго по lock-файлу
npm run dev          # сервер из исходников, без сборки
npm run build        # dist/ — то, что запускает MCP-клиент
npm test             # юнит-тесты, сеть подменена
npm run lint         # Biome: формат и линт
npm run typecheck    # типы в src, тестах и конфигах
npm run lint:dead    # knip: неиспользуемый код и зависимости
npm run lint:workflows # actionlint + zizmor: корректность и безопасность workflow
npm run lint:secrets # gitleaks по всей истории
npm run docs:tools   # таблицы инструментов в README из реестра

gitleaks, actionlint, zizmor и shellcheck — не npm-пакеты; без них хуки pre-commit не пропустят коммит. На Windows:

winget install -e --id Gitleaks.Gitleaks
winget install -e --id rhysd.actionlint
winget install -e --id zizmor.zizmor
winget install -e --id koalaman.shellcheck

Без режима разработчика winget не создаёт ссылки в %LOCALAPPDATA%\Microsoft\WinGet\Links, и каталоги пакетов из %LOCALAPPDATA%\Microsoft\WinGet\Packages придётся добавить в PATH.

Таблицы инструментов выше руками не правятся: после смены описания инструмента — npm run docs:tools, иначе юнит-тест покажет расхождение.

Сетевые тесты (npm run test:int) идут по боевому аккаунту и пишут только в кампанию-полигон, оставленную черновиком: её ID задаётся переменной YANDEX_DIRECT_POLYGON_CAMPAIGN_ID. Без переменной они пропускаются.

Код разложен по слоям app → tools → shared; инструмент — это каталог src/tools/<домен>/ с schema.ts, handler.ts и tool.ts. Подробности — в docs/architecture.md.

Происхождение и благодарности

Проект начат на коде theYahia/yandex-direct-mcp под лицензией MIT. Расширение с 20 до 48 инструментов и перевод ID на строки — работа Maxim (DrSeedon), PR #7; в npm эта версия не публиковалась. Дальше проект развивается самостоятельно и апстрим не отслеживает.

История изменений с отделения от апстрима — в CHANGELOG.md.

Лицензия

Copyright © 2026 Pavelsiba. GNU AGPL-3.0-only.

Пользоваться сервером, изменять его и разворачивать у себя можно свободно, в том числе в работе с клиентами. Кто предоставляет изменённый сервер другим людям по сети, обязан дать им исходный код своей версии (раздел 13 лицензии).

Версии до 1.7.0 включительно вышли под MIT и под ней остаются.

Pull request'ы принимаются вместе с передачей прав на вклад автору проекта (CLA) — без этого проект не сможет распоряжаться своим кодом. Перед большой правкой лучше завести issue.