# Яндекс Директ MCP
[](https://www.npmjs.com/package/mcp-yandex-direct)
[](https://github.com/askads/mcp-yandex-direct/actions/workflows/ci.yml)
[](https://glama.ai/mcp/servers/askads/mcp-yandex-direct)
[](./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`, см. [Подключение и настройка](#подключение-и-настройка).
Codex
**Через интерфейс приложения:**
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)
Claude Code
```bash
claude mcp add --transport stdio --scope user yandex-direct -- npx -y mcp-yandex-direct@latest
```
Проверить подключение: `claude mcp list`.
Claude Desktop
Откройте **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.
Cursor
Откройте `~/.cursor/mcp.json`, чтобы подключить сервер во всех проектах, или `.cursor/mcp.json` в конкретном проекте. Добавьте:
```json
{
"mcpServers": {
"yandex-direct": {
"command": "npx",
"args": ["-y", "mcp-yandex-direct@latest"]
}
}
}
```
VS Code
В палитре команд выполните **MCP: Open User Configuration**. В открывшемся `mcp.json` добавьте сервер:
```json
{
"servers": {
"yandex-direct": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-yandex-direct@latest"]
}
}
}
```
После сохранения выполните **MCP: List Servers** и запустите сервер из списка.
## Что можно поручить
### Проверить, как расходуется бюджет
- «Какие кампании за прошлую неделю потратили больше всего?»
- «Какие объявления получают показы и клики, но не дают конверсий?»
- «Сравни расход, 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).