Yandex Direct MCP

Выполняет действие над объявлениями по id: moderate, suspend, resume, archive, unarchive или delete.

Добавляет корректировку ставок на кампанию или группу объявлений. Значения 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 создаёт всё или ничего.

Создаёт уточнения, до 25 символов каждое, не более 1000 за вызов. Уточнения неизменяемы — чтобы поменять, нужно удалить и создать заново. Привязка к объявлениям — через сервис Ads.

Добавляет ключевые фразы в группу объявлений, при необходимости — со ставками для поиска и сетей.

Показывает, подключён ли Яндекс Директ: есть ли токен, откуда он взят (переменная окружения YANDEX_DIRECT_TOKEN или сохранённый вход), когда истекает и где лежит файл с сохранёнными данными. Ничего не отправляет в сеть и не показывает сам токен. Вызовите это, если инструменты Директа отвечают, что подключение не настроено.

Выполняет действие над кампаниями по id: suspend, resume, archive, unarchive или delete.

Сводка по всем клиентам агентства и кабинетам в управлении за один вызов — для вопросов вроде «что у меня по аккаунтам в управлении»: по каждому клиенту баланс общего счёта и число кампаний по состояниям (on — идут или могут идти, suspended — остановлены пользователем, off — не идут по другой причине, ended) и статусам модерации (moderation, rejected, draft). Архивные кампании не считаются. Клиенты — из list_clients, либо явный список logins. Ошибка по одному клиенту (нет доступа, нет общего счёта) не прерывает остальных и попадает в его строку. С параметром stats добавляет показы, клики и расход (с НДС, в валюте клиента) за период — по одному отчёту Reports на клиента, строго по очереди: Яндекс пускает примерно один отчёт в 10 секунд, так что 30 клиентов — около 5 минут; клиенты без неархивных кампаний не запрашиваются, а кто не уложился в 5 минут, помечается statsSkipped. Без stats ответ приходит за секунды — запрашивать расход, только когда вопрос про деньги или трафик. Не вызывать list_campaigns по каждому клиенту в цикле — эта сводка дешевле. Тратит баллы API каждого клиента: один запрос кампаний на клиента и один запрос баланса на 50 клиентов у агентства (у обычного аккаунта — на каждого).

Создаёт группу объявлений в кампании с заданными регионами показа.

Создаёт набор быстрых ссылок (1–8 штук). Лимиты API: текст ссылки до 30 символов, описание до 60, URL до 1024 (с протоколом и доменом); длиннее API отв��чает «Превышена допустимая длина», поэтому сокращать заранее. Наборы неизменяемы — чтобы поменять ссылки, нужно создать новый набор и переназначить его объявлению.

Создаёт текстовое объявление (TextAd) в группе объявлений. Новые объявления создаются черновиками. TextAdAdd требует хотя бы одно из Href/TurboPageId/BusinessId — этот инструмент передаёт посадочную страницу через href (обязателен); объявление с BusinessId вместо ссылки создаётся через raw_request. Визитки (VCardId) Директ больше не поддерживает: контакты задаются организацией из Яндекс Бизнеса (BusinessId). Директ создаёт такие объявления комбинаторными (тип RESPONSIVE_AD), а Title2 объединяет с Title через «. », если вместе они короче 56 символов, иначе отбрасывает; о таких изменениях API сообщает предупреждениями.

Создаёт кампанию TextCampaign (текстово-графические объявления). Без biddingStrategy применяются ручные ставки на поиске с отключёнными сетями (Search HIGHEST_POSITION, Network SERVING_OFF); чтобы включить автостратегию или сети, передать biddingStrategy целиком — {Search, Network}.

Удаляет группы объявлений по id (adgroups/delete). Вместе с группой удаляются её объявления и ключевые фразы; отменить это нельзя.

Удаляет корректировки ставок по id (bidmodifiers/delete).

Удаляет уточнения по id (adextensions/delete).

Удаляет наборы быстрых ссылок по id (удалить можно только наборы, не привязанные ни к одному объявлению).

Второй шаг подключения: обменивает код подтверждения из start_login на токен доступа, сохраняет его в файл только для владельца (0600) и сразу проверяет живым запросом к Директу. После успеха остальные инструменты работают немедленно — перезапускать клиент не нужно. Код одноразовый и живёт 10 минут: если он не принят, вызовите start_login заново и попросите свежий.

Возвращает данные текущего аккаунта рекламодателя (логин, валюта, тип, страна) через сервис `clients` Яндекс Директа.

Возвращает список изображений из библиотеки изображений, ключ — хеш изображения. Новые изображения загружает upload_ad_image.

Читает видео из библиотеки видео по id (API требует id). Загрузка идёт через raw_request (advideos/add).

Возвращает баланс общего счёта и финансовые поля (Amount, AmountAvailableForTransfer, Currency, Discount, AccountID) через устаревший сервис AccountManagement Live v4 — единственный API Яндекс Директа, который отдаёт баланс (в v5 финансового метода нет). Amount — строка в ВАЛЮТЕ АККАУНТА (не в микроединицах); отрицательный Amount означает задолженность. По умолчанию — собственный аккаунт токена, а при переданном client_login — счёт этого клиента; чтобы получить несколько общих счетов разом (агентство, до 50 логинов), передать logins.

Читает корректировки ставок (мобильные, десктоп, демография, ретаргетинг, регионы, видео) для кампаний или групп объявлений. BidModifier — это процент, а не деньги.

Возвращает список уточнений из библиотеки adextensions. Привязать уточнение к объявлению можно через сервис Ads.

Возвращает список креативов (смарт-баннеры, HTML5) из библиотеки креативов.

Возвращает справочники Яндекс Директа (валюты, часовые пояса, константы, категории объявлений, …). GeoRegions может быть очень большим — для поиска регионов лучше get_regions.

Возвращает сегодняшнюю квоту баллов API (потрачено / осталось / лимит) из заголовка Units — чтобы не упереться в дневной лимит.

Ищет id регионов для таргетинга (те самые regionIds, которые нужны create_ad_group). Фильтр — подстрока названия; количество результатов ограничено limit.

Читает наборы быстрых ссылок по id. API требует id наборов — их можно взять из поля SitelinkSetId объявлений.

Запрашивает отчёт по эффективности через сервис 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 дня статистики Яндекс может пересчитать.

Выполняет действие над ключевыми фразами по id: suspend, resume или delete.

Возвращает список групп объявлений. Нужно передать campaignIds и/или ids — API Яндекс Директа требует хотя бы один критерий отбора.

Возвращает список объявлений. Нужно передать campaignIds, adGroupIds или ids — API Яндекс Директа требует хотя бы один из них; states и statuses только сужают выборку.

Возвращает список кампаний с необязательными фильтрами по id, типу, состоянию и статусу. Денежные поля (DailyBudget.Amount и Funds общего счёта — Sum, Balance, SumAvailableForTransfer, Spend) отдаются в валюте аккаунта. strategy: true добавляет блок TextCampaign/UnifiedCampaign со стратегией (BiddingStrategy), ключевыми целями (PriorityGoals), счётчиками Метрики, моделью атрибуции и пакетной стратегией — деньги в нём тоже в валюте аккаунта, а сам объект BiddingStrategy в этом виде принимает set_campaign_strategy.

Перечисляет рекламодателей, с которыми может работать токен: клиентов агентства (AgencyClients.get) и кабинеты в управлении из YANDEX_DIRECT_CLIENTS. Логин из ответа передаётся в параметр client_login любого инструмента данных — так один сервер работает со всеми клиентами без перезапуска. accountType=agency — токен агентства: без client_login (и без YANDEX_DIRECT_LOGIN) инструменты видят собственный аккаунт агентства, где обычно нет кампаний. accountType=advertiser — обычный аккаунт: API не перечисляет кабинеты, где этот логин представитель, поэтому список есть только если его задали в YANDEX_DIRECT_CLIENTS. Архивные клиенты агентства по умолчанию скрыты. Сводка по всем клиентам сразу (баланс, кампании) — clients_overview.

Возвращает список ключевых фраз. Нужно передать campaignIds, adGroupIds или ids — API Яндекс Директа требует хотя бы один из них. Bid и ContextBid отдаются в валюте аккаунта.

Удаляет сохранённый токен Директа с диска. Токен, заданный переменной окружения YANDEX_DIRECT_TOKEN, не трогает — его нужно убирать из конфигурации клиента вручную. Доступ, выданный приложению, остаётся активным на стороне Яндекса: отозвать его можно в Яндекс ID.

Универсальный запрос: вызывает напрямую любой сервис или метод API Яндекс Директа v5 (например service "bidmodifiers", method "get"). Нужен для сервисов, у которых нет отдельного инструмента. Деньги — в микроединицах (без конвертации). Методы чтения (get/has/check) выполняются свободно; любой другой метод считается записью и требует confirmWrite=true.

Меняет процент существующих корректировок (bidmodifiers/set) по id корректировки. BidModifierSetItem принимает только Id и BidModifier; включить/выключить корректировку через API нельзя (метод bidmodifiers/toggle устарел и не поддерживается) — чтобы отключить корректировку, удалить её через delete_bid_modifiers.

Меняет стратегию показа (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 и отвечает ошибкой по объекту. Передаются обе стороны, search и network. Внутри структуры параметров непереданные поля той же стратегии сохраняют текущие значения (проверено вживую на ЕПК). PriorityGoals, CounterIds и AttributionModel этим инструментом не меняются (raw_request). Правила API: автостратегия на поиске ⇒ в сетях только NETWORK_DEFAULT или SERVING_OFF; автостратегия в сетях ⇒ на поиске SERVING_OFF. Конверсионные стратегии требуют GoalId цели Метрики и счётчик на кампании; стратегии *_MULTIPLE_GOALS берут цели из PriorityGoals. Минимумы бюджета и ставок — get_dictionaries → Currencies. Смена типа стратегии перезапускает её обучение. Кампании других типов и кампании в пакетной стратегии — через raw_request.

Задаёт ручные ставки на поиске и в сетях для ключевых фраз либо для всех фраз указанных групп объявлений или кампаний (keywordbids/set). Ставки — в валюте аккаунта. Тип цели один на весь вызов: все элементы bids используют только keywordId, только adGroupId или только campaignId; для целей разных типов нужны отдельные вызовы.

Первый шаг подключения Яндекс Директа без правки конфигурации и без перезапуска клиента. Возвращает ссылку на страницу Яндекс OAuth. Покажите ссылку пользователю целиком и попросите: открыть её в браузере под аккаунтом, у которого есть доступ к нужному рекламному кабинету, подтвердить доступ и прислать показанный код подтверждения. Полученный код передайте в finish_login. Код действует 10 минут. Сам по себе код бесполезен для постороннего: обменять его может только этот сервер.

Обновляет название и/или регионы показа группы объявлений (adgroups/update).

Обновляет название, дату окончания и/или дневной бюджет кампании (campaigns/update). API требует передавать режим бюджета (Mode) вместе с суммой, поэтому если dailyBudgetMode не задан, текущий режим кампании дочитывается через campaigns/get и сохраняется — смена суммы не меняет темп открутки.

Меняет список площадок, где кампании запрещено показываться (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 хранит список целиком и при записи заменяет его, поэтому действие задаётся явно: - 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 вернёт ошибкой по объекту. Минус-фразы кампании и группы действуют вместе.

Обновляет заголовок, текст или посадочную страницу текстового объявления (ads/update). Правка активного объявления отправляет его на повторную модерацию.

Загружает изображение в библиотеку изображений (adimages/add) и возвращает его AdImageHash — этот хеш подставляется в поле AdImageHash текстово-графического объявления. Изображение передаётся публичным URL (сервер сам скачает и закодирует) или в base64 через imageData. Яндекс принимает JPG/PNG/GIF до 10 МБ; текстово-графическому объявлению нужна горизонтальная картинка (минимум 1080×607).