How do I use yandex-direct?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@yandex-direct list my active advertising campaigns" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

yandex-direct

by dontsovcmc

Overview Schema Source Related Servers Discussions Admin

Python

Remote

mcp-server-yandex-direct

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

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

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

Архитектура

Сервер использует паттерн 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 — если не установлен:
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

Для удаления:

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:

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

Через pip (после pip install mcp-server-yandex-direct):

{
  "mcpServers": {
    "yandex-direct": {
      "command": "python",
      "args": ["-m", "mcp_server_yandex_direct"],
      "env": {
        "YD_TOKEN": "ваш_токен"
      }
    }
  }
}

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

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

Из JSON-строки:

claude --mcp-config '{"yandex-direct":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-yandex-direct"]}}'

Из файла:

claude --mcp-config ~/mcp-servers.json

Пример ~/mcp-servers.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

Available Tools

2 tools

yd_executeA

Выполнить действие Yandex Direct API по ID.

Используй yd_search для получения ID и схемы параметров.

Args: action: ID действия из yd_search (например "campaigns-get", "ads-suspend") params_json: JSON-объект с параметрами согласно params_schema из yd_search

Inputs: action (required), params_json. Returns: result

yd_searchA

Read-only

Найти действия Yandex Direct API по намерению. Вызывай первым.

Args: query: что нужно сделать (на русском или английском) domain: фильтр домена (campaigns, adgroups, ads, keywords, bidding, assets, audience, negkeywords, feeds, creatives, research, changes, account, leads, turbopages, reports) limit: максимум результатов (по умолчанию 10)

Inputs: query (required), limit, domain. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-07-28 13:35 across 2 tools

Disambiguation5/5

Two tools with clearly distinct purposes: yd_search for discovering API actions and yd_execute for executing them. No overlap in functionality.

Naming Consistency5/5

Both tools follow a consistent 'yd_verb' pattern (yd_search, yd_execute), making them predictable and easy to use together.

Tool Count3/5

Only 2 tools for a large API like Yandex Direct. While the search+execute pattern is a clever abstraction, it feels thin compared to typical server scopes, but it is intentional for flexibility.

Completeness4/5

The pair covers any Yandex Direct API action through discovery and execution. No dead ends, though missing higher-level convenience tools for common operations.

Maintenance

ActivityInactive

ResponsivenessOutdated data

Resources

Related MCP Connectors

marketscore-direct-mcp
io.github.marketscore
MCP for Yandex Direct: manage ad campaigns & analytics from Claude or ChatGPT
Marketing Search
24
https://app.marketscore.ru/api/mcp
MCPKit — Yandex Direct MCP
io.github.MCPKit-RU
Review Yandex Direct reports and manage supported campaign settings in ChatGPT.
Marketing App Automation
1
https://mcpkit.ru/mcp-yandex-direct/mcp
GrowomatA
com.growomat
Build, edit and sync Google, Microsoft, Reddit and Meta ad campaigns from your assistant.
Marketing Social Media
1131
https://mcp.growomat.com/mcp
Adwarp
io.github.adwarp-dev
Open-source ad agent for LinkedIn Ads and Google Ads. Drafts campaigns, audiences and reports.
Marketing App Automation
125
https://mcp.adwarp.dev/api/mcp

Related MCP Servers

Yandex Direct MCP
E-commerce & Retail Marketing
askads
A
license
B
quality
B
maintenance
Enables managing Yandex Direct PPC campaigns, ad groups, ads, and keywords, plus pulling performance statistics via the Yandex Direct API v5.
Updated 5 days ago (2026-11-06 23:05 UTC)
46
2,212 npm
4
MIT
Yandex MCP Server
Marketing Research & Data
mlenkov
A
license
Not graded
quality
B
maintenance
Enables interaction with Yandex advertising and analytics APIs (Direct, Metrika, Audience, Webmaster, AdMetrica) through MCP tools, resources, and prompts for campaign management and data retrieval.
Updated 4 months ago (2026-07-20 16:43 UTC)
MIT
yandex-mcp
Marketing Search Research & Data
webkoth
A
license
Not graded
quality
C
maintenance
Enables AI assistants to work with Yandex Webmaster, Direct, and Metrika data through natural language, including managing sites, sitemaps, recrawls, ad campaigns with write-safety guards, and pulling traffic, conversion, and ad statistics.
Updated 3 months ago (2026-08-25 11:32 UTC)
MIT
yandex-direct-mcp
Marketing Finance
iarbor04
A
license
A
quality
C
maintenance
Enables AI agents to manage Yandex Direct advertising accounts via the API v5, including reports, bids, campaign management, and semantic analysis through natural language requests.
Updated 2 months ago (2026-08-27 08:56 UTC)
4
87 npm
MIT