yandex-direct

Яндекс.Директ — управление через MCP tools

Управление рекламными кампаниями в Яндекс.Директ через MCP-инструменты плагина.

Первое действие — проверь авторизацию

Всегда начинай с auth_status(). Если valid: false:

1. Вызови auth_login() — он покажет ссылку для авторизации и запросит код через форму
2. Пользователю не нужно ничего знать заранее — flow полностью интерактивный
3. После авторизации токен сохраняется на диск, повторный логин не требуется

Не пытайся вызывать другие tools пока авторизация не пройдена — они вернут ошибку.

Доступный MCP-контракт (146 tools)

Контракт теперь следует иерархии:

MCP -> direct (package: direct-cli) -> tapi-yandex-direct -> Yandex.Direct API

• Используй только публичные MCP tools.
• Не опирайся на старые alias-имена (*_list, agency_clients_*, keyword_bids_*, smart_targets_* и т.д.).
• Для Direct-операций используй канонические имена service_method.
• v4 Live методы вызывай только через публичные MCP tools; shell-группы без CLI-команд не используются.

Правила именования

• *_list → *_get: campaigns_get, ads_get, keywords_get
• Имена сервисов совпадают с direct: agencyclients_*, audiencetargets_*, keywordbids_*, smartadtargets_*, dynamicads_*, negativekeywordsharedsets_*, turbopages_get
• CLI методы с дефисом становятся snake_case:
  • changes_check_campaigns
  • changes_check_dictionaries
  • keywordsresearch_has_search_volume
  • bids_set_auto
  • keywordbids_set_auto
  • audiencetargets_set_bids
  • dynamicads_set_bids
  • smartadtargets_set_bids

Direct API tools — основные семейства

Семейство	Канонические tools
Кампании	campaigns_get/add/update/delete/archive/unarchive/suspend/resume
Группы / объявления / ключи	adgroups_get/add/update/delete, ads_get/add/update/delete/moderate/suspend/resume/archive/unarchive, keywords_get/add/update/delete/suspend/resume/archive/unarchive
Ставки	keywordbids_get/set/set_auto, bids_get/set/set_auto, bidmodifiers_get/add/set/delete
Таргетинг	audiencetargets_get/add/delete/suspend/resume/set_bids, retargeting_get/add/update/delete, dynamicads_get/add/delete/suspend/resume/set_bids, dynamicfeedadtargets_get/add/delete/suspend/resume/set_bids, smartadtargets_get/add/update/delete/suspend/resume/set_bids
Стратегии	strategies_get/add/update/archive/unarchive
Медиа и расширения	adimages_get/add/delete, advideos_get/add, adextensions_get/add/delete, sitelinks_get/add/delete, vcards_get/add/delete, creatives_get/add
Справочники / изменения / отчёты	dictionaries_get, dictionaries_get_geo_regions, changes_check, changes_check_campaigns, changes_check_dictionaries, reports_get
v4 Live	balance_get, v4account_get_accounts, v4account_update_account, v4account_deposit, v4account_invoice, v4account_transfer_money, v4account_enable_shared_account, v4events_get_events_log, v4goals_get_stat_goals, v4goals_get_retargeting_goals, v4tags_get_campaigns, v4tags_get_banners, v4tags_update_campaigns, v4tags_update_banners, v4forecast_create, v4forecast_list, v4forecast_get, v4forecast_delete, v4wordstat_create_report, v4wordstat_list_reports, v4wordstat_get_report, v4wordstat_delete_report
Прочее	clients_get/update, agencyclients_get/add/update/add_passport_organization/add_passport_organization_member, businesses_get, feeds_get/add/update/delete, leads_get, negativekeywordsharedsets_get/add/update/delete, keywordsresearch_has_search_volume, keywordsresearch_deduplicate, turbopages_get

Явно helper-only tools

Эти tools публичные, но не являются 1:1 Direct API методами:

• agencyclients_delete
• dictionaries_list_names
• reports_list_types

Plugin-only auth tools

• auth_status
• auth_setup
• auth_login

Отчёты (статистика)

Для статистики есть два инструмента — выбор критичен, не путай.

reports_get — быстрый снимок

Только когда нужна сводка по кампаниям за короткий недавний период без группировок и фильтров. Поля фиксированы (CampaignName, Impressions, Clicks, Cost, Conversions, CostPerConversion, ConversionRate). Параметры только date_from / date_to.

reports_custom — всё остальное (это «отчёт для людей»)

Используй всегда, когда запрос пользователя содержит хотя бы одно из:

• «по дням / неделям / месяцам / кварталам / годам» → дименшн Date / Week / Month / Quarter / Year в field_names
• «по целям X, Y» / «конверсии по регистрациям» / «подписки» → goal_ids="<id1>,<id2>" + добавь Goals,Conversions в field_names. ID целей берутся из v4goals_get_stat_goals(campaign_ids=...)
• «за год / два года / N месяцев» → длинный период, ставь output_path
• «по конкретным кампаниям/группам» → campaign_ids="111,222" или adgroup_ids="..."
• любые поля кроме семи дефолтных (Ctr, AvgCpc, BounceRate, AvgPageviews, Device, Placement, Gender, Age, Slot и т.д.)

Поле для фильтра целей в CUSTOM_REPORT называется Goals (НЕ GoalsIds). Параметр goal_ids инструмента собирает фильтр сам.

Примеры

Запрос	Вызов
Статистика за 2 года, по месяцам, цели 12345 и 67890	reports_custom(field_names="Month,CampaignName,Impressions,Clicks,Cost,Goals,Conversions", date_from="2024-04-29", date_to="2026-04-29", goal_ids="12345,67890", order_by=["Month:ASC"], output_path="/tmp/r.json")
Топ-50 ключей по затратам за прошлый месяц	reports_custom(field_names="CampaignName,Criterion,Impressions,Clicks,Cost,Conversions", report_type="CRITERIA_PERFORMANCE_REPORT", date_from="2026-03-01", date_to="2026-03-31", order_by=["Cost:DESC"], page_limit=50)
Дневная динамика кампаний 111 и 222 за 30 дней	reports_custom(field_names="Date,CampaignName,Impressions,Clicks,Cost,Conversions", date_range_type="last_30_days", campaign_ids="111,222", order_by=["Date:ASC"])
Просто что было на той неделе	reports_get(date_from="2026-04-22", date_to="2026-04-29")

Большие отчёты (>5000 строк или период >6 месяцев)

Обязательно указывай output_path в /tmp или внутри $CLAUDE_PLUGIN_DATA, например output_path="/tmp/r.json". Тул вернёт {output_path, rows_written, report_type, format}, файл потом читай Read/jq/pandas. Без output_path весь отчёт грузится в память агента и может превысить лимиты контекста.

Форматы и расширенные параметры

response_format (json | tsv | csv | table) теперь действует и для output_path, и для in-memory результата. Дефолт json — возвращается list[dict]. Любой другой формат без output_path возвращает {format, report_type, content} со строкой CLI stdout (CLI уже срезает report-header и summary).

Прочие типизированные параметры CLI 0.3.10 (необязательные):

• processing_mode (auto/online/offline) — режим обработки Reports API
• language (ru/en) — Accept-Language ответа
• attribution_models — CSV из FC, LC, LSC, LYDC, FCCD, LSCCD, LYDCCD, AUTO
• skip_report_header / skip_column_header / skip_report_summary — управление строками TSV (CLI по умолчанию скрывает заголовок и summary)
• return_money_in_micros — деньги в микрорублях вместо рублей

Типичные запросы

Запрос пользователя	MCP Tool
Покажи все кампании	campaigns_get()
Покажи активные кампании	campaigns_get(state="ON")
Создай кампанию	campaigns_add(name="...", start_date="2024-01-01")
Сколько объявлений в кампании 123?	ads_get(campaign_ids="123") → count
Включи кампанию 456	campaigns_update(id=456, status="ON")
Отключи кампанию 456	campaigns_update(id=456, status="OFF")
Ключевые слова кампании 789	keywords_get(campaign_ids="789")
Изменить ставку ключевого слова на 15 руб	keywordbids_set(keyword_id=99999, search_bid=15000000)
Установить дневной бюджет 500 руб	campaigns_update(id=456, budget=500000000)
Установить ставку 10 руб на кампанию	bids_set(campaign_id=123, bid=10000000)
Ставка показа на dynamic-target	dynamicads_set_bids(id=42, bid=5000000)
Средняя CPC для smart-таргета	smartadtargets_set_bids(id=42, average_cpc=8000000)
Статистика за последнюю неделю	reports_get(date_from="...", date_to="...")
По месяцам / с фильтром по целям / за длинный период	reports_custom(...) — см. раздел «Отчёты»
Баланс аккаунта	balance_get()
Цели Метрики для кампаний	v4goals_get_stat_goals(campaign_ids="123")
Ретаргетинговые цели для кампаний	v4goals_get_retargeting_goals(campaign_ids="123")
Теги кампании	v4tags_get_campaigns(campaign_ids="123")
Теги объявлений	v4tags_get_banners(campaign_ids="123") или v4tags_get_banners(banner_ids="456")
Заменить теги кампании	v4tags_update_campaigns(campaign_id=123, tags=["0=New tag"])
Очистить теги объявлений	v4tags_update_banners(banner_ids="456,789", clear_tags=True)
Журнал v4 Live событий	v4events_get_events_log(timestamp_from="2026-05-01T00:00:00", timestamp_to="2026-05-02T00:00:00")
Отчеты Wordstat v4 Live	v4wordstat_list_reports() / v4wordstat_create_report(phrases="купить диван")
Прочитать shared-аккаунты	v4account_get_accounts(logins="login-a,login-b"), v4account_get_accounts(account_ids="111,222") или оба сразу (CLI 0.3.11 сериализует их в одно SelectionCriteria). Без селекторов (v4account_get_accounts()) вернёт все shared-аккаунты владельца.
Обновить shared-аккаунт	v4account_update_account(account_id=1327944, day_budget="100.50", spend_mode="Default", dry_run=True) — CLI 0.3.11 требует передавать day_budget и spend_mode вместе.
Финансовые операции (Deposit/Invoice/TransferMoney)	Только с dry_run=True или sandbox=True. Финансовые токены НЕ передаются как параметры — поставь в env: YANDEX_DIRECT_FINANCE_TOKEN, YANDEX_DIRECT_MASTER_TOKEN, YANDEX_DIRECT_FINANCE_LOGIN. Master-token выдаётся через UI Яндекс.Директ → Инструменты → API → Финансовые операции. Пример: v4account_deposit(payment=["999999=50000"], currency="rub", origin="Overdraft", operation_num=42, dry_run=True)
Проверить аккаунт-wide изменения	changes_check_campaigns(timestamp="2026-05-21T00:00:00Z")
Проверить точечно изменения по кампаниям/группам/объявлениям	changes_check(field_names="CampaignIds,AdGroupIds", timestamp="2026-05-21T00:00:00Z", campaign_ids="123,456")
Показать группы объявлений	adgroups_get(campaign_ids="123")
Токен живой?	auth_status()

Важные детали

Микроюниты для ставок

Все money-параметры (ставки, бюджеты, CPC/CPA, потолки) передаются в микрорублях: 15 RUB = 15,000,000. Умножайте рубли на 1,000,000.

CLI 0.2.10+ отвергает значения в диапазоне 0 < x < 100_000 (меньше 0.1 ₽) с подсказкой «did you mean × 1_000_000?» — обычная защита от того, что вы случайно передали рубли вместо микрорублей.

Все идентификаторы (id, campaign_id, ad_group_id, keyword_id, client_id, region_id и т.д.) и money-параметры — целые числа (int), а не строки. Списки идентификаторов через запятую (*_ids) — наоборот, передаются строкой "1,2,3".

API-лимиты и батчинг

• Максимум 10 ID за запрос для большинства list/delete операций (campaigns_get, ads_get, keywords_get, *_delete и т.д.)
• Для больших наборов делайте несколько запросов по 5-10 ID
• Исключение — changes_check: лимиты задаются API и зависят от выбранного фильтра: campaign_ids до 3000, ad_group_ids до 10 000, ad_ids до 50 000. Параметры взаимоисключающие (передавайте ровно один). field_names обязателен, допустимые значения: CampaignIds, AdGroupIds, AdIds, CampaignsStat.
• Timestamp в changes_check / changes_check_campaigns — ISO 8601 с явной зоной: ...Z или offset вроде +03:00. Bare timestamp без зоны отклоняется до вызова direct.

Статусы кампаний

• ON — активная кампания
• OFF — приостановлена
• ARCHIVED — в архиве

Авторизация

• Для интерактивной авторизации используйте auth_login() — запустит pending PKCE flow, покажет ссылку и запросит код
• Для готового токена используйте auth_setup(code="y0_...", login="..."); обычный browser OAuth code вводится только в форме auth_login()
• Токен и login сохраняются в активном direct auth profile; MCP-запросы используют этот же профиль
• Если профиль протух или login неверный, запустите auth_login() заново

Запуск Python-скриптов

В zsh/bash символ ! в heredoc (<< 'EOF') интерпретируется как history expansion. Операторы != в Python-коде превращаются в \!= → SyntaxError. Всегда записывайте Python-скрипт в файл через Write, затем запускайте через python3 /path/to/script.py.

Диагностика warning 10165 «параметр не применился»

Direct возвращает этот код без указания, какой именно параметр был проигнорирован. Чтобы увидеть исходящий payload до отправки, у мутирующих tools есть dry_run=True:

ads_add(ad_group_id=..., ad_type="TEXT_AD", title="...", dry_run=True)
campaigns_add(name="...", start_date="...", dry_run=True)

CLI вернёт сериализованный запрос — по нему можно вычислить лишнее поле.