# Yandex Direct
**Category:** 💻 Developer Tools
**Repository:** https://github.com/askads/mcp-yandex-direct
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/yandex-direct
## Description
MCP server for Yandex Direct API v5: manage PPC campaigns, ads, keywords, and statistics.
## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):
```json
"mcpServers": {
"yandex-direct": {
"command": "npx",
"args": ["-y","yandex-direct"]
}
}
```
## Documentation & README
# Yandex Direct 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-сервер для **Yandex Direct API v5**: управляйте контекстной рекламой из Claude, Cursor, Codex и других AI-клиентов на естественном языке.
Ассистент сам собирает данные из статистики, ключей, ставок и расширений, находит закономерности и вносит правки — то, что в веб-кабинете Директа приходится делать вручную и по одному экрану.
Настоящая MCP-сессия: реальный сервер, хендшейк и tools/call по stdio через официальный SDK; ответы Яндекс Директа — записанные фикстуры (docs/demo), поэтому демо воспроизводится без токена и сети — vhs docs/demo.tape.
## Быстрый старт
Два способа подключиться:
**По URL, без установки** — MCP-эндпоинт `https://mcp.askads.ru/mcp`: вставляете URL в клиент и входите через Яндекс в браузере, токены не нужны. Бесплатно, только чтение — статистика и аудит. → [Подключение по URL](#подключение-по-url-без-установки)
**Локально через npx** — полный доступ, включая правки ставок и бюджетов; токен хранится только у вас:
1. [Получите токен](#получение-токена) — одна ссылка, токен покажется на странице.
2. Добавьте сервер — например, в Claude Code ([другие клиенты](#установка)):
```bash
claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y mcp-yandex-direct@latest
```
3. Спросите ассистента: «Проанализируй мои кампании за неделю и предложи, что улучшить».
## Что умеет
- **Полное покрытие 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** |
>
> **Что улучшить:**
> 1. **Автотаргетинг забирает почти весь трафик.** Условие `---autotargeting` собирает основную долю показов и кликов, а ключи («расшифровка интервью», «транскрибация записи» …) получают по 1–22 показа и почти 0 кликов — стоит усилить ставки на фразы или точнее настроить автотаргетинг.
> 2. **Ставки на минимуме (0.30 ₽), а CTR высокий (16–20%).** На поиске при таком CTR имеет смысл поднять ставки на топ-фразы — заберёте больше недорогих показов.
> 3. **Объявление 17674525479 отстаёт** (CTR 2–10% против 17–20% у основного) — кандидат на переработку заголовка/текста или отключение.
> 4. **Расширения в порядке** — 9 уточнений и 3 быстрые ссылки; можно добавить ещё пару быстрых ссылок (лимит — 8).
## Подключение по URL (без установки)
`https://mcp.askads.ru/mcp` — удалённый сервер Яндекс Директа (зеркало — `https://mcp.askads.cloud/mcp`). Не нужны ни Node.js, ни токен в конфиге: клиент откроет браузер, вы войдёте через Яндекс и подтвердите доступ — как обычное «Войти с Яндексом». Сервер **только читает** (статистика, кампании, аудит) и бесплатен — правки доступны в локальной установке. Подробнее — на [mcp.askads.ru](https://mcp.askads.ru).
Claude Desktop / claude.ai
Настройки → **Connectors** → **Add custom connector** → вставьте `https://mcp.askads.ru/mcp` → войдите через Яндекс.
Claude Code
```bash
claude mcp add --transport http yandex-direct https://mcp.askads.ru/mcp
```
Затем в сессии `/mcp` → **Authenticate**. Либо через маркетплейс плагинов:
```
/plugin marketplace add askads/claude-plugins
/plugin install yandex-direct@askads
```
ChatGPT
Settings → **Apps & Connectors** → **Advanced settings** → включите **Developer mode** → **Create** → вставьте `https://mcp.askads.cloud/mcp` (для ChatGPT используйте зеркало `.cloud`). Требуется план с поддержкой коннекторов.
Cursor
`~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"yandex-direct": { "url": "https://mcp.askads.ru/mcp" }
}
}
```
## Установка
Локальный сервер через npx — полный доступ, включая write-инструменты. Разверните своего клиента:
Claude Code
```bash
claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y mcp-yandex-direct@latest
```
Claude Desktop
`claude_desktop_config.json` — macOS `~/Library/Application Support/Claude/`, Windows `%APPDATA%\Claude\`
```json
{
"mcpServers": {
"yandex-direct": {
"command": "npx",
"args": ["-y", "mcp-yandex-direct@latest"],
"env": { "YANDEX_DIRECT_TOKEN": "ваш_токен" }
}
}
}
```
Cursor
`~/.cursor/mcp.json` (или `.cursor/mcp.json` в проекте)
```json
{
"mcpServers": {
"yandex-direct": {
"command": "npx",
"args": ["-y", "mcp-yandex-direct@latest"],
"env": { "YANDEX_DIRECT_TOKEN": "ваш_токен" }
}
}
}
```
OpenAI Codex
Командой: `codex mcp add yandex-direct --env YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y mcp-yandex-direct@latest`
Или в `~/.codex/config.toml`:
```toml
[mcp_servers.yandex-direct]
command = "npx"
args = ["-y", "mcp-yandex-direct@latest"]
[mcp_servers.yandex-direct.env]
YANDEX_DIRECT_TOKEN = "ваш_токен"
```
VS Code
`.vscode/mcp.json` — ключ `servers` (не `mcpServers`)
```json
{
"servers": {
"yandex-direct": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-yandex-direct@latest"],
"env": { "YANDEX_DIRECT_TOKEN": "ваш_токен" }
}
}
}
```
## Получение токена
Откройте ссылку, **залогинившись под аккаунтом с доступом к нужному кабинету Яндекс Директа**, и подтвердите доступ:
[**→ Получить токен**](https://oauth.yandex.ru/authorize?response_type=token&client_id=c48790e11f0e48c588d2cd2d1b4bb92d)
Браузер вернёт вас на сайт Ask Ads — токен покажется **во всплывающем окне**, скопируйте его в `YANDEX_DIRECT_TOKEN`. Токен персональный (привязан к вашему кабинету) и действует около года; при утере его можно получить заново по той же ссылке.
⚠️ Токен даёт **полный доступ** к рекламному кабинету (включая трату бюджета) и хранится **открытым текстом** в конфиге — относитесь к нему как к паролю.
## Настройка
| Переменная | Обяз. | Описание |
|---|---|---|
| `YANDEX_DIRECT_TOKEN` | да | OAuth-токен Яндекс Директа. |
| `YANDEX_DIRECT_LOGIN` | нет | Логин клиента (для агентских аккаунтов). |
| `YANDEX_DIRECT_SANDBOX` | нет | `true` — работать в песочнице API. |
Полный список переменных (язык ответов, таймауты, повторы) и инструментов — в [docs/TOOLS.md](https://github.com/askads/mcp-yandex-direct/blob/main/docs/TOOLS.md).
## Требования
- Для подключения по URL — ничего: только аккаунт Яндекса с доступом к кабинету.
- Для локальной установки: Node.js 20+ (запускается через `npx`, отдельная установка не нужна) и OAuth-токен — см. [Получение токена](#получение-токена).
## Ограничения
- `get_statistics` использует асинхронный сервис Reports: отчёт генерируется на стороне Яндекса (сервер опрашивает готовность) и имеет собственные лимиты на объём и число отчётов в сутки.
- Токен живёт около года — потом нужно получить заново.
- Для агентских аккаунтов укажите клиента через `YANDEX_DIRECT_LOGIN`.
## Документация
- [Все инструменты](https://github.com/askads/mcp-yandex-direct/blob/main/docs/TOOLS.md) — полный список с описанием.
- [Разработка](https://github.com/askads/mcp-yandex-direct/blob/main/docs/DEVELOPMENT.md) — сборка, тесты, smoke-проверка.
## Смотрите также
- **[Ask Ads](https://askads.ru)** — чат-аналитик и «Сторож» рекламных кабинетов от авторов этого сервера: алерты о сливах бюджета и поломках трекинга — в Telegram.
- **[askads/claude-plugins](https://github.com/askads/claude-plugins)** — маркетплейс плагинов Claude: серверы Ask Ads ставятся одной командой, токены спрашиваются при включении.
## Поддержка
Вопросы, идеи и доработки — пишите в Telegram: [@gistrec](http://t.me/gistrec).
## Лицензия
MIT — см. [LICENSE](./LICENSE).