io.github.gistrec/mcp-yandex-direct

Official

by askads · TypeScript

Yandex Direct

MCP server for Yandex Direct API v5: manage PPC campaigns, ads, keywords, and statistics.

Manages Yandex Direct PPC advertising campaigns, ads, keywords, and performance metrics.

Topics

advertisingclaudemcpmodel-context-protocolppctypescriptyandexyandex-directaicodexcursor

README.md14 KBView on GitHub

Yandex Direct MCP

MCP-сервер для Yandex Direct API v5: управляйте контекстной рекламой из Claude, Cursor, Codex и других AI-клиентов на естественном языке.

Ассистент сам собирает данные из статистики, ключей, ставок и расширений, находит закономерности и вносит правки — то, что в веб-кабинете Директа приходится делать вручную и по одному экрану.

Настоящая MCP-сессия: реальный сервер, хендшейк и tools/call по stdio через официальный SDK; ответы Яндекс Директа — записанные фикстуры (<a href="docs/demo">docs/demo</a>), поэтому демо воспроизводится без токена и сети — <a href="docs/demo.tape">vhs docs/demo.tape</a>.

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

Два способа подключиться:

По URL, без установки — MCP-эндпоинт https://mcp.askads.ru/mcp: вставляете URL в клиент и входите через Яндекс в браузере, токены не нужны. Бесплатно, только чтение — статистика и аудит. → Подключение по URL

Локально через npx — полный доступ, включая правки ставок и бюджетов; токен хранится только у вас:

Получите токен — одна ссылка, токен покажется на странице.
Добавьте сервер — например, в Claude Code (другие клиенты):
bash
```
claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y mcp-yandex-direct
```
Спросите ассистента: «Проанализируй мои кампании за неделю и предложи, что улучшить».

Что умеет

Полное покрытие API v5 — частые объекты как удобные инструменты, всё остальное — через универсальный raw_request.
Защита от случайных записей — универсальный raw_request блокирует любой не-read метод без confirmWrite=true; выделенные write-инструменты (ставки, бюджеты, минус-слова, статусы) проходят штатное подтверждение MCP-клиента перед вызовом.
Деньги в валюте аккаунта — бюджеты и ставки на вход и на выход в той же валюте, что и кабинет (например, в рублях), без ручного пересчёта микроединиц.
autoPaginate — проход всех страниц по курсору LimitedBy, без молчаливой обрезки на больших аккаунтах.
get_quota — остаток дневной квоты API в Units (потрачено / осталось / лимит).
get_balance — баланс единого счёта (сумма, доступно к переводу, валюта) через Live v4 AccountManagement — единственный метод API, отдающий баланс (в v5 его нет). Отрицательная сумма = задолженность.
Устойчивость — ретраи на лимитах и 5xx с бэкоффом плюс режим песочницы (YANDEX_DIRECT_SANDBOX) для безопасных тестов.

Примеры запросов

Попросите ассистента на русском — например:

«Какие ключевые фразы тратят бюджет, но не приносят кликов?»
«Подними ставки до 3 ₽ на фразы с CTR выше 15%»
«Найди id региона Москва и создай группу с таргетингом на Москву»
«Поставь корректировку −20% на мобильные в кампании 708589088»

Пример: аудит кампании

Вы: Проанализируй кампанию ClearTranscriptBot за последнюю неделю и предложи, что улучшить.

Claude (вызывает get_statistics, list_keywords, get_callouts, get_sitelinks):

Кампания «EPK/Поиск — бот в Max и Telegram» за 7 дней:

Дата Показы Клики CTR Расход, ₽ Ср. клик, ₽
08.06 544 90 16.5% 782.50 8.69
09.06 456 70 15.4% 528.93 7.56
10.06 206 39 18.9% 254.48 6.53
11.06 198 36 18.2% 205.87 5.72
12.06 275 37 13.5% 178.95 4.84
13.06 332 45 13.6% 214.62 4.77
14.06 419 82 19.6% 481.55 5.87
Итого 2 430 399 16.4% 2 646.90 6.63

Что улучшить:

Автотаргетинг забирает почти весь трафик. Условие ---autotargeting собирает основную долю показов и кликов, а ключи («расшифровка интервью», «транскрибация записи» …) получают по 1–22 показа и почти 0 кликов — стоит усилить ставки на фразы или точнее настроить автотаргетинг.

Ставки на минимуме (0.30 ₽), а CTR высокий (16–20%). На поиске при таком CTR имеет смысл поднять ставки на топ-фразы — заберёте больше недорогих показов.

Объявление 17674525479 отстаёт (CTR 2–10% против 17–20% у основного) — кандидат на переработку заголовка/текста или отключение.

Расширения в порядке — 9 уточнений и 3 быстрые ссылки; можно добавить ещё пару быстрых ссылок (лимит — 8).

Подключение по URL (без установки)

https://mcp.askads.ru/mcp — удалённый сервер Яндекс Директа (зеркало — https://mcp.askads.cloud/mcp). Не нужны ни Node.js, ни токен в конфиге: клиент откроет браузер, вы войдёте через Яндекс и подтвердите доступ — как обычное «Войти с Яндексом». Сервер только читает (статистика, кампании, аудит) и бесплатен — правки доступны в локальной установке. Подробнее — на mcp.askads.ru.

<details> <summary>Claude Desktop / claude.ai</summary>

Настройки → Connectors → Add custom connector → вставьте https://mcp.askads.ru/mcp → войдите через Яндекс.

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

bash

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

Затем в сессии /mcp → Authenticate. Либо через маркетплейс плагинов:

code

/plugin marketplace add askads/claude-plugins
/plugin install yandex-direct@askads

</details> <details> <summary>ChatGPT</summary>

Settings → Apps & Connectors → Advanced settings → включите Developer mode → Create → вставьте https://mcp.askads.cloud/mcp (для ChatGPT используйте зеркало .cloud). Требуется план с поддержкой коннекторов.

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

~/.cursor/mcp.json:

json

{
  "mcpServers": {
    "yandex-direct": { "url": "https://mcp.askads.ru/mcp" }
  }
}

</details>

Установка

Локальный сервер через npx — полный доступ, включая write-инструменты. Разверните своего клиента:

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

bash

claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y mcp-yandex-direct

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

claude_desktop_config.json — macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\

json

{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct"],
      "env": { "YANDEX_DIRECT_TOKEN": "ваш_токен" }
    }
  }
}

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

~/.cursor/mcp.json (или .cursor/mcp.json в проекте)

json

{
  "mcpServers": {
    "yandex-direct": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct"],
      "env": { "YANDEX_DIRECT_TOKEN": "ваш_токен" }
    }
  }
}

</details> <details> <summary>OpenAI Codex</summary>

Командой: codex mcp add yandex-direct --env YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y mcp-yandex-direct

Или в ~/.codex/config.toml:

toml

[mcp_servers.yandex-direct]
command = "npx"
args = ["-y", "mcp-yandex-direct"]

[mcp_servers.yandex-direct.env]
YANDEX_DIRECT_TOKEN = "ваш_токен"

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

.vscode/mcp.json — ключ servers (не mcpServers)

json

{
  "servers": {
    "yandex-direct": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-direct"],
      "env": { "YANDEX_DIRECT_TOKEN": "ваш_токен" }
    }
  }
}

</details>

Получение токена

Откройте ссылку, залогинившись под аккаунтом с доступом к нужному кабинету Яндекс Директа, и подтвердите доступ:

→ Получить токен

Браузер вернёт вас на сайт Ask Ads — токен покажется во всплывающем окне, скопируйте его в YANDEX_DIRECT_TOKEN. Токен персональный (привязан к вашему кабинету) и действует около года; при утере его можно получить заново по той же ссылке.

⚠️ Токен даёт полный доступ к рекламному кабинету (включая трату бюджета) и хранится открытым текстом в конфиге — относитесь к нему как к паролю.

Настройка

Переменная	Обяз.	Описание
`YANDEX_DIRECT_TOKEN`	да	OAuth-токен Яндекс Директа.
`YANDEX_DIRECT_LOGIN`	нет	Логин клиента (для агентских аккаунтов).
`YANDEX_DIRECT_SANDBOX`	нет	`true` — работать в песочнице API.

Полный список переменных (язык ответов, таймауты, повторы) и инструментов — в docs/TOOLS.md.

Требования

Для подключения по URL — ничего: только аккаунт Яндекса с доступом к кабинету.
Для локальной установки: Node.js 20+ (запускается через npx, отдельная установка не нужна) и OAuth-токен — см. Получение токена.

Ограничения

get_statistics использует асинхронный сервис Reports: отчёт генерируется на стороне Яндекса (сервер опрашивает готовность) и имеет собственные лимиты на объём и число отчётов в сутки.
Токен живёт около года — потом нужно получить заново.
Для агентских аккаунтов укажите клиента через YANDEX_DIRECT_LOGIN.

Документация

Все инструменты — полный список с описанием.
Разработка — сборка, тесты, smoke-проверка.

Смотрите также

Ask Ads — чат-аналитик и «Сторож» рекламных кабинетов от авторов этого сервера: алерты о сливах бюджета и поломках трекинга — в Telegram.
askads/claude-plugins — маркетплейс плагинов Claude: серверы Ask Ads ставятся одной командой, токены спрашиваются при включении.

Поддержка

Вопросы, идеи и доработки — пишите в Telegram: @gistrec.

Лицензия

MIT — см. LICENSE.

Install

Configuration

Environment variables

YANDEX_DIRECT_TOKENrequiredsecret

Yandex Direct OAuth token — full account access (can spend budget). Treat it as a secret.

YANDEX_DIRECT_LOGIN

Client login to target a specific account on agency tokens.

YANDEX_DIRECT_SANDBOXdefault false

Set to true to call the Yandex Direct sandbox API instead of production.

YANDEX_DIRECT_LANGdefault ru

Language for API responses and error messages (ru, en, ...).

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-yandex-direct": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-yandex-direct@1.0.5"
      ],
      "env": {
        "YANDEX_DIRECT_TOKEN": "<YOUR_YANDEX_DIRECT_TOKEN>",
        "YANDEX_DIRECT_LOGIN": "<YOUR_YANDEX_DIRECT_LOGIN>",
        "YANDEX_DIRECT_SANDBOX": "false",
        "YANDEX_DIRECT_LANG": "ru"
      }
    }
  }
}

Дата	Показы	Клики	CTR	Расход, ₽	Ср. клик, ₽
08.06	544	90	16.5%	782.50	8.69
09.06	456	70	15.4%	528.93	7.56
10.06	206	39	18.9%	254.48	6.53
11.06	198	36	18.2%	205.87	5.72
12.06	275	37	13.5%	178.95	4.84
13.06	332	45	13.6%	214.62	4.77
14.06	419	82	19.6%	481.55	5.87
Итого	2 430	399	16.4%	2 646.90	6.63