# 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](FORK.md)**.

Форк [Yurich-ru/yandex-ads-mcp](https://github.com/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. Установка

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

```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-токен для Директа и Метрики

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

#### Шаг 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](https://github.com/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