Yandex Ads MCP Server

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

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

Возможности

| Сервис | Инструментов | Что умеет | |--------|-------------|-----------| | Яндекс Директ | 86 | Кампании, группы, объявления, ключевики, автотаргетинг, ставки, корректировки, минус-фразы, быстрые ссылки, уточнения, визитки, фиды, изображения, видео, ретаргетинг, площадки, стратегии, отчёты | | Яндекс Метрика | 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_DIRECT_TOKENS) | | YD_DIRECT_TOKENS | Нет | Дополнительные кабинеты Директа: логин:токен,логин2:токен2. Кабинет выбирается аргументом client_login; для таких логинов используется их токен и не шлётся Client-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 ограничивает, к каким логинам агент вообще имеет доступ. Два режима:
  • агентский — логин субклиента передаётся в заголовке Client-Login с основным токеном;
  • несколько самостоятельных кабинетов (не агентство) — у каждого кабинета свой токен в YD_DIRECT_TOKENS=логин:токен,...; client_login с таким логином переключает токен. yd_direct_accounts_get показывает все доступные кабинеты с живой проверкой.
• 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_ads_update набор заголовков и текстов в responsive_ad. Поля titles (1–7) и texts (1–3) обязательны; также нужен href или business_id. Быстрые ссылки прикрепляются через responsive_ad.sitelink_set_id. Не смешивайте responsive_ad с полями старого текстового формата в одном объявлении. Комбинаторные объявления обновляются через обязательную для этого типа версию Direct API v501.

{
  "ads": [{
    "id": 123456,
    "responsive_ad": {
      "titles": ["Основной заголовок", "Дополнительный заголовок"],
      "texts": ["Текст объявления"],
      "href": "https://example.com",
      "sitelink_set_id": 123456
    }
  }]
}

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

| Инструмент | Описание | |-----------|----------| | yd_keywords_add | Добавить ключевые фразы или автотаргетинг с настройками категорий и брендов | | yd_keywords_update | Изменить категории запросов и упоминания брендов для автотаргетинга | | yd_keywords_get | Получить фразы и полные настройки автотаргетинга | | yd_keywords_has_volume | Проверить наличие показов по фразам | | yd_keywords_research | Дедупликация фраз | | yd_keywords_suspend | Приостановить ключевые фразы по ID | | yd_keywords_resume | Возобновить ключевые фразы по ID | | yd_keywords_delete | Удалить ключевые фразы по ID |

Автотаргетинг создаётся как специальный критерий ---autotargeting, а его настройки передаются в autotargeting_settings. Для изменения существующего критерия сначала получите его ID через yd_keywords_get, затем вызовите yd_keywords_update:

{
  "keywords": [{
    "id": 123456789,
    "autotargeting_settings": {
      "categories": {
        "exact": "YES",
        "narrow": "YES",
        "alternative": "NO",
        "accessory": "NO",
        "broader": "NO"
      },
      "brand_options": {
        "with_advertiser_brand": "YES",
        "with_competitors_brand": "NO",
        "without_brands": "YES"
      }
    }
  }]
}

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

| Инструмент | Описание | |-----------|----------| | yd_bids_set | Установить ставки | | `yd_keyword_bids_g