# Яндекс Директ MCP

[![npm](https://img.shields.io/npm/v/mcp-yandex-direct)](https://www.npmjs.com/package/mcp-yandex-direct)
[![CI](https://github.com/askads/mcp-yandex-direct/actions/workflows/ci.yml/badge.svg)](https://github.com/askads/mcp-yandex-direct/actions/workflows/ci.yml)
[![Glama](https://glama.ai/mcp/servers/askads/mcp-yandex-direct/badges/score.svg)](https://glama.ai/mcp/servers/askads/mcp-yandex-direct)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

**Яндекс Директ MCP** подключает AI-приложение к рекламному кабинету Яндекс Директа. Спросите на естественном языке, куда уходит рекламный бюджет, сопоставьте кампании, объявления и ключевые фразы, а затем подготовьте или внесите нужные изменения без переходов между разделами кабинета. Подключение начинается прямо в диалоге: не нужно заранее создавать токен или редактировать конфигурацию.

- **44 инструмента.** Кампании, группы, объявления, ключевые фразы, ставки, корректировки, расширения, статистика, баланс, справочники и подключение аккаунта прямо в диалоге.
- **Два способа подключения.** Удалённый сервер по URL не требует вручную получать токен и только читает данные; локальный через `npx` даёт полный доступ к кабинету.
- **Подключение в чате.** Яндекс откроет страницу входа; после кода из чата можно сразу работать с рекламой, а доступ продлевается автоматически.
- **Деньги в понятном виде.** В удобных инструментах бюджеты, ставки и баланс показываются в валюте аккаунта, а не в микроединицах API.
- **Реальная реклама.** Локальные изменения применяются в боевом кабинете и могут повлиять на расход. Для работы в тестовой среде есть песочница Яндекс Директа.

Попробуйте первым сообщением:

> Покажи кампании моего аккаунта и расход за прошлую неделю по группам объявлений.

[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация)

---

## Увидеть работу за минуту

> **Вы:** Подключи Яндекс Директ.
>
> **Ассистент:** Даёт ссылку на вход в Яндекс. Откройте её под аккаунтом с доступом к нужному рекламному кабинету, подтвердите доступ и пришлите показанный код.
>
> **Вы:** Отправляет код со страницы Яндекса.
>
> **Ассистент:** Подключает Директ и показывает кабинет. Перезапускать приложение не нужно.
>
> **Вы:** Покажи кампании моего аккаунта и расход за прошлую неделю по группам объявлений.
>
> **Ассистент:** Находит кампании, строит отчёт по группам объявлений и показывает расход в валюте аккаунта.

## Содержание

- [Быстрый старт](#быстрый-старт)
- [Что можно поручить](#что-можно-поручить)
- [Как это работает](#как-это-работает)
- [Что может изменить данные](#что-может-изменить-данные)
- [Подключение и настройка](#подключение-и-настройка)
- [Данные и телеметрия](#данные-и-телеметрия)
- [Ограничения](#ограничения)
- [Техническая документация](#техническая-документация)
- [Поддержка](#поддержка)

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

1. Выберите способ подключения и добавьте сервер в AI-приложение по инструкции ниже.
2. Откройте новый диалог и спросите: **«Покажи кампании моего аккаунта и расход за прошлую неделю по группам объявлений»**.

### Анализ без самостоятельного получения токена — по URL

Удалённый сервер `https://mcp.askads.ru/mcp` подключается через приложение, которое поддерживает MCP по URL. Войдите в Яндекс в браузере и подтвердите доступ: токен не нужно передавать в конфиг. Этот вариант предназначен только для чтения — статистики, аудита и просмотра объектов; он не меняет настройки рекламы.

В Claude Code можно добавить его командой:

```bash
claude mcp add --transport http yandex-direct https://mcp.askads.ru/mcp
```

После подключения откройте `/mcp` и пройдите авторизацию. В остальных поддерживающих HTTP MCP приложениях добавьте тот же URL через интерфейс приложения.

### Полный доступ — локально через `npx`

Для создания и изменения объектов нужен Node.js 20+. `npx` скачает сервер при первом запуске — отдельно устанавливать пакет не нужно. Получать токен заранее не требуется — подключение начинается прямо в диалоге:

1. Добавьте сервер в AI-приложение — ниже открыт пример для Codex, остальные приложения собраны в сворачиваемые инструкции.
2. Напишите: «Подключи Яндекс Директ» — ассистент проведёт через вход в Яндекс и покажет кабинет.

Для CI и агентских установок — готовый токен и `YANDEX_DIRECT_LOGIN`, см. [Подключение и настройка](#подключение-и-настройка).

<details open>
<summary><strong>Codex</strong></summary>

<br>

**Через интерфейс приложения:**

1. Откройте **Settings → Plugins → MCP servers**.
2. Нажмите **Add server**.
3. Добавьте команду запуска `npx -y mcp-yandex-direct@latest`.

**Через командную строку:**

```bash
codex mcp add yandex-direct -- npx -y mcp-yandex-direct@latest
```

Проверьте подключение:

```bash
codex mcp list
```

[Официальная инструкция Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)

</details>

<details>
<summary><strong>Claude Code</strong></summary>

```bash
claude mcp add --transport stdio --scope user yandex-direct -- npx -y mcp-yandex-direct@latest
```

Проверить подключение: `claude mcp list`.

</details>

<details>
<summary><strong>Claude Desktop</strong></summary>

Откройте **Settings → Developer → Edit Config** и добавьте в `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct@latest"]
    }
  }
}
```

Если раздела Developer нет, откройте файл вручную: macOS — `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows — `%APPDATA%\Claude\claude_desktop_config.json`. Перезапустите Claude Desktop.

</details>

<details>
<summary><strong>Cursor</strong></summary>

Откройте `~/.cursor/mcp.json`, чтобы подключить сервер во всех проектах, или `.cursor/mcp.json` в конкретном проекте. Добавьте:

```json
{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct@latest"]
    }
  }
}
```

</details>

<details>
<summary><strong>VS Code</strong></summary>

В палитре команд выполните **MCP: Open User Configuration**. В открывшемся `mcp.json` добавьте сервер:

```json
{
  "servers": {
    "yandex-direct": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct@latest"]
    }
  }
}
```

После сохранения выполните **MCP: List Servers** и запустите сервер из списка.

</details>

## Что можно поручить

### Проверить, как расходуется бюджет

- «Какие кампании за прошлую неделю потратили больше всего?»
- «Какие объявления получают показы и клики, но не дают конверсий?»
- «Сравни расход, CTR и среднюю цену клика по кампаниям за месяц».
- «Покажи баланс счёта и остаток дневной квоты API».

### Найти точки для улучшения

- «Какие ключевые фразы тратят бюджет, но не приносят кликов?»
- «Какие группы и объявления сейчас остановлены или не проходят модерацию?»
- «Проверь, какие корректировки ставок действуют для мобильных устройств».
- «Какие быстрые ссылки и уточнения есть у этой кампании?»

### Подготовить изменения

- «Предложи новые ставки для фраз с высоким CTR и покажи изменения до применения».
- «Проверь, есть ли в кампании минус-слова для этой темы, и подготовь список».
- «Собери параметры новой текстовой кампании для Москвы: бюджет, группы, ключевые фразы и объявления».

### Выполнить явное действие

- «Добавь эти ключевые фразы в группу 123 и установи ставку 45 ₽».
- «Приостанови объявление 456».
- «Отправь страницу с изображением в библиотеку объявлений».

## Как это работает

Реклама обычно строится из трёх уровней: **кампания → группа объявлений → объявление**. В группе находятся ключевые фразы, настройки показа и корректировки ставок. У объявлений могут быть быстрые ссылки, уточнения, визитки и изображения.

Сервер помогает смотреть на эти объекты вместе: связать расход кампании со статистикой групп, ключевыми фразами и объявлениями. Он умеет создавать новые кампании и объявления только текстового типа. Кампании других типов можно читать, переименовывать, менять им бюджет, останавливать, архивировать и удалять по идентификатору.

Статистика формируется не мгновенно: `get_statistics` запускает отчёт в сервисе Reports и ждёт его готовности. Большие списки `autoPaginate` проходит по страницам выдачи автоматически.

## Что может изменить данные

Удалённый сервер по URL только читает данные. Локальный сервер через `npx` может изменить живой рекламный кабинет:

| Действие | Что происходит | На что обратить внимание |
| --- | --- | --- |
| Читать статистику и объекты | Сервер получает кампании, объявления, ключевые фразы, баланс и отчёты. | Эти вызовы не меняют данные и не двигают деньги. |
| Создавать | Можно создать текстовую кампанию, группу, текстовое объявление, ключевые фразы, расширения или загрузить изображение. | Новые объекты попадут в боевой кабинет, если не включена песочница. |
| Обновлять | Можно менять бюджет, ставки, названия, минус-слова, настройки групп и корректировки ставок. | Изменение ставок и бюджетов может повлиять на расход. |
| Менять статус или удалять | Можно приостановить, возобновить, архивировать или удалить некоторые объекты. | Удаление и отдельные действия необратимы. |
| Прямой запрос API | `raw_request` открывает любой метод API, для которого нет отдельного инструмента. | Любой метод, кроме чтения, требует `confirmWrite=true`; данные там передаются в микроединицах. |

Инструменты передают AI-приложению метки чтения, записи и потенциально необратимого действия. Приложение может показать подтверждение, но его поведение зависит от клиента. Прямой запрос API дополнительно не выполнит запись без `confirmWrite=true`; для изменения рекламы нужна явная просьба.

## Подключение и настройка

Для обычного использования токен заранее не нужен:

1. В чате попросите подключить Яндекс Директ.
2. Откройте ссылку на Яндекс OAuth **под аккаунтом с доступом к нужному рекламному кабинету**.
3. Подтвердите доступ и пришлите в чат показанный код. Всё, можно работать с рекламой: перезапускать клиент не нужно, конфигурацию править тоже.

Дальше подключение живёт само: доступ продлевается автоматически и не отваливается через год. Проверить состояние — попросите «покажи статус подключения», отключить — «отключи Директ». Выданный доступ отзывается в [Яндекс ID](https://id.yandex.ru/security).

Для CI и автоматических установок, где диалога нет, доступна настройка через переменные окружения:

| Переменная | Назначение |
|---|---|
| `YANDEX_DIRECT_TOKEN` | Готовый OAuth-токен; имеет приоритет над входом из чата. |
| `YANDEX_DIRECT_LOGIN` | Логин клиента при работе через агентский аккаунт; иначе API покажет аккаунт агентства. |
| `YANDEX_DIRECT_SANDBOX` | `true` — работа в тестовой среде (песочнице) Яндекс Директа. |
| `YANDEX_DIRECT_OAUTH_CLIENT_ID` | Client ID собственного OAuth-приложения вместо встроенного. |
| `YANDEX_DIRECT_LANG` | Язык ответов API; по умолчанию `ru`. |
| `YANDEX_DIRECT_TIMEOUT_MS` | Таймаут запроса; по умолчанию 60 000 мс. |
| `YANDEX_DIRECT_MAX_RETRIES` | Число повторов при временных ошибках; по умолчанию 3. |

Получить готовый токен для `YANDEX_DIRECT_TOKEN` можно по ссылке, войдя под аккаунтом с доступом к нужному кабинету:

[**Получить токен Яндекс Директа**](https://oauth.yandex.ru/authorize?response_type=token&client_id=c48790e11f0e48c588d2cd2d1b4bb92d)

Не публикуйте токен в чатах, репозиториях и скриншотах: он даёт доступ к рекламному кабинету, включая действия, которые могут повлиять на бюджет.

## Данные и телеметрия

По умолчанию сервер отправляет анонимные технические события: случайный идентификатор установки, название вызванного инструмента, версии сервера, AI-приложения, Node.js и операционной системы. Это нужно, чтобы понимать, какие части сервера используются и возникают ли проблемы при запуске. Токен Яндекса, данные рекламного кабинета, аргументы инструментов, тексты запросов, значения и названия переменных окружения не отправляются.

Чтобы отключить телеметрию для MCP-серверов Ask Ads, задайте переменную окружения:

```bash
ASKADS_TELEMETRY=0
```

## Ограничения

- **Дневная квота API.** Каждый вызов расходует Units. Инструмент `get_quota` показывает, сколько потрачено, осталось и доступно на сегодня.
- **Лимиты отчётов.** У отчётов Яндекса есть собственные ограничения на объём и количество в сутки, а готовность отчёта в сервисе Reports приходится ждать.
- **Большие списки.** Если при автоматической пагинации достигнут внутренний предел, сервер явно отмечает результат как неполный, а не скрывает это.
- **Временные ошибки.** Сервер делает до трёх повторов при ограничениях частоты. Ошибки сети и сервера автоматически повторяются только для чтения, чтобы не продублировать изменение.
- **Боевой кабинет.** Локальные изменения применяются в реальном рекламном кабинете и могут повлиять на расход. Для тестов используйте песочницу (`YANDEX_DIRECT_SANDBOX=true`).
- **Нет постоянного наблюдения.** Сервер работает во время вызова из AI-приложения. Если приложение поддерживает регулярные задания, можно настроить периодический запрос для проверки нужных показателей.

## Техническая документация

- [Каталог MCP-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента.
- [Все инструменты](https://github.com/askads/mcp-yandex-direct/blob/main/docs/TOOLS.md) — параметры, ответы и границы каждого инструмента.
- [Разработка](https://github.com/askads/mcp-yandex-direct/blob/main/docs/DEVELOPMENT.md) — устройство проекта и работа с исходным кодом.
- [API Яндекс Директа](https://yandex.ru/dev/direct/doc/dg/concepts/about.html) — первоисточник по API и его ограничениям.
- [Пакет npm](https://www.npmjs.com/package/mcp-yandex-direct) — опубликованные версии сервера.

## Поддержка

Нашли ошибку или не хватает сценария? [Создайте issue](https://github.com/askads/mcp-yandex-direct/issues) или напишите в [Telegram](http://t.me/gistrec).