yandex-direct-mcp-plus
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| YANDEX_DIRECT_LOGIN | No | Логин клиента для агентских токенов (заголовок Client-Login). Обязателен, если токен агентский | |
| YANDEX_DIRECT_TOKEN | Yes | OAuth-токен Яндекс.Директ |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Сервер работает с API Яндекс.Директа v5 в боевом аккаунте: тестовой среды у Директа нет с июля 2026, любой пишущий вызов меняет настоящие кампании. Подключение — из диалога, без ручного токена: start_login даёт ссылку, её показать пользователю; код, который Яндекс покажет после входа, передать в finish_login. Кто подключён и откуда токен — auth_status. Деньги на входе и выходе — в рублях. ID — десятичные строки: 19-значные ID Директа не помещаются в число без потери точности. Чего Директ через API не делает, хотя в WSDL методы объявлены (ошибка 3500): не создаёт смарт-баннеры и динамические объявления (с 22.05.2026) и визитки. Такие объекты заводятся в интерфейсе Директа; дальше сервер их читает, кампании — правит. Единую перфоманс-кампанию сервер пока только читает: создать её можно в интерфейсе Директа. Отказ по отдельному объекту приходит строкой ❌, и вызов помечается ошибкой, но остальные объекты пакета при этом обработаны: повторять только то, что не прошло. У частых кодов ошибок в тексте есть подсказка «Что делать» — ей следовать, а не повторять вызов вслепую.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| start_loginA | Первый шаг входа из диалога, без ручного токена: возвращает ссылку на вход в Яндекс. Ссылку показать пользователю, код со страницы Яндекса передать в finish_login. Повторный вызов делает прежнюю ссылку недействительной. |
| finish_loginA | Второй шаг входа: меняет код подтверждения от пользователя на токен и сохраняет его на этом компьютере. Токен в ответ не попадает. |
| auth_statusA | Откуда сервер берёт токен (переменная окружения, вход из диалога или запрос) и до когда он действует. В сеть не ходит, баллов не тратит. |
| logoutA | Удаляет сохранённый вход из диалога с этого компьютера. Переменную YANDEX_DIRECT_TOKEN не трогает; доступ приложения отзывается в Яндекс ID. |
| list_campaignsA | Список рекламных кампаний Яндекс.Директ с фильтрацией по статусу и типу. Бюджеты — в рублях. По умолчанию возвращается узкий набор полей; нужны другие (Funds, TimeZone, NegativeKeywords и прочие из CampaignFieldEnum) — перечислите их в fields. Кампаний «Баннер на поиске» (MCBANNER) API не отдаёт вовсе: их нет в списке, и это граница API, а не ошибка логина или фильтра — такие кампании видны только в веб-интерфейсе. |
| get_campaignA | Детальная информация о кампании по ID: бюджет (руб), статус и пояснение к нему, даты, статистика, UTM-разметка, цели и их ценность (PriorityGoals), счётчики Метрики, модель атрибуции и прочие настройки. Реальные ID целей — PriorityGoals.Items[].GoalId; GoalId 13 в стратегии — служебное «ключевые цели», то есть оптимизация по этим PriorityGoals. Пустой ответ по ID из веб-интерфейса не значит, что номер неверный: кампании «Баннер на поиске» (MCBANNER) API не отдаёт, по ID они приходят пустыми. |
| create_campaignA | Создать новую текстово-графическую кампанию. Бюджет в рублях; счётчики Метрики и модель атрибуции задаются сразу. Смарт-баннеры и динамические объявления Директ через API не создаёт с 22.05.2026, единую перфоманс-кампанию этот сервер пока не создаёт: такие кампании заводятся в интерфейсе Директа, дальше их можно читать и править здесь. ⚠️ Тестовой среды у Директа нет: кампания создаётся в боевом аккаунте. Деньги она начнёт тратить после модерации и включения, поэтому созданную для проверки оставляйте черновиком. |
| update_campaignA | Обновить кампанию: название, бюджет (руб), UTM-разметку, счётчики Метрики, модель атрибуции и/или статус (SUSPEND/RESUME/ARCHIVE/UNARCHIVE). Разметка действует на ссылки всех объявлений кампании. Список счётчиков заменяется целиком. |
| manage_campaignsA | Запустить, остановить, архивировать, разархивировать или удалить кампании. ⚠️ delete необратимо и недоступен кампании с накопленной статистикой — такую только архивировать. |
| get_strategyA | Получить текущую стратегию показов текстово-графической кампании вместе с целями (PriorityGoals), счётчиками и моделью атрибуции. Реальные ID целей Метрики, по которым работает кампания, — TextCampaign.PriorityGoals.Items[].GoalId (рядом их ценность Value в рублях), счётчики — CounterIds. GoalId внутри BiddingStrategy бывает служебным: 13 — «оптимизировать по ключевым целям», то есть по тем же PriorityGoals; 12 — «Вовлечённые сессии». Названий целей API Директа не отдаёт — они есть только в Метрике. |
| set_strategyB | Изменить стратегию текстово-графической кампании: ручная, максимум кликов, средняя цена клика или конверсии, оплата за конверсию. Цены — в рублях, цель Метрики — goal_id. |
| set_priority_goalsA | Задать цели стратегии кампании (PriorityGoals) и их ценность в рублях — по ним автостратегия оптимизирует ставки, в том числе «максимум конверсий» со служебным GoalId 13. Режим mode обязателен: add добавляет цели или меняет ценность уже заданных, remove убирает названные, replace заменяет список целиком (пустой массив очищает). Текущий список сервер читает сам. Чтобы добавить цель к существующим, нужен add: replace с одной целью сотрёт остальные. ⚠️ Смена целей перезапускает обучение стратегии. Поддерживаются текстово-графические, динамические, смарт и единые перфоманс-кампании; ID целей — из Метрики. |
| get_time_targetingB | Временной таргетинг кампании: часовой пояс, часы показов по дням недели, почасовые коэффициенты и настройка праздников. |
| set_time_targetingA | Задать расписание показов кампании: дни, часы, почасовые коэффициенты, праздники и часовой пояс. ⚠️ Расписание заменяется целиком: часы вне переданных правил показов не получат. |
| list_ad_groupsB | Группы объявлений выбранных кампаний: названия, регионы, статусы. По умолчанию возвращается узкий набор полей; нужны другие (NegativeKeywords, NegativeKeywordSharedSetIds, TrackingParams, ServingStatus и прочие из AdGroupFieldEnum) — перечислите их в fields. |
| create_ad_groupB | Создать группу объявлений в кампании с таргетингом по регионам (см. get_regions). |
| update_ad_groupA | Изменить группу объявлений без пересоздания: название, регионы показа (полный список, заменяет прежний) и/или UTM-разметку ссылок. Минус-фразы группы — set_ad_group_negative_keywords, наборы — link_negative_keyword_sets, автотаргетинг — update_keywords. |
| delete_ad_groupsA | Удалить группы объявлений по их ID. ⚠️ Необратимо. |
| list_adsA | Объявления: все заголовки и тексты, ссылки, статусы, тип и подтип объявления, привязанные сайтлинки, изображения и видео. Текстовые объявления Директ отдаёт комбинаторными (RESPONSIVE_AD). Причина отказа модерации приходит в StatusClarification. Отбор по ID объявлений, группам или кампаниям — хотя бы одно из трёх; сужается состоянием, статусом и типом. Без фильтра по состоянию архивные приходят наравне с активными. Список может быть неполным: объявления, тексты которых генерирует нейросеть Яндекса, через API недоступны и в выдачу не попадают, а по ответу это никак не видно. Поэтому «в группе только эти объявления» из ответа не следует — ни из пустого, ни из непустого; для полноты картины сверяйтесь с интерфейсом Директа. |
| create_responsive_adA | Создать комбинаторное объявление: от 1 до 7 заголовков (≤56 символов), от 1 до 3 текстов (≤81) и ссылка; варианты показа Директ собирает из них сам. Текстовые объявления через API больше не создаются — Директ заводит их комбинаторными. В группе — не больше 3 неархивных комбинаторных объявлений. |
| update_responsive_adA | Обновить комбинаторное объявление: заголовки, тексты, ссылка. Набор заголовков или текстов заменяется целиком — передайте полный, вместе с теми, что не меняются; текущие показывает list_ads. Изменённое объявление уходит на модерацию. |
| manage_adsB | Действие над объявлениями: suspend/resume/archive/unarchive/moderate/delete. ⚠️ delete необратимо. |
| moderate_adsC | Отправить выбранные объявления на модерацию. |
| list_keywordsA | Ключевые фразы в группах объявлений: фразы, ставки (руб), статусы. По умолчанию возвращается узкий набор полей; нужны другие (StatisticsSearch, StatisticsNetwork, Productivity, ServingStatus и прочие из KeywordFieldEnum) — перечислите их в fields. Автотаргетинг — спецфраза ---autotargeting в той же группе; его категории запросов — с autotargeting: true. |
| add_keywordsC | Добавить ключевые фразы в группу объявлений. |
| update_keywordsA | Изменить текст ключевых фраз, подстановочные переменные {param1}/{param2} и настройки автотаргетинга. Правка текста может привести к появлению фразы с новым ID или к её удалению как дубликата — сверьтесь с list_keywords после вызова. Автотаргетинг — фраза ---autotargeting: её ID берётся из list_keywords, категории запросов и брендов задаются autotargeting_categories / autotargeting_brand_options. Выключить автотаргетинг целиком — manage_keywords с suspend (delete Директ отбивает). Ставки меняет set_keyword_bids, статус — manage_keywords. |
| manage_keywordsB | Действие над ключевыми фразами: suspend/resume/delete. ⚠️ delete необратимо. |
| set_keyword_bidsA | Установить фиксированные ставки (поиск/сети, в рублях) на уровне фраз, групп или кампаний и включить или выключить автоставку автотаргетинга. Ставки применяются только при ручной стратегии: на автостратегии их назначает Директ, и ставка, не подходящая стратегии, не применится. Сначала get_strategy, затем get_keyword_auction — сколько стоит нужный объём трафика; ставку под объём ставит set_auto_keyword_bids. |
| set_auto_keyword_bidsA | Назначить ставки по правилу вместо суммы: на поиске — под желаемый объём трафика (5–100%), в сетях — под долю аудитории, с надбавкой в процентах и потолком в рублях. Директ рассчитает ставку по текущим торгам один раз, следить за ними дальше не будет; назначенные ставки покажет get_keyword_auction. Только при ручной стратегии на соответствующей площадке — иначе Директ отклонит вызов. Отдельному автотаргетингу правило не задаётся: используйте ad_group_ids или campaign_ids. |
| get_keyword_auctionA | Сколько стоит трафик по фразам: текущие ставки и торги на поиске и в сетях. Всё в рублях. На поиске Search.AuctionBids — для каждого объёма трафика фразы TrafficVolume Bid — сколько поставить и Price — сколько спишется за клик. Объём трафика — индекс кликабельности места показа: 100 — первое место премиум-показов, следующие места — 85, 75, 65; выше 100 — места кликабельнее первого, например показ в расширенном формате. В сетях Network.Coverage — ставка под долю аудитории (Probability, %). Отбор по одному уровню: фразы, группы или кампании. Торги видны при любой стратегии, но ставкой управляются только при ручной: на автостратегии (WB_*, AVERAGE_CPA, AVERAGE_CPC и прочие) ставки назначает Директ. Стратегию кампании проверяйте через get_strategy. |
| get_keyword_forecastA | Прогноз трафика и цены клика по списку фраз без кампании — для подбора семантики. Отдаёт таблицу TSV, строка на фразу: Shows — показы за прошедший месяц; Clicks, CTR — нижний блок без первого места; FirstPlaceClicks, FirstPlaceCTR — первое место; PremiumClicks, PremiumCTR — спецразмещение; Min и Max — цена клика за вход в нижний блок и за первое место в нём; PremiumMin и PremiumMax — то же в спецразмещении. С auction_bids — колонки «P<блок><место> Bid» (ставка за позицию) и «… Price» (списываемая цена): P11–P14 — спецразмещение, P21–P24 — нижний блок. Строка «Итого» — суммы по всем фразам, где Min/Max/PremiumMin уже бюджет за месяц, а не цена клика. Деньги — в валюте из currency. Ждёт готовности отчёта до 90 секунд. |
| get_campaign_negative_keywordsC | Получить текущие минус-фразы кампаний по их ID. |
| set_campaign_negative_keywordsA | Минус-фразы на уровне кампании. Режим mode обязателен: replace заменяет список целиком (прежние фразы теряются, пустой массив очищает), add дописывает к текущим, remove убирает названные — читать список перед этим не нужно, add и remove делают это сами. Чтобы добавить фразу к существующим, нужен add: replace с одной фразой сотрёт остальные. |
| set_ad_group_negative_keywordsA | Минус-фразы на уровне группы объявлений. Режим mode обязателен: replace заменяет список целиком (прежние фразы теряются, пустой массив очищает), add дописывает к текущим, remove убирает названные — читать список перед этим не нужно, add и remove делают это сами. Чтобы добавить фразу к существующим, нужен add: replace с одной фразой сотрёт остальные. |
| list_negative_keyword_shared_setsC | Получить общие наборы минус-фраз аккаунта. |
| manage_negative_keyword_shared_setsC | Создать, изменить или удалить общие наборы минус-фраз аккаунта. |
| link_negative_keyword_setsA | Заменить привязки общих наборов минус-фраз у кампаний и/или групп объявлений. Привязка к кампании действует на все её группы. Пустой set_ids очищает привязки. |
| set_campaign_excluded_sitesA | Площадки РСЯ и приложения, на которых кампания не показывается (до 1000). Режим mode обязателен: replace заменяет список целиком (прежние площадки теряются, пустой массив очищает), add дописывает к текущим, remove убирает названные — читать список перед этим не нужно, add и remove делают это сами. Текущий список есть в get_campaign. Чтобы добавить площадку к существующим, нужен add: replace с одной площадкой сотрёт остальные. |
| set_campaign_blocked_ipsA | IP-адреса, которым кампания не показывается (до 25, одиночные публичные IPv4). Режим mode обязателен: replace заменяет список целиком (прежние адреса теряются, пустой массив очищает), add дописывает к текущим, remove убирает названные — add и remove читают текущий список сами. Текущий список есть в get_campaign. |
| list_sitelinksC | Получить все или выбранные наборы быстрых ссылок. |
| set_sitelinksB | Создать новый набор из 1–8 быстрых ссылок. Возвращает ID набора для привязки к объявлению. |
| delete_sitelinksA | Удалить наборы быстрых ссылок по ID. Набор, привязанный к объявлению, Директ удалить не даст. |
| list_ad_extensionsB | Получить уточнения (callouts) с их статусами и текстом. |
| add_ad_extensionsC | Создать уточнения (callouts), каждый текст до 25 символов. |
| delete_ad_extensionsC | Удалить уточнения по ID. ⚠️ Необратимо. |
| manage_ad_imagesB | Загрузить, получить или удалить изображения объявлений (AdImages). Для add данные передаются в base64. |
| list_vcardsA | Получить виртуальные визитки по ID или найти их через объявления выбранных кампаний. Создавать визитки Директ через API не даёт — новая визитка заводится в интерфейсе Директа. |
| delete_vcardsA | Удалить визитки по ID; удаление необратимо. Отказ по отдельной визитке приходит строкой ❌ в ответе, остальные при этом удалены. |
| list_audience_targetsC | Получить условия нацеливания на аудиторию по ID кампании, группы, ретаргетинга или интереса. |
| set_audience_targetsC | Добавить, остановить, возобновить, удалить аудиторные цели или изменить их ставки. |
| list_dynamic_targetsC | Получить условия нацеливания динамических текстовых объявлений. |
| manage_dynamic_targetsC | Создать, изменить ставки, остановить, возобновить или удалить динамические цели. |
| list_retargeting_listsB | Получить условия ретаргетинга и подбора аудитории с правилами и областью применения. |
| add_retargeting_listC | Создать условие ретаргетинга из целей Метрики, сегментов или интересов. |
| update_retargeting_listsA | Изменить название, описание и правила условий ретаргетинга. Переданные правила заменяют прежние целиком: сначала прочитайте условие через list_retargeting_lists. |
| delete_retargeting_listsA | Удалить условия ретаргетинга и подбора аудитории по ID; удаление необратимо. Отказ по отдельному условию приходит строкой ❌ в ответе, остальные при этом удалены. |
| get_bid_adjustmentsA | Получить корректировки ставок кампании или группы: устройства, пол и возраст, аудитории, регионы, платёжеспособность, размещение. |
| add_bid_adjustmentsB | Создать корректировки ставок на кампаниях или группах. Коэффициент — проценты от ставки: 100 ничего не меняет, 0 отключает показы среза. |
| set_bid_adjustmentsB | Изменить коэффициенты существующих корректировок по их ID. |
| delete_bid_adjustmentsA | Удалить корректировки по их ID. Ставка среза возвращается к базовой; отменить удаление нельзя. |
| get_statisticsB | Статистика за период по кампаниям, группам, объявлениям, условиям показа или аккаунту: показы, клики, расход (руб), CTR, CPC; с goals — конверсии и CPA по целям Метрики (ReportService, TSV). |
| get_search_queriesB | Отчёт по фактическим поисковым запросам для анализа и добавления минус-фраз. |
| get_account_balanceB | Баланс и финансовая информация аккаунта (Amount, Currency) через Live API v4. |
| list_businessesB | Получить доступные профили организаций из Яндекс Бизнеса. |
| get_changesB | Проверить изменения кампаний, групп и объявлений начиная с указанного времени, а также изменения справочников (mode=dictionaries) и текущее время сервера Директа. |
| list_feedsB | Получить товарные фиды, их источники, статусы обработки и связанные кампании. |
| get_regionsB | Справочник кодов регионов (GeoRegions) для таргетинга. Фильтр по названию, 225 = Россия. with_parents=true показывает вложенность и различает одноимённые города. |
| list_time_zonesB | Справочник часовых поясов (TimeZones) для set_time_targeting и create_campaign. Фильтр по коду или названию. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 68 tools
Many tools target distinct resources and actions, but there is real overlap: update_campaign also handles SUSPEND/RESUME/ARCHIVE while manage_campaigns covers launch/stop/archive/unarchive/delete; manage_ads includes moderate while moderate_ads exists separately; keyword bidding is split across update_keywords, manage_keywords, set_keyword_bids, and set_auto_keyword_bids. The long descriptions usually clarify scope, but at 68 tools the boundaries require careful reading.
All names are snake_case and mostly follow verb_noun, but conventions vary: list_campaigns is plural while get_campaign is singular, create_ad_group is singular while list_ad_groups/delete_ad_groups are plural, set_sitelinks actually creates a new set, and login/auth tools use start/finish/logout/auth_status. The set is still readable, but it is not a consistently predictable pattern.
68 tools is far above the well-scoped 3-15 range and creates a very heavy selection surface for an agent. Yandex Direct is a broad domain, but this is an extreme tool count and should be split or consolidated.
Coverage is broad across campaigns, ad groups, ads, keywords, bids, strategies, targeting, negative keywords, sitelinks, vcards, images, audience/retargeting, bid adjustments, statistics, references, and authentication. Some gaps remain, such as update_ad_extensions, vcard creation that the API disallows, and limited creation support for some campaign types, but most core workflows are represented.