mcp-server-yandex-direct

![Version](https://github.com/dontsovcmc/mcp-server-yandex-direct)

MCP-сервер, CLI-утилита и библиотека Pydantic-моделей для Yandex Direct API v5.

MCP-сервер — интеграция с Claude Code, Claude Desktop и другими MCP-клиентами
CLI-утилита — работа с API из терминала, скрипты и автоматизация
Pydantic-модели — типизированные модели API для использования в своих Python-программах

Все данные остаются на вашем компьютере — токен никуда не передаётся.

Архитектура
Доступные действия
MCP-сервер
Установка
Подключение к Claude Code
Подключение к Claude Desktop
Подключение через --mcp-config
Примеры
CLI-утилита
Установка
Использование
Примеры команд
Pydantic-модели
Установка
Использование в своих программах
Переменные окружения
Разработка
Лицензия

Архитектура

Сервер использует паттерн search + execute — вместо 79 отдельных инструментов предоставляет 2:

| Инструмент | Описание | |------------|----------| | yd_search | Поиск действий по описанию на естественном языке | | yd_execute | Выполнение действия по ID |

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

LLM: yd_search("остановить кампании")
→ [{"id": "campaigns-suspend", "params_schema": {"SelectionCriteria": {...}, ...}, ...}]

LLM: yd_execute("campaigns-suspend", '{"SelectionCriteria": {"Ids": [12345]}}')
→ {"SuspendResults": [...]}

Доступные действия (79)

| Домен | Кол-во | Описание | |-------|--------|----------| | campaigns | 8 | Кампании: создание, управление, архивация | | adgroups | 4 | Группы объявлений | | ads | 9 | Объявления: создание, управление, модерация | | keywords | 6 | Ключевые слова | | bidding | 7 | Ставки и корректировки ставок | | assets | 11 | Быстрые ссылки, изображения, видео, расширения | | audience | 10 | Аудитории и ретаргетинг | | negkeywords | 4 | Общие списки минус-слов | | feeds | 4 | Фиды для динамических объявлений | | creatives | 2 | Креативы для медийных объявлений | | research | 2 | Исследование ключевых слов | | leads | 1 | Лиды из форм лидогенерации | | changes | 3 | Отслеживание изменений | | account | 6 | Аккаунт, справочники, клиенты агентства | | turbopages | 1 | Турбо-страницы | | reports | 1 | Отчёты (TSV/CSV) |

---

MCP-сервер

Установка

Шаг 1. Получить OAuth-токен

Войдите в Яндекс Директ
Перейдите в Настройки → API
Создайте OAuth-токен с нужными правами
Скопируйте токен

Шаг 2. Подключить MCP-сервер

Подключение к Claude Code

Способ 1: через uvx (не требует установки пакета)

Требуется uv — если не установлен: ``bash curl -LsSf https://astral.sh/uv/install.sh | sh ``

claude mcp add yandex-direct \
  -e YD_TOKEN=ваш_токен \
  -- uvx mcp-server-yandex-direct

Способ 2: через pip

pip install mcp-server-yandex-direct

claude mcp add yandex-direct \
  -e YD_TOKEN=ваш_токен \
  -- python -m mcp_server_yandex_direct

Для удаления: ``bash claude mcp remove yandex-direct ``

Подключение к Claude Desktop

Добавьте в конфигурационный файл:

| Клиент | ОС | Путь к файлу | |--------|----|-------------| | Claude Code | все | ~/.claude/settings.json (секция mcpServers) | | Claude Desktop | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Claude Desktop | Linux | ~/.config/Claude/claude_desktop_config.json |

Через uvx: ``json { "mcpServers": { "yandex-direct": { "command": "uvx", "args": ["mcp-server-yandex-direct"], "env": { "YD_TOKEN": "ваш_токен" } } } } ``

Через pip (после pip install mcp-server-yandex-direct): ``json { "mcpServers": { "yandex-direct": { "command": "python", "args": ["-m", "mcp_server_yandex_direct"], "env": { "YD_TOKEN": "ваш_токен" } } } } ``

Подключение через --mcp-config

Подключает сервер только на время одной сессии Claude, не сохраняя в настройки. Токен хранится в отдельном .env.mcp файле, а не в конфиге Claude.

Из JSON-строки: ``bash claude --mcp-config '{"yandex-direct":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-yandex-direct"]}}' ``

Из файла: ``bash claude --mcp-config ~/mcp-servers.json ``

Пример ~/mcp-servers.json: ``json { "yandex-direct": { "command": "bash", "args": ["-c", "source ~/.env.mcp && exec uvx mcp-server-yandex-direct"] } } ``

Пример ~/.env.mcp: `` YD_TOKEN=ваш_токен ``

Шаг 3. Проверить

Попросите Claude: «Покажи список кампаний» — он вызовет yd_search, получит схему campaigns-get, затем yd_execute.

Примеры (MCP)

Claude автоматически использует yd_search для поиска нужного действия, затем yd_execute для его выполнения:

«Покажи все активные кампании» → yd_search("кампании") → yd_execute("campaigns-get", ...)
«Останови кампании 123, 456» → yd_search("остановить кампании") → yd_execute("campaigns-suspend", ...)
«Покажи объявления кампании 789» → yd_search("объявления") → yd_execute("ads-get", ...)
«Добавь ключевую фразу» → yd_search("ключевые слова добавить") → yd_execute("keywords-add", ...)
«Получи справочник регионов» → yd_search("справочники") → yd_execute("dictionaries-get", ...)
«Сделай отчёт по кампаниям за январь» → yd_search("отчёт") → yd_execute("reports-get", ...)

---

CLI-утилита

Установка (CLI)

pip install mcp-server-yandex-direct

Переменная окружения YD_TOKEN должна быть установлена:

export YD_TOKEN=ваш_токен

Или через файл:

mcp-server-yandex-direct --env /path/to/.env <command>

Формат файла — KEY=VALUE, по одной переменной на строку, #-комментарии.

Использование (CLI)

Без аргументов запускается MCP-сервер, с командой — CLI. Все команды выводят JSON.

# Версия
mcp-server-yandex-direct --version

# Справка
mcp-server-yandex-direct --help
mcp-server-yandex-direct <command> --help

Примеры команд

# Кампании
mcp-server-yandex-direct campaigns-get '{"SelectionCriteria": {}, "FieldNames": ["Id", "Name", "State"]}'
mcp-server-yandex-direct campaigns-suspend 123,456

# Объявления
mcp-server-yandex-direct ads-get '{"SelectionCriteria": {"CampaignIds": [123]}, "FieldNames": ["Id", "Type", "State"]}'
mcp-server-yandex-direct ads-moderate 789,101

# Ключевые фразы
mcp-server-yandex-direct keywords-get '{"SelectionCriteria": {"AdGroupIds": [111]}, "FieldNames": ["Id", "Keyword", "State"]}'

# Справочники
mcp-server-yandex-direct dictionaries-get Currencies,Regions

# Отчёты
mcp-server-yandex-direct reports-get '{"params": {"SelectionCriteria": {"DateFrom": "2026-01-01", "DateTo": "2026-04-28"}, "FieldNames": ["Date", "CampaignId", "Clicks", "Cost"], "ReportName": "My Report", "ReportType": "CAMPAIGN_PERFORMANCE_REPORT", "DateRangeType": "CUSTOM_DATE", "Format": "TSV"}}'

Пример вывода

$ mcp-server-yandex-direct campaigns-get '{"SelectionCriteria": {"States": ["ON"]}, "FieldNames": ["Id", "Name"]}'
{"Campaigns": [{"Id": 12345, "Name": "Летняя распродажа"}]}

---

Pydantic-модели

Пакет содержит типизированные Pydantic-модели всех объектов API. Модели можно использовать в своих Python-программах для валидации данных и автодополнения в IDE.

Установка (библиотеки)

pip install mcp-server-yandex-direct

Использование в своих программах

from mcp_server_yandex_direct.models.campaigns import CampaignsGetParams, CampaignsSelectionCriteria

# Валидация данных из API
params = CampaignsGetParams(
    SelectionCriteria=CampaignsSelectionCriteria(States=["ON"]),
    FieldNames=["Id", "Name", "State"],
)
print(params.model_dump_json())

# Валидация ответа
from mcp_server_yandex_direct.models.campaigns import CampaignsGetResult

data = {"Campaigns": [{"Id": 12345, "Name": "Тест", "State": "ON"}]}
result = CampaignsGetResult.model_validate(data)
print(result.Campaigns[0].Name)  # type-safe доступ к полям

Все модели используют extra="allow" для forward compatibility — неизвестные поля API не вызывают ошибок.

Полный список моделей: models/

---

Переменные окружения

| Переменная | Обязательная | По умолчанию | Описание | |------------|:------------:|:------------:|----------| | YD_TOKEN | да | — | OAuth-токен Yandex Direct API | | YD_CLIENT_LOGIN | нет | — | Логин клиента для агентских аккаунтов | | YD_LANG | нет | — | Язык ответов: ru, en, uk | | YD_TIMEOUT | нет | 30 | Таймаут HTTP-запросов к API (секунды) | | YD_FILE_TIMEOUT | нет | 120 | Таймаут отчётов Reports API (секунды) |

Разработка

pip install -e ".[test]"
ruff check src/ tests/
pytest tests/ -v

Лицензия

MIT

mcp-server-yandex-direct