Yandex Direct MCP Server

MCP-сервер для Яндекс Директа, Яндекс Метрики и Wordstat — 120 инструментов для работы с контекстной рекламой из AI-ассистентов (Claude, Claude Code, Cursor, Windsurf и других MCP-клиентов).

Что эта сборка добавляет к исходному проекту

• Комбинаторные объявления (ResponsiveAd — несколько заголовков и текстов, которые система сама комбинирует): создание, изменение, удаление. В исходном проекте их нельзя было загрузить вообще — собирались только одиночные TextAd.
• Direct API v501 для них. Рабочий JSON-эндпоинт вычислен опытным путём: в документации указан SOAP-адрес, который на JSON отвечает XML-ошибкой. Без этого комбинаторные объявления не создаются.
• IAM-токены из ключа сервисного аккаунта. Яндекс запретил обмен Passport-токенов, выпущенных после 1 июня 2026 года, — на любом свежем токене Wordstat переставал работать совсем.
• Ретраи Wordstat на HTTP 429 и num_phrases по умолчанию 2000 вместо 30: квота тратится на запрос, а не на фразу, поэтому старое значение сжигало единицу квоты ради 30 фраз.
• Имена инструментов yandex_direct_* / yandex_metrika_* / yandex_wordstat_*. Прежние yd_* не находились семантическим поиском инструментов в MCP-клиентах: в названии yd_campaigns_get с описанием «Get list of campaigns» нет ни одного слова «yandex» или «direct».
• Фильтры выдачи инструментов: YD_READONLY убирает изменяющие инструменты из tools/list, YD_LEAN оставляет только основной набор для клиентов с лимитом на число инструментов.

Что именно изменено, в каком коммите и почему — в FORK.md.

Форк Yurich-ru/yandex-ads-mcp (MIT) от коммита 7ad0551; ветка master — нетронутый апстрим, вся работа в fork-main.

Ключевые слова: Yandex Direct MCP server, Яндекс Директ MCP, Яндекс Метрика, Wordstat API, Model Context Protocol, комбинаторные объявления, ResponsiveAd, Direct API v501, контекстная реклама, Claude, Claude Code, Cursor, AI-агент, автоматизация рекламы.

---

Документация исходного проекта

MCP-сервер для управления рекламой в Яндекс Директе, аналитикой в Яндекс Метрике и подбором ключевых слов через Wordstat API.

120 инструментов для полного цикла управления рекламой из AI-ассистентов (Claude Code, Cursor, Windsurf и др.).

Возможности

Сервис	Инструментов	Что умеет
Яндекс Директ	77	Кампании, группы, объявления, ключевики, ставки, корректировки, минус-фразы, быстрые ссылки, уточнения, визитки, фиды, изображения, видео, ретаргетинг, площадки, стратегии, отчёты
Яндекс Метрика	43	Счётчики, цели, сегменты, фильтры, доступы, отчёты, аннотации, офлайн-конверсии, расходы, звонки
Wordstat	5	Частотность запросов, динамика, региональное распределение, дерево регионов, квота API

Быстрый старт

1. Установка

git clone https://github.com/YOUR_USER/yandex-ads-mcp.git
cd yandex-ads-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Настройка токенов

Скопируйте .env.example в .env и заполните:

cp .env.example .env

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

Добавьте в ~/.claude.json (секция mcpServers):

{
  "yandex-ads": {
    "type": "stdio",
    "command": "/path/to/yandex-ads-mcp/venv/bin/python",
    "args": ["/path/to/yandex-ads-mcp/server.py"],
    "env": {
      "YD_OAUTH_TOKEN": "YOUR_TOKEN",
      "YC_FOLDER_ID": "YOUR_FOLDER_ID"
    }
  }
}

Перезапустите Claude Code.

---

Получение токенов

OAuth-токен для Директа и Метрики

Один токен используется для Директа и Метрики.

Шаг 1: Создать OAuth-приложение

1. Зайдите на https://oauth.yandex.ru/
2. Нажмите "Зарегистрировать новое приложение"
3. Redirect URI: выберите "Подставить URL для разработки" (https://oauth.yandex.ru/verification_code)
4. В разделе "Доступ к данным" отметьте:
   • Яндекс Директ → direct:api (управление рекламой)
   • Яндекс Метрика → metrika:read (чтение данных) и metrika:write (управление целями)
   • Яндекс Cloud → cloud:auth (для Wordstat API)
5. Сохраните — запомните Client ID

Шаг 2: Получить токен

Откройте в браузере (подставьте свой Client ID):

https://oauth.yandex.ru/authorize?response_type=token&client_id=YOUR_CLIENT_ID

Авторизуйтесь → токен будет в адресной строке после access_token=.

Шаг 3: Подать заявку на API Директа

1. Зайдите в Яндекс Директ → Настройки → API
2. Нажмите "Получить доступ к API"
3. Укажите Client ID приложения
4. Опишите назначение: "Управление рекламными кампаниями через собственное приложение"
5. Ожидайте одобрения (обычно несколько часов)

Folder ID для Wordstat API

Wordstat API работает через Yandex Cloud. Нужен платёжный аккаунт (карта не списывается, есть бесплатная квота).

Шаг 1: Зарегистрироваться в Yandex Cloud

1. Зайдите на https://console.yandex.cloud/
2. Создайте платёжный аккаунт (привяжите карту)

Шаг 2: Получить Folder ID

1. В консоли Cloud → выберите каталог (обычно default)
2. Скопируйте ID каталога (формат: b1gxxxxxxxxxx)

Шаг 3: Назначить роль

1. Перейдите в каталог → "Права доступа"
2. Назначьте своему пользователю роль search-api.executor

Шаг 4: Убедиться что OAuth-токен имеет scope cloud:auth

Если при создании приложения не добавляли Yandex Cloud — отредактируйте приложение на https://oauth.yandex.ru/ → добавьте cloud:auth → получите новый токен.

---

Переменные окружения

Переменная	Обязательна	Описание
YD_OAUTH_TOKEN	Да	OAuth-токен с правами direct:api, metrika:read, metrika:write, cloud:auth
YC_FOLDER_ID	Для Wordstat	ID каталога Yandex Cloud
YD_SANDBOX	Нет	true для тестового режима Директа (sandbox)
YD_LOGIN	Нет	Логин клиента по умолчанию (для агентских аккаунтов)
YD_READONLY	Нет	true — блокирует все изменяющие инструменты (add/update/delete/action/set/...); отчёты и чтение работают
YD_CONFIRM	Нет	true — изменяющие вызовы требуют confirm=true, иначе возвращают только превью
YD_ALLOWED_LOGINS	Нет	Белый список агентских Client-Login через запятую (для инструментов Директа). Пусто = без ограничений
YD_LOG_LEVEL	Нет	DEBUG/INFO/WARNING/ERROR (по умолчанию INFO)
YD_LOG_FILE	Нет	Путь к лог-файлу. Пусто = только stderr, файл не пишется
YD_LOG_BODIES	Нет	true — писать тела запросов/ответов в лог (подробно; могут содержать данные кампаний)

Безопасность и доступ (доработки форка)

Этот форк (upstream: Yurich-ru/yandex-ads-mcp) добавляет защитную обвязку для работы с боевыми кабинетами:

• Read-only режим (YD_READONLY=true) — агент видит и анализирует данные, но физически не может создать/изменить/удалить кампании, ставки, счётчики или цели.
• Confirm-режим (YD_CONFIRM=true) — любой изменяющий вызов сначала возвращает превью операции; чтобы выполнить, нужно повторить вызов с confirm=true.
• Мульти-аккаунт — у инструментов Директа есть необязательный аргумент client_login для выбора клиентского кабинета на уровне вызова; YD_ALLOWED_LOGINS ограничивает, к каким логинам агент вообще имеет доступ.
• Partial-success — изменяющие ответы Директа разбираются на per-item Errors/Warnings и сводятся в поле _partial_success, чтобы наполовину провалившаяся массовая операция не выглядела как успех.
• Логи по умолчанию не пишутся на диск — раньше сервер всегда писал yandex-ads.log с полными телами запросов. Теперь файл создаётся только при заданном YD_LOG_FILE, а тела — только при YD_LOG_BODIES=true.

Офлайн-проверка обвязки (без сети и токенов): python3 test_safety.py.

---

Полный список инструментов

Яндекс Директ — Кампании

Инструмент	Описание
yd_campaigns_get	Список кампаний с фильтрами
yd_campaigns_add	Создать кампанию (все стратегии: PAY_FOR_CONVERSION, WB_MAXIMUM_CLICKS и др.)
yd_campaigns_update	Обновить настройки кампании
yd_campaigns_action	Приостановить / возобновить / архивировать

Яндекс Директ — Группы объявлений

Инструмент	Описание
yd_adgroups_add	Создать группы объявлений
yd_adgroups_get	Получить группы
yd_adgroups_update	Обновить группу (имя, регионы, минус-фразы)

Яндекс Директ — Объявления

Инструмент	Описание
yd_ads_add	Создать текстовые объявления (с sitelinks и картинками)
yd_ads_add_dynamic	Создать динамические объявления
yd_ads_add_image	Создать графические объявления
yd_ads_add_shopping	Создать товарные объявления (ЕПК, v501)
yd_ads_get	Получить объявления
yd_ads_update	Обновить объявления
yd_ads_action	Модерация / пауза / архив

Яндекс Директ — Ключевые фразы

Инструмент	Описание
yd_keywords_add	Добавить ключевые фразы
yd_keywords_get	Получить фразы
yd_keywords_has_volume	Проверить наличие показов по фразам
yd_keywords_research	Дедупликация фраз

Яндекс Директ — Ставки

Инструмент	Описание
yd_bids_set	Установить ставки
yd_keyword_bids_get	Получить ставки и прогнозы
yd_keyword_bids_set	Установить ставки на ключевики
yd_keyword_bids_set_auto	Автоматические ставки
yd_bid_modifiers_add	Корректировки (устройства, демография, регионы)
yd_bid_modifiers_get	Получить корректировки
yd_bid_modifiers_set	Обновить корректировки
yd_bid_modifiers_delete	Удалить корректировки
yd_bid_modifiers_toggle	Включить/выключить корректировки

Яндекс Директ — Минус-фразы

Инструмент	Описание
yd_negative_keywords_sets_add	Создать набор минус-фраз
yd_negative_keywords_sets_get	Получить наборы
yd_negative_keywords_sets_update	Обновить набор
yd_negative_keywords_sets_delete	Удалить набор

Яндекс Директ — Расширения

Инструмент	Описание
yd_sitelinks_add	Создать быстрые ссылки
yd_sitelinks_get	Получить быстрые ссылки
yd_sitelinks_delete	Удалить быстрые ссылки
yd_ad_extensions_add	Создать уточнения (callouts)
yd_ad_extensions_get	Получить уточнения
yd_ad_extensions_delete	Удалить уточнения
yd_callouts_link	Привязать уточнения к объявлению (v501)

Яндекс Директ — Визитки

Инструмент	Описание
yd_vcards_add	Создать визитку
yd_vcards_get	Получить визитки
yd_vcards_delete	Удалить визитки

Яндекс Директ — Изображения и видео

Инструмент	Описание
yd_ad_images_add	Загрузить изображения (base64)
yd_ad_images_get	Получить изображения
yd_ad_images_delete	Удалить изображения
yd_videos_upload	Загрузить видео (из файла)
yd_videos_get	Получить видео
yd_creatives_add	Создать видеокреатив
yd_creatives_get	Получить креативы

Яндекс Директ — Фиды

Инструмент	Описание
yd_feeds_add	Добавить фид
yd_feeds_get	Получить фиды
yd_feeds_update	Обновить фид
yd_feeds_delete	Удалить фиды

Яндекс Директ — Ретаргетинг

Инструмент	Описание
yd_retargeting_lists_add	Создать список ретаргетинга
yd_retargeting_lists_get	Получить списки
yd_retargeting_lists_delete	Удалить списки
yd_audience_targets_add	Добавить таргетинг на аудиторию
yd_audience_targets_get	Получить таргетинги
yd_audience_targets_delete	Удалить таргетинги
yd_smart_targets_add	Создать смарт-таргет
yd_smart_targets_get	Получить смарт-таргеты
yd_smart_targets_action	Пауза / возобновление / удаление

Яндекс Директ — Отчёты и справочники

Инструмент	Описание
yd_report	Статистика (TSV, любой тип отчёта)
yd_dictionaries	Справочники (регионы, валюты и др.)
yd_regions_get	Справочник регионов (отдельный tool)
yd_interests_get	Справочник интересов
yd_changes_check	Проверка изменений
yd_clients_get	Информация об аккаунте
yd_businesses_get	Организации из Яндекс Бизнеса

Яндекс Директ — Управление площадками и стратегией

Инструмент	Описание
yd_excluded_sites_get	Получить список заблокированных площадок
yd_excluded_sites_update	Обновить список заблокированных площадок (SSP, сайты)
yd_blocked_ips_update	Заблокировать IP-адреса (до 25 шт.)
yd_campaign_strategy_update	Сменить стратегию, CPA, недельный бюджет, цель конверсии

Яндекс Метрика — Счётчики

Инструмент	Описание
yd_metrika_counters_get	Список счётчиков
yd_metrika_counter_get	Детали счётчика
yd_metrika_counter_create	Создать счётчик
yd_metrika_counter_update	Обновить счётчик
yd_metrika_counter_delete	Удалить счётчик

Яндекс Метрика — Цели

Инструмент	Описание
yd_metrika_goals_get	Список целей
yd_metrika_goal_create	Создать цель
yd_metrika_goal_update	Обновить цель
yd_metrika_goal_delete	Удалить цель

Яндекс Метрика — Отчёты

Инструмент	Описание
yd_metrika_report	Табличный отчёт (визиты, пользователи, конверсии)
yd_metrika_report_by_time	Отчёт по времени (день/неделя/месяц)
yd_metrika_report_comparison	Сравнение двух периодов
yd_metrika_report_drilldown	Иерархический drill-down

Яндекс Метрика — Сегменты, фильтры, доступы

Инструмент	Описание
yd_metrika_segments_get/create/update/delete	Управление сегментами
yd_metrika_filters_get/create/update/delete	Управление фильтрами
yd_metrika_grants_get/add/update/delete	Управление доступами
yd_metrika_delegates_get/add/delete	Управление делегатами

Яндекс Метрика — Метки и аннотации

Инструмент	Описание
yd_metrika_labels_get/create/update/delete	Управление метками
yd_metrika_label_link/unlink	Привязка счётчиков к меткам
yd_metrika_annotations_get/create/update/delete	Аннотации на графиках

Яндекс Метрика — Офлайн-данные

Инструмент	Описание
yd_metrika_upload_conversions	Загрузить офлайн-конверсии
yd_metrika_conversions_status	Статус загрузки конверсий
yd_metrika_upload_calls	Загрузить звонки
yd_metrika_upload_expenses	Загрузить расходы
yd_metrika_upload_user_params	Загрузить параметры пользователей

Wordstat API

Инструмент	Описание
yd_wordstat_top_requests	Популярные запросы (частотность)
yd_wordstat_dynamics	Динамика частотности
yd_wordstat_regions	Региональное распределение
yd_wordstat_regions_tree	Дерево регионов
yd_wordstat_user_info	Квота API

---

Лицензия

MIT