All servers / Marketing / Yandex Direct MCP server
Yandex Direct MCP server
MCP server for the Yandex Direct API v5 — manage PPC campaigns, ad groups, ads, keywords and pull statistics from AI agents.
Tested by ConnectATDScore 86 out of 100. Tested 2026-11-19 on package version 1.14.0. Package: mcp-yandex-direct · source
Score breakdown
| Runs | 18 / 20 | |
|---|---|---|
| Tool descriptions | 20 / 20 | |
| Package safety | 20 / 20 | |
| Maintenance | 20 / 20 | |
| Adoption | 8 / 20 |
What we saw
- Starts and answers the MCP handshake: yes (2.8 seconds including download)
- Tools offered: 46
- Last published: 2026-11-12
- Weekly downloads (npm): 628
- License: MIT · Direct dependencies: 2
Want this server set up for your team?
ConnectATD builds AI automation and wires up MCP servers like this one. Tell us what you are trying to do.
Talk to ConnectATDTools and how they are described
Agents choose tools from these descriptions. Under each name you can see how many of its parameters are explained.
auth_statusno parametersПоказывает, подключён ли Яндекс Директ: есть ли токен, откуда он взят (переменная окружения YANDEX_DIRECT_TOKEN или сохранённый вход), когда истекает и где лежит файл с сохранёнными данными. Ничего не отправляет в сеть и не показывает сам токен. Вызовите это, если инструменты Директа отвечают, что подключение не настроено.
start_loginno parametersПервый шаг подключения Яндекс Директа без правки конфигурации и без перезапуска клиента. Возвращает ссылку на страницу Яндекс OAuth. Покажите ссылку пользователю целиком и попросите: открыть её в браузере под аккаунтом, у которого есть доступ к нужному рекламному кабинету, подтвердить доступ и прислать показанный код подтверждения. Полученный код передайте в finish_login. Код действует 10 минут. Сам по себе код бесполезен для постороннего: обменять его может только этот сервер.
finish_login1 of 1 parameter describedВторой шаг подключения: обменивает код подтверждения из start_login на токен доступа, сохраняет его в файл только для владельца (0600) и сразу проверяет живым запросом к Директу. После успеха остальные инструменты работают немедленно — перезапускать клиент не нужно. Код одноразовый и живёт 10 минут: если он не принят, вызовите start_login заново и попросите свежий.
logoutno parametersУдаляет сохранённый токен Директа с диска. Токен, заданный переменной окружения YANDEX_DIRECT_TOKEN, не трогает — его нужно убирать из конфигурации клиента вручную. Доступ, выданный приложению, остаётся активным на стороне Яндекса: отозвать его можно в Яндекс ID.
get_account_info2 of 2 parameters describedВозвращает данные текущего аккаунта рекламодателя (логин, валюта, тип, страна) через сервис `clients` Яндекс Директа.
get_balance2 of 2 parameters describedВозвращает баланс общего счёта и финансовые поля (Amount, AmountAvailableForTransfer, Currency, Discount, AccountID) через устаревший сервис AccountManagement Live v4 — единственный API Яндекс Директа, который отдаёт баланс (в v5 финансового метода нет). Amount — строка в ВАЛЮТЕ АККАУНТА (не в микроединицах); отрицательный Amount означает задолженность. По умолчанию — собственный аккаунт токена, а при переданном client_login — счёт этого клиента; чтобы получить несколько общих счетов разом (агентство, до 50 логинов), передать logins.
get_quota1 of 1 parameter describedВозвращает сегодняшнюю квоту баллов API (потрачено / осталось / лимит) из заголовка Units — чтобы не упереться в дневной лимит.
list_clients3 of 3 parameters describedПеречисляет рекламодателей, с которыми может работать токен: клиентов агентства (AgencyClients.get) и кабинеты в управлении из YANDEX_DIRECT_CLIENTS. Логин из ответа передаётся в параметр client_login любого инструмента данных — так один сервер работает со всеми клиентами без перезапуска. accountType=agency — токен агентства: без client_login (и без YANDEX_DIRECT_LOGIN) инструменты видят собственный аккаунт агентства, где обычно нет кампаний. accountType=advertiser — обычный аккаунт: API не перечисляет кабинеты, где этот логин представитель, поэтому список есть только если его задали в YANDEX_DIRECT_CLIENTS. Архивные клиенты агентства по умолчанию скрыты. Сводка по всем клиентам сразу (баланс, кампании) — clients_overview.
clients_overview4 of 4 parameters describedСводка по всем клиентам агентства и кабинетам в управлении за один вызов — для вопросов вроде «что у меня по аккаунтам в управлении»: по каждому клиенту баланс общего счёта и число кампаний по состояниям (on — идут или могут идти, suspended — остановлены пользователем, off — не идут по другой причине, ended) и статусам модерации (moderation, rejected, draft). Архивные кампании не считаются. Клиенты — из list_clients, либо явный список logins. Ошибка по одному клиенту (нет доступа, нет общего счёта) не прерывает остальных и попадает в его строку. С параметром stats добавляет показы, клики и расход (с НДС, в валюте клиента) за период — по одному отчёту Reports на клиента, строго по очереди: Яндекс пускает примерно один отчёт в 10 секунд, так что 30 клиентов — около 5 минут; клиенты без неархивных кампаний не запрашиваются, а кто не уложился в 5 минут, помечается statsSkipped. Без stats ответ приходит за секунды — запрашивать расход, только когда вопрос про деньги или трафик. Не вызывать list_campaigns по каждому клиенту в цикле — эта сводка дешевле. Тратит баллы API каждого клиента: один запрос кампаний на клиента и один запрос баланса на 50 клиентов у агентства (у обычного аккаунта — на каждого). Кампании клиентов читаются через API v501, в песочнице — через v5.
list_campaigns10 of 10 parameters describedВозвращает список кампаний с необязательными фильтрами по id, типу, состоянию и статусу. Запрос идёт в API v501 (в песочнице — в v5): только он отдаёт Единую перформанс-кампанию с типом UNIFIED_CAMPAIGN (v5 называет её TEXT_CAMPAIGN; ответ v5 доступен через raw_request с apiVersion "v5"). Денежные поля (Funds общего счёта — Sum, Balance, SumAvailableForTransfer, Spend) отдаются в валюте аккаунта. Бюджет кампании — недельный (WeeklySpendLimit) и у ручных ставок, и у автостратегий; он лежит внутри BiddingStrategy и виден только при strategy: true (дневного бюджета DailyBudget у API больше нет). strategy: true добавляет блок TextCampaign/UnifiedCampaign со стратегией (BiddingStrategy), ключевыми целями (PriorityGoals), счётчиками Метрики, моделью атрибуции, пакетной стратегией и переносом бюджета (WeeklyBudgetRollover — сколько добавлено к недельному бюджету за счёт неиспользованного на прошлой неделе, до 30%; null — перенос не применяется или данных нет) — деньги в нём тоже в валюте аккаунта, а сам объект BiddingStrategy в этом виде принимает set_campaign_strategy.
create_text_campaign8 of 8 parameters describedСоздаёт кампанию TextCampaign (текстово-графические объявления). Без biddingStrategy применяются ручные ставки на поиске с отключёнными сетями (Search HIGHEST_POSITION, Network SERVING_OFF) — у ручных ставок текстовой кампании бюджета в API нет. Чтобы ограничить расход, включить автостратегию или сети, передать biddingStrategy целиком — {Search, Network}, недельный бюджет внутри него (WeeklySpendLimit в структуре параметров автостратегии). Дневного бюджета у Директа больше нет. Запрос идёт в API v501, в песочнице — в v5.
campaign_action2 of 3 parameters describedВыполняет действие над кампаниями по id: suspend, resume, archive, unarchive или delete. Запрос идёт в API v501, в песочнице — в v5.
update_campaign7 of 7 parameters describedОбновляет название, дату окончания и/или минус-фразы кампании (campaigns/update). Бюджет здесь не меняется: у Директа он недельный и является частью стратегии — set_campaign_strategy (WeeklySpendLimit в структуре параметров автостратегии; у ручных ставок — HighestPosition: {WeeklySpendLimit}, только у ЕПК). Запрос идёт в API v501, в песочнице — в v5.
list_ad_groups7 of 7 parameters describedВозвращает список групп объявлений. Нужно передать campaignIds и/или ids — API Яндекс Директа требует хотя бы один критерий отбора. Запрос идёт в API v501 (в песочнице — в v5): группы Единой перформанс-кампании приходят с Type UNIFIED_AD_GROUP (v5 называет их TEXT_AD_GROUP; ответ v5 доступен через raw_request с apiVersion "v5").
create_ad_group4 of 4 parameters describedСоздаёт группу объявлений в кампании с заданными регионами показа. Запрос идёт в API v501, в песочнице — в v5.
update_ad_group5 of 5 parameters describedОбновляет название и/или регионы показа группы объявлений (adgroups/update). Запрос идёт в API v501, в песочнице — в v5.
delete_ad_groups2 of 2 parameters describedУдаляет группы объявлений по id (adgroups/delete). Вместе с группой удаляются её объявления и ключевые фразы; отменить это нельзя. Запрос идёт в API v501, в песочнице — в v5.
list_ads11 of 11 parameters describedВозвращает список объявлений. Нужно передать campaignIds, adGroupIds или ids — API Яндекс Директа требует хотя бы один из них; states и statuses только сужают выборку. Текстовые объявления Единой перформанс-кампании Директ хранит комбинаторными и отдаёт в одном из двух видов. Без responsiveAdFieldNames — в виде совместимости: Type TEXT_AD, запрошенные тексты в объекте TextAd. Если передано хотя бы одно поле в responsiveAdFieldNames — как Type RESPONSIVE_AD с объектом ResponsiveAd вместо TextAd, где заголовки и тексты — массивы Titles[] и Texts[] со статусом модерации каждого варианта.
create_text_ad7 of 7 parameters describedСоздаёт текстовое объявление (TextAd) в группе объявлений. Новые объявления создаются черновиками. TextAdAdd требует хотя бы одно из Href/TurboPageId/BusinessId — этот инструмент передаёт посадочную страницу через href (обязателен); объявление с BusinessId вместо ссылки создаётся через raw_request. Визитки (VCardId) Директ больше не поддерживает: контакты задаются организацией из Яндекс Бизнеса (BusinessId). Директ создаёт такие объявления комбинаторными (тип RESPONSIVE_AD), а Title2 объединяет с Title через «. », если вместе они короче 56 символов, иначе отбрасывает; о таких изменениях API сообщает предупреждениями.
ad_action2 of 3 parameters describedВыполняет действие над объявлениями по id: moderate, suspend, resume, archive, unarchive или delete.
update_text_ad6 of 6 parameters describedОбновляет заголовок, текст или посадочную страницу текстового объявления (ads/update). Правка активного объявления отправляет его на повторную модерацию.
list_keywords8 of 8 parameters describedВозвращает список ключевых фраз. Нужно передать campaignIds, adGroupIds или ids — API Яндекс Директа требует хотя бы один из них. Bid и ContextBid отдаются в валюте аккаунта.
add_keywords3 of 3 parameters describedДобавляет ключевые фразы в группу объявлений, при необходимости — со ставками для поиска и сетей.
keyword_action2 of 3 parameters describedВыполняет действие над ключевыми фразами по id: suspend, resume или delete.
set_keyword_bids2 of 2 parameters describedЗадаёт ручные ставки на поиске и в сетях для ключевых фраз либо для всех фраз указанных групп объявлений или кампаний (keywordbids/set). Ставки — в валюте аккаунта. Тип цели один на весь вызов: все элементы bids используют только keywordId, только adGroupId или только campaignId; для целей разных типов нужны отдельные вызовы.
update_negative_keywords5 of 5 parameters describedМеняет минус-фразы одной кампании или одной группы объявлений. API хранит список целиком и при записи заменяет его, поэтому действие задаётся явно: - add — дописать фразы к текущим. Инструмент читает текущий список (campaigns/get или adgroups/get) и записывает объединённый (update): два вызова API. Уже имеющиеся фразы не дублируются. - remove — убрать указанные фразы из текущего списка. Тоже чтение + запись. - replace — записать ровно переданный список вместо текущего, без чтения. Пустой список здесь не принимается — для очистки есть clear. - clear — удалить все минус-фразы (отправляется null). Фразы сравниваются без учёта регистра и лишних пробелов — так же склеивает их сам API; морфологию и порядок слов инструмент не учитывает. Если add/remove ничего не меняют, записи нет (changed: false). Ответ: before/after — число фраз до и после, added/alreadyPresent или removed/notFound — что именно произошло. Между чтением и записью нет блокировки: правка того же списка в интерфейсе в эту секунду будет перезаписана. Ограничения API: фраза без минуса в начале, до 7 слов, слово до 35 символов; суммарно до 20 000 символов на кампанию и 4096 на группу — нарушения API вернёт ошибкой по объекту. Минус-фразы кампании и группы действуют вместе. Запрос идёт в API v501, в песочнице — в v5.
update_excluded_sites4 of 4 parameters describedМеняет список площадок, где кампании запрещено показываться (ExcludedSites): сайты, мобильные приложения и внешние сети РСЯ. Действует только в сетях, на поиске площадки не запрещаются. API хранит список целиком и при записи заменяет его, поэтому действие задаётся явно: - add — дописать площадки к текущим. Инструмент читает текущий список (campaigns/get) и записывает объединённый (campaigns/update): два вызова API. Уже исключённые не дублируются. - remove — вернуть показы на указанных площадках. Тоже чтение + запись. - replace — записать ровно переданный список вместо текущего, без чтения. Пустой список здесь не принимается — для очистки есть clear. - clear — снять все запреты (отправляется null). Значения: домен без протокола (example.com — API сам уберёт www. и приведёт к нижнему регистру), id приложения Android/iOS в виде com.example.app (числовой id App Store вида id123456789 API отвергает), название внешней сети из get_dictionaries → SupplySidePlatforms (например BidSwitch). Значение площадки из отчёта get_statistics (поле Placement, строки с AdNetworkType=AD_NETWORK) передаётся как есть. Если add/remove ничего не меняют, записи нет (changed: false). Ответ: before/after — число площадок до и после, added/alreadyPresent или removed/notFound. Между чтением и записью нет блокировки: правка того же списка в интерфейсе в эту секунду будет перезаписана. Лимиты API: до 1000 площадок, до 255 символов в каждой. Текущий список — list_campaigns с fieldNames ["ExcludedSites"]. Запрос идёт в API v501, в песочнице — в v5.
set_campaign_strategy4 of 4 parameters describedМеняет стратегию показа (BiddingStrategy) текстовой кампании или ЕПК. Формат — объект API как есть, в том же виде, в каком его отдаёт list_campaigns с strategy: true, поэтому порядок такой: прочитать текущую стратегию, показать её пользователю, скопировать и поправить нужное поле. Сервер делает только три вещи: (1) одним campaigns.get узнаёт тип кампании и кладёт стратегию в TextCampaign или UnifiedCampaign; (2) переводит деньги из валюты аккаунта в микроединицы — WeeklySpendLimit, BidCeiling, AverageCpc, AverageCpa, Cpa, SpendLimit, MinimumExplorationBudget (Crr и BudgetIncreasePercent — проценты, не деньги); (3) возвращает previous — стратегию до изменения — рядом с UpdateResults. Больше ничего не дописывается и не проверяется: правила совместимости проверяет API и отвечает ошибкой по объекту. Бюджет кампании — недельный и задаётся только здесь: у автостратегий — WeeklySpendLimit в их структуре параметров, у ручных ставок ЕПК — {BiddingStrategyType: HIGHEST_POSITION, HighestPosition: {WeeklySpendLimit}}; у ручных ставок текстовой кампании бюджета нет (API отвечает 8000 на HighestPosition). Дневного бюджета (DailyBudget) у Директа больше нет. Передаются обе стороны, search и network. Внутри структуры параметров непереданные поля той же стратегии сохраняют текущие значения (проверено вживую на ЕПК). PriorityGoals, CounterIds и AttributionModel этим инструментом не меняются (raw_request). Правила API: автостратегия на поиске ⇒ в сетях только NETWORK_DEFAULT или SERVING_OFF; автостратегия в сетях ⇒ на поиске SERVING_OFF. Конверсионные стратегии требуют GoalId цели Метрики и счётчик на кампании; стратегии *_MULTIPLE_GOALS берут цели из PriorityGoals. Минимумы бюджета и ставок — get_dictionaries → Currencies. Смена типа стратегии перезапускает её обучение. Кампании других типов и кампании в пакетной стратегии — через raw_request. Запрос идёт в API v501, в песочнице — в v5.
get_statistics19 of 19 parameters describedЗапрашивает отчёт по эффективности через сервис Reports Яндекс Директа. По умолчанию отчёт АГРЕГИРОВАН за весь период (одна строка на объект) — добавлять "Date" в fieldNames только для динамики по дням или вопросов о трендах. Почасовой статистики в Reports нет: минимум — сутки, внутридневную динамику дают только повторные снимки TODAY. Готового ROAS нет — считать Revenue / Cost; GoalsRoi — это ROI ((Revenue − Cost) / Cost), не ROAS. Revenue, Profit, GoalsRoi и конверсии заполняются только по целям Метрики с ценностью. ALL_TIME без фильтра по кампаниям отклоняется для отчётов SEARCH_QUERY/CRITERIA: нужно передать campaignIds или ограниченный период. SEARCH_QUERY_PERFORMANCE_REPORT возвращает не сырые строки, а ВЫЧИСЛЕННУЮ СВОДКУ (итоги по ВСЕМ строкам + детализация top-N + свёртка хвоста + количество строк без кликов и без конверсий); её форму задают sortBy/topN/minCost/queryContains/zeroClicksOnly/zeroConversionsOnly, а для подсчётов по конверсиям нужно добавить Conversions в fieldNames. Остальные типы отчётов возвращают строки, разделённые табуляцией (без заголовка). compareTo — сравнение двух периодов: инструмент запускает ДВЕ задачи Reports (текущий период dateFrom/dateTo и compareTo) и возвращает JSON, где строки сопоставлены по разрезам отчёта (matchKey; название кампании или группы не учитывается, если запрошен её id — переименование не ломает сопоставление), с current, previous, delta и deltaPct по каждой метрике. Это только значения Яндекса и их разность: вклад факторов (расход = показы × CTR × CPC) инструмент не считает — при объяснении изменений считать по колонкам ответа и называть порядок факторов. Последние ~3 дня статистики Яндекс может пересчитать.
get_regions3 of 3 parameters describedИщет id регионов для таргетинга (те самые regionIds, которые нужны create_ad_group). Фильтр — подстрока названия; количество результатов ограничено limit.
get_dictionaries2 of 2 parameters describedВозвращает справочники Яндекс Директа (валюты, часовые пояса, константы, категории объявлений, …). GeoRegions может быть очень большим — для поиска регионов лучше get_regions.
raw_request6 of 6 parameters describedУниверсальный запрос: вызывает напрямую любой сервис или метод API Яндекс Директа (например service "bidmodifiers", method "get"). Нужен для сервисов, у которых нет отдельного инструмента. Деньги — в микроединицах (без конвертации). Методы чтения (get/has/check) выполняются свободно; любой другой метод считается записью и требует confirmWrite=true. Версия API по умолчанию — v5, а для сервисов campaigns и adgroups — v501: только она называет Единую перформанс-кампанию и её группы настоящими типами (UNIFIED_CAMPAIGN, UNIFIED_AD_GROUP) и фильтрует по ним, v5 выдаёт их за TEXT_CAMPAIGN и TEXT_AD_GROUP. Параметр apiVersion задаёт версию явно для любого сервиса.
get_bid_modifiers6 of 6 parameters describedЧитает корректировки ставок (мобильные, десктоп, демография, ретаргетинг, регионы, видео) для кампаний или групп объявлений. BidModifier — это процент, а не деньги.
add_bid_modifier8 of 8 parameters describedДобавляет корректировку ставок на кампанию или группу объявлений. Значения BidModifier — проценты по правилам API (например, 0–1300), а не деньги. API принимает в одном элементе BidModifiers только один тип корректировки, поэтому каждый переданный тип (mobile, desktop, demographics, retargeting, regional) уходит отдельным элементом в одном вызове bidmodifiers/add, в этом порядке. Каждая запись AddResults помечена полем Type (MOBILE_ADJUSTMENT, DESKTOP_ADJUSTMENT, DEMOGRAPHICS_ADJUSTMENT, RETARGETING_ADJUSTMENT, REGIONAL_ADJUSTMENT): типы создаются независимо, при частичной ошибке повторять только типы с Errors. Внутри одного типа (массивы demographics/retargeting/regional) API создаёт всё или ничего.
set_bid_modifiers2 of 2 parameters describedМеняет процент существующих корректировок (bidmodifiers/set) по id корректировки. BidModifierSetItem принимает только Id и BidModifier; включить/выключить корректировку через API нельзя (метод bidmodifiers/toggle устарел и не поддерживается) — чтобы отключить корректировку, удалить её через delete_bid_modifiers.
delete_bid_modifiers2 of 2 parameters describedУдаляет корректировки ставок по id (bidmodifiers/delete).
get_sitelinks4 of 4 parameters describedЧитает наборы быстрых ссылок по id. API требует id наборов — их можно взять из поля SitelinkSetId объявлений.
create_sitelinks_set2 of 2 parameters describedСоздаёт набор быстрых ссылок (1–8 штук). Лимиты API: текст ссылки до 30 символов, описание до 60, URL до 1024 (с протоколом и доменом); длиннее API отвечает «Превышена допустимая длина», поэтому сокращать заранее. Наборы неизменяемы — чтобы поменять ссылки, нужно создать новый набор и переназначить его объявлению.
delete_sitelinks2 of 2 parameters describedУдаляет наборы быстрых ссылок по id (удалить можно только наборы, не привязанные ни к одному объявлению).
get_callouts4 of 4 parameters describedВозвращает список уточнений из библиотеки adextensions. Привязать уточнение к объявлению можно через сервис Ads.
add_callouts2 of 2 parameters describedСоздаёт уточнения, до 25 символов каждое, не более 1000 за вызов. Уточнения неизменяемы — чтобы поменять, нужно удалить и создать заново. Привязка к объявлениям — через сервис Ads.
delete_callouts2 of 2 parameters describedУдаляет уточнения по id (adextensions/delete).
get_ad_images4 of 4 parameters describedВозвращает список изображений из библиотеки изображений, ключ — хеш изображения. Новые изображения загружает upload_ad_image.
get_ad_videos4 of 4 parameters describedЧитает видео из библиотеки видео по id (API требует id). Загрузка идёт через raw_request (advideos/add).
get_creatives4 of 4 parameters describedВозвращает список креативов (смарт-баннеры, HTML5) из библиотеки креативов.
upload_ad_image4 of 4 parameters describedЗагружает изображение в библиотеку изображений (adimages/add) и возвращает его AdImageHash — этот хеш подставляется в поле AdImageHash текстово-графического объявления. Изображение передаётся публичным URL (сервер сам скачает и закодирует) или в base64 через imageData. Яндекс принимает JPG/PNG/GIF до 10 МБ; текстово-графическому объявлению нужна горизонтальная картинка (минимум 1080×607).
Tested in a sandbox with an empty environment: no API keys, a throwaway folder, nothing from a real account. A passing test shows the server runs and responds. It is not a security audit.