Yandex Direct MCP Server
gistrec/mcp-yandex-direct
Gerencie anúncios Yandex Direct via Claude com cobertura completa da API v5
Ver no GitHubMCP server para gerenciar campanhas de publicidade contextual do Yandex Direct (v5 API) diretamente pelo Claude. Controle ativações de anúncios, ajuste lances, analise estatísticas e otimize palavras-chave sem sair da interface do IA, com proteção contra alterações acidentais.
Instalação
npx convez-ai gistrec/mcp-yandex-direct1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Auditoria e otimização de campanhas publicitárias em tempo real
- Análise de performance de palavras-chave e ajuste automático de lances
- Monitoramento de quota de API e execução de tarefas em lote
Veredito

Ferramenta bem arquitetada para agências e gestores de tráfego que usam Yandex Direct. Oferece cobertura robusta da API v5, proteções contra erros e paginação automática — indicado para quem precisa automação sofisticada de campanhas sem perder segurança.
README
A tradução para o português deste README ainda está na fila.
Yandex Direct MCP
MCP-сервер для Yandex Direct API v5: управляйте контекстной рекламой из Claude, Cursor, Codex и других AI-клиентов на естественном языке.
Ассистент сам собирает данные из статистики, ключей, ставок и расширений, находит закономерности и вносит правки — то, что в веб-кабинете Директа приходится делать вручную и по одному экрану.
Что умеет
- Полное покрытие API v5 — частые объекты как удобные инструменты, всё остальное — через универсальный
raw_request. - Защита от случайных записей — универсальный
raw_requestблокирует любой не-read метод безconfirmWrite=true; выделенные write-инструменты (ставки, бюджеты, минус-слова, статусы) проходят штатное подтверждение MCP-клиента перед вызовом. - Деньги в валюте аккаунта — бюджеты и ставки на вход и на выход в той же валюте, что и кабинет (например, в рублях), без ручного пересчёта микроединиц.
autoPaginate— проход всех страниц по курсоруLimitedBy, без молчаливой обрезки на больших аккаунтах.get_quota— остаток дневной квоты API в Units (потрачено / осталось / лимит).- Устойчивость — ретраи на лимитах и 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).
Быстрая установка
Разверните своего клиента:
claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y mcp-yandex-direct
claude_desktop_config.json — macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\
{
"mcpServers": {
"yandex-direct": {
"command": "npx",
"args": ["-y", "mcp-yandex-direct"],
"env": { "YANDEX_DIRECT_TOKEN": "ваш_токен" }
}
}
}
~/.cursor/mcp.json (или .cursor/mcp.json в проекте)
{
"mcpServers": {
"yandex-direct": {
"command": "npx",
"args": ["-y", "mcp-yandex-direct"],
"env": { "YANDEX_DIRECT_TOKEN": "ваш_токен" }
}
}
}
Командой: codex mcp add yandex-direct --env YANDEX_DIRECT_TOKEN=ваш_токен -- npx -y mcp-yandex-direct
Или в ~/.codex/config.toml:
[mcp_servers.yandex-direct]
command = "npx"
args = ["-y", "mcp-yandex-direct"]
[mcp_servers.yandex-direct.env]
YANDEX_DIRECT_TOKEN = "ваш_токен"
.vscode/mcp.json — ключ servers (не mcpServers)
{
"servers": {
"yandex-direct": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-yandex-direct"],
"env": { "YANDEX_DIRECT_TOKEN": "ваш_токен" }
}
}
}
Получение токена
Откройте ссылку, залогинившись под аккаунтом с доступом к нужному кабинету Яндекс Директа, и подтвердите доступ — токен покажется на странице:
Скопируйте токен в YANDEX_DIRECT_TOKEN. Токен персональный (привязан к вашему кабинету) и действует около года; при утере его можно получить заново по той же ссылке.
⚠️ Токен даёт полный доступ к рекламному кабинету (включая трату бюджета) и хранится открытым текстом в конфиге клиента — относитесь к нему как к паролю.
Настройка
| Переменная | Обяз. | Описание |
|---|---|---|
YANDEX_DIRECT_TOKEN | да | OAuth-токен Яндекс Директа. |
YANDEX_DIRECT_LOGIN | нет | Логин клиента (для агентских аккаунтов). |
YANDEX_DIRECT_SANDBOX | нет | true — работать в песочнице API. |
Полный список переменных (язык ответов, таймауты, повторы) и инструментов — в docs/TOOLS.md.
Требования
- Node.js 18+ (запускается через
npx, отдельная установка не нужна). - OAuth-токен Яндекс Директа — см. Получение токена.
Ограничения
get_statisticsиспользует асинхронный сервис Reports: отчёт генерируется на стороне Яндекса (сервер опрашивает готовность) и имеет собственные лимиты на объём и число отчётов в сутки.- Токен живёт около года — потом нужно получить заново.
- Для агентских аккаунтов укажите клиента через
YANDEX_DIRECT_LOGIN.
Документация
- Все инструменты — полный список с описанием.
- Разработка — сборка, тесты, smoke-проверка.
Поддержка
Вопросы, идеи и доработки — пишите в Telegram: @gistrec.
Лицензия
MIT — см. LICENSE.