Yandex Ads

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

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

Возможности

Сервис	Инструментов	Что умеет
Яндекс Директ	84	Кампании, группы, объявления, ключевики, ставки, корректировки, минус-фразы, быстрые ссылки, уточнения, визитки, фиды, изображения, видео, ретаргетинг, площадки, стратегии, отчёты
Яндекс Метрика	43	Счётчики, цели, сегменты, фильтры, доступы, отчёты, аннотации, офлайн-конверсии, расходы, звонки
Яндекс Аудитории	23	Сегменты из CRM-данных (email/телефоны/ID устройств), lookalike, гео-сегменты, сегменты из Метрики/AppMetrica, пиксели, права доступа, делегаты
Wordstat	5	Частотность запросов, динамика, региональное распределение, дерево регионов, квота API

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

1. Установка

git clone https://github.com/Yurich-ru/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-токен для Директа, Метрики и Аудиторий

Один токен используется для Директа, Метрики и Аудиторий — если все сервисы живут в одном Яндекс-аккаунте.

Сервисы в разных аккаунтах? OAuth-токен привязан к аккаунту, поэтому одним токеном два аккаунта не покрыть. Выпустите токен в каждом аккаунте и разложите их по переменным: YD_OAUTH_TOKEN — аккаунт с кабинетом Директа, YD_METRIKA_TOKEN / YD_AUDIENCE_TOKEN — аккаунт с Метрикой и Аудиториями.

Шаг 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

Если приложение уже создано без прав Аудиторий — отредактируйте его на https://oauth.yandex.ru/, добавьте доступ к Яндекс Аудиториям и получите новый токен (шаг 2). Без этого инструменты yd_audience_* возвращают 403 access_denied.

Шаг 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 и доступом к Яндекс Аудиториям
YD_METRIKA_TOKEN	Нет	Отдельный токен для Метрики (мульти-аккаунт). Пусто = YD_OAUTH_TOKEN
YD_AUDIENCE_TOKEN	Нет	Отдельный токен для Аудиторий (мульти-аккаунт). Пусто = YD_OAUTH_TOKEN
YC_FOLDER_ID	Для Wordstat	ID каталога Yandex Cloud
YC_API_KEY	Для Wordstat	API-ключ сервисного аккаунта (роль search-api.executor). Обязателен для OAuth-токенов, выпущенных после 01.06.2026 — Яндекс Облако больше не меняет их на IAM. Пусто = старый обмен OAuth→IAM
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 — писать тела запросов/ответов в лог (подробно; могут содержать данные кампаний)

Безопасность и работа с боевыми кабинетами

Все защитные механизмы — opt-in через env-переменные (см. таблицу выше). С дефолтными настройками поведение не меняется по сравнению с базовым MCP-сервером.

• Read-only режим (YD_READONLY=true) — агент видит и анализирует данные, но физически не может создать/изменить/удалить кампании, ставки, счётчики или цели. Блокировка происходит до сетевого вызова.
• Confirm-режим (YD_CONFIRM=true) — любой изменяющий вызов сначала возвращает превью операции; чтобы выполнить, нужно повторить вызов с confirm=true. В схемах мутирующих инструментов автоматически появляется параметр confirm.
• Мульти-аккаунт — у инструментов Директа есть необязательный аргумент client_login для выбора клиентского кабинета на уровне вызова (передаётся через contextvars, безопасно для конкурентных вызовов); YD_ALLOWED_LOGINS ограничивает, к каким логинам агент вообще имеет доступ.
• Partial-success — изменяющие ответы Директа разбираются на per-item Errors/Warnings и сводятся в поле _partial_success, чтобы наполовину провалившаяся массовая операция не выглядела как успех.
• Retry / backoff — экспоненциальный backoff на 429/5xx для вызовов Direct API, с уважением заголовка Retry-After. Балансы очков Direct API из заголовка Units логируются (WARN если осталось менее 5%).
• IAM-токен — TTL берётся из ответа Yandex Cloud IAM (expiresAt), а не из захардкоженных 11 часов.
• Логи по умолчанию не пишутся на диск — файл yandex-ads.log создаётся только при заданном YD_LOG_FILE. Тела запросов/ответов пишутся только при YD_LOG_BODIES=true (могут содержать данные кампаний; токены никогда не логируются).

Рекомендуемая конфигурация для агента, работающего с боевыми кабинетами:

YD_READONLY=true       # либо
YD_CONFIRM=true        # для интерактивного подтверждения мутаций
YD_ALLOWED_LOGINS=client1,client2   # для агентского аккаунта

Офлайн-проверка защитной обвязки (без сети и токенов): 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_keywords_suspend	Приостановить ключевые фразы по ID
yd_keywords_resume	Возобновить ключевые фразы по ID
yd_keywords_delete	Удалить ключевые фразы по ID

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

Инструмент	Описание
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_update	Обновить список (имя, описание, правила)
yd_retargeting_lists_delete	Удалить списки
yd_audience_targets_add	Добавить таргетинг на аудиторию
yd_audience_targets_get	Получить таргетинги
yd_audience_targets_suspend	Приостановить таргетинги по ID
yd_audience_targets_resume	Возобновить таргетинги по ID
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_changes_timestamp_get	Текущий серверный timestamp (точка отсчёта для 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	Загрузить параметры пользователей

Яндекс Аудитории — Сегменты

Инструмент	Описание
yd_audience_segments_get	Список сегментов (опционально по пикселю)
yd_audience_segment_upload	Загрузить данные (email/телефоны/ID устройств/ClientID/CRM) → черновик сегмента
yd_audience_segment_confirm	Сохранить загруженный сегмент (имя, тип данных, hashed)
yd_audience_segment_update	Переименовать сегмент
yd_audience_segment_delete	Удалить сегмент
yd_audience_segment_reprocess	Принудительный пересчёт сегмента
yd_audience_segment_create_lookalike	Lookalike-сегмент (похожие пользователи)
yd_audience_segment_create_metrika	Сегмент из Метрики (счётчик / цель / сегмент)
yd_audience_segment_create_appmetrica	Сегмент из AppMetrica
yd_audience_segment_create_geo	Гео-сегмент (окружности или полигоны)
yd_audience_segment_create_pixel	Сегмент из пикселя

Яндекс Аудитории — Доступы и пиксели

Инструмент	Описание
yd_audience_grants_get/grant_add/grant_delete	Права доступа к сегменту (для использования в чужих кабинетах Директа)
yd_audience_pixels_get	Список пикселей
yd_audience_pixel_create/update/delete/undelete	Управление пикселями
yd_audience_accounts_get	Аккаунты, где вы представитель
yd_audience_delegates_get/delegate_add/delegate_delete	Представители вашего аккаунта

Wordstat API

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

---

Лицензия

MIT