Yandex Ads MCP Server

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

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

Возможности

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

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 → получите новый токен.

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

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

Все защитные механизмы — 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Wordstat API

Лицензия

MIT