brainstate

discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens

Yurich-ru/yandex-ads-mcp · source

Snapshot 0 · 2026-11-04T12:47:28Z · Python ·

Content fingerprint50001e7a459150d16b293350ac1667d9c1852f3bf06f6ec24d76944d81e84589

GitHub description at capture

MCP server for Yandex Direct, Metrika, Audience & Wordstat APIs — 152 tools for campaign management, audience segments, analytics, and keyword research

README at capture

# 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. Установка

```bash
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` и заполните:

```bash
cp .env.example .env
```

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

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

```json
{
  "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` (могут содержать данные кампаний; токены никогда не логируются).

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

```bash
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.

```json
{
  "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`:

```json
{
  "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_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_direct_accounts_get` | Все доступные кабинеты Директа (основной токен + `YD_DIRECT_TOKENS`) с живой проверкой |
| `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