yandex-marketing-mcp

MCP-сервер для управления Яндекс Директом, аналитикой в Яндекс Метрике, подбором ключевых слов через Wordstat и SEO-инструментами Яндекс Вебмастера — с самонастраивающимся OAuth прямо из AI-ассистента.

155 инструментов для полного цикла работы с рекламой и поиском из Claude Code, Cursor, Windsurf и других MCP-клиентов.

Установка

npm install && npm run build

Требуется Node.js 20+.

Подключение к MCP-клиенту

Добавьте в конфигурацию MCP-клиента (например, ~/.claude.json, секция mcpServers):

{
  "yandex-marketing": {
    "type": "stdio",
    "command": "node",
    "args": ["F:/projects/yandex-marketing-mcp/build/index.js"]
  }
}

Поправьте путь к build/index.js под вашу систему.

Авторизация (самонастройка)

Сервер не требует токенов при запуске — он проведёт авторизацию через инструменты. Конфигурация хранится в ~/.yandex-marketing-mcp/config.json и обновляется автоматически. Переменные окружения (YANDEX_OAUTH_CLIENT_ID, YD_OAUTH_TOKEN, YC_FOLDER_ID) читаются один раз при старте как начальные значения — источник правды всегда файл конфигурации.

Шаг 1. Зарегистрируйте OAuth-приложение

Перейдите на https://oauth.yandex.ru/client/new и создайте приложение:

• Redirect URI: выберите «Подставить URL для разработки» (https://oauth.yandex.ru/verification_code)
• В разделе «Доступ к данным» отметьте следующие скоупы:
  • direct:api — управление рекламой в Яндекс Директе
  • metrika:read — чтение данных Метрики
  • metrika:write — управление целями и счётчиками
  • cloud:auth — IAM-токен (для Wordstat больше не работает, см. «Настройка Wordstat» ниже)
  • webmaster:hostview — просмотр данных Вебмастера
  • webmaster:verify — верификация сайтов в Вебмастере
• Сохраните и запомните Client ID

Шаг 2. Сохраните Client ID через инструмент

Вызовите yd_set_client_id с вашим Client ID — инструмент сохранит его и вернёт ссылку для авторизации.

Шаг 3. Получите токен

Откройте ссылку из ответа yd_set_client_id в браузере, подтвердите доступ. После редиректа скопируйте значение параметра access_token из адресной строки.

Шаг 4. Сохраните токен

Вызовите yd_set_token с полученным токеном. Токен проверяется через API Метрики перед сохранением.

Проверка статуса: yd_auth_status — показывает, что настроено, валиден ли токен, и подсказывает следующий шаг. Поле token_valid относится к Директу, Метрике и Вебмастеру; готовность Wordstat показывается отдельно в wordstat_ready.

Шаг 5. Настройка Wordstat — сервисный аккаунт Yandex Cloud

Wordstat ходит через Yandex Cloud и требует IAM-токен. С 1 июня 2026 года Облако не обменивает на IAM пользовательские OAuth-токены, выпущенные начиная с этой даты — запрет привязан к дате выпуска токена, поэтому перевыпуск не помогает. Скоупа cloud:auth теперь недостаточно, нужен сервисный аккаунт.

# ID каталога
yc resource-manager folder list

# Сервисный аккаунт и авторизованный ключ
yc iam service-account create --name wordstat-mcp
yc iam key create --service-account-name wordstat-mcp -o key.json

Приватный ключ в Облаке не хранится и повторно не выдаётся — если потеряете key.json, придётся создавать новый ключ.

Дальше вызовите yd_set_service_account:

{ "key_file": "~/key.json", "yc_folder_id": "b1g..." }

Сервер подпишет JWT (PS256) и сам будет обменивать его на IAM-токен, продлевая по мере истечения. Проверить: yd_wordstat_regions_tree.

Временный вариант, если сервисный аккаунт заводить некогда: yc iam create-token и затем yd_set_iam_token. IAM-токен живёт не больше 12 часов, после чего вызовы упадут — это костыль на один сеанс, не решение.

Сервисному аккаунту нужна роль на каталог для доступа к Wordstat, а к облаку — привязанный платёжный аккаунт. Актуальные названия ролей и тарифы смотрите в документации Yandex Search API: сверьте их в браузере перед первым платным вызовом.

Возможности

| Сервис | Инструментов | Описание | |--------|-------------|---------| | Авторизация | 5 | Self-setup OAuth + сервисный аккаунт Yandex Cloud | | Яндекс Директ (основной) | 46 | Кампании, группы, объявления, ключевики, ставки, корректировки, минус-фразы, сайтлинки, ретаргетинг, изображения, отчёты | | Яндекс Директ (расширенный) | 26 | Визитки, фиды, смарт-таргеты, видео, креативы, площадки, стратегии | | Wordstat | 5 | Частотность запросов, динамика, регионы | | Яндекс Метрика | 43 | Счётчики, цели, сегменты, фильтры, доступы, отчёты, аннотации, офлайн-данные, метки | | Яндекс Вебмастер | 30 | Хосты, верификация, индексирование, поисковые запросы, ссылки, рекроул |

Полный список инструментов

Авторизация

| Инструмент | Описание | |-----------|----------| | yd_auth_status | Проверить статус: client_id, токен, folder_id, готовность Wordstat | | yd_set_client_id | Сохранить Client ID OAuth-приложения и получить ссылку для авторизации | | yd_set_token | Сохранить OAuth access_token (с валидацией через Метрику); опционально — folder_id | | yd_set_service_account | Настроить сервисный аккаунт Yandex Cloud для Wordstat (key_file или key_json) | | yd_set_iam_token | Временно сохранить готовый IAM-токен из yc iam create-token (≤12 ч) |

Яндекс Директ — Кампании

| Инструмент | Описание | |-----------|----------| | yd_campaigns_get | Список кампаний с фильтрами (тип, статус, ID) | | yd_campaigns_add | Создать текстовую кампанию (все стратегии: PAY_FOR_CONVERSION, WB_MAXIMUM_CLICKS и др.) | | yd_campaigns_update | Обновить настройки кампании (имя, бюджет, минус-фразы, дата окончания) | | yd_campaigns_action | Приостановить / возобновить / архивировать / разархивировать кампанию |

Яндекс Директ — Группы объявлений

| Инструмент | Описание | |-----------|----------| | yd_adgroups_add | Создать группы объявлений в кампании | | yd_adgroups_get | Получить группы по кампании или ID групп | | yd_adgroups_update | Обновить группу (имя, регионы, минус-фразы, UTM-параметры) |

Яндекс Директ — Объявления

| Инструмент | Описание | |-----------|----------| | yd_ads_add | Создать текстовые объявления (с сайтлинками и картинками) | | yd_ads_update | Обновить текстовые объявления | | yd_ads_get | Получить объявления по кампании, группе или ID | | yd_ads_action | Модерация / пауза / возобновление / архив объявлений | | yd_ads_add_dynamic | Создать динамическое текстовое объявление | | yd_ads_add_image | Создать графическое объявление (TextImageAd) | | yd_ads_add_shopping | Создать товарное объявление (v501 API) |

Яндекс Директ — Ключевые фразы

| Инструмент | Описание | |-----------|----------| | yd_keywords_add | Добавить ключевые фразы в группу | | yd_keywords_get | Получить фразы по кампании, группе или ID | | yd_keywords_has_volume | Проверить наличие трафика у фраз (до 10 000) | | yd_keywords_research | Дедупликация и устранение пересечений фраз |

Яндекс Директ — Ставки

| Инструмент | Описание | |-----------|----------| | yd_bids_set | Установить ставки для ключевых фраз | | yd_keyword_bids_get | Получить ставки и прогнозы трафика | | yd_keyword_bids_set | Установить ставки (поиск и сеть) | | yd_keyword_bids_set_auto | Автоматические ставки по целевой позиции |

Яндекс Директ — Корректировки ставок

| Инструмент | Описание | |-----------|----------| | yd_bid_modifiers_add | Добавить корректировки (устройства, демография, регионы) | | yd_bid_modifiers_get | Получить корректировки | | yd_bid_modifiers_set | Обновить корректировки по ID | | yd_bid_modifiers_delete | Удалить корректировки | | yd_bid_modifiers_toggle | Включить / выключить корректировки |

Яндекс Директ — Минус-фразы

| Инструмент | Описание | |-----------|----------| | yd_negative_keywords_sets_add | Создать набор минус-фраз (общий, до 30 наборов) | | yd_negative_keywords_sets_get | Получить наборы минус-фраз | | yd_negative_keywords_sets_update | Обновить набор минус-фраз | | yd_negative_keywords_sets_delete | Удалить набор минус-фраз |

Яндекс Директ — Сайтлинки и уточнения

| Инструмент | Описание | |-----------|----------| | yd_sitelinks_add | Создать набор быстрых ссылок (1–8 штук) | | yd_sitelinks_get | Получить наборы быстрых ссылок | | yd_sitelinks_delete | Удалить наборы быстрых ссылок | | yd_ad_extensions_add | Создать уточнения (callouts, до 25 символов) | | yd_ad_extensions_get | Получить уточнения | | yd_ad_extensions_delete | Удалить уточнения | | yd_callouts_link | Привязать уточнения к объявлению (v501) |

Яндекс Директ — Ретаргетинг и аудитории

| Инструмент | Описание | |-----------|----------| | yd_retargeting_lists_add | Создать список ретаргетинга на основе целей Метрики | | yd_retargeting_lists_get | Получить списки ретаргетинга | | yd_retargeting_lists_delete | Удалить списки ретаргетинга | | yd_audience_targets_add | Добавить аудиторный таргетинг в группу | | yd_audience_targets_get | Получить аудиторные таргетинги | | yd_audience_targets_delete | Удалить аудиторные таргетинги |

Яндекс Директ — Изображения

| Инструмент | Описание | |-----------|----------| | yd_ad_images_add | Загрузить изображения (base64, до 100 за раз) | | yd_ad_images_get | Получить изображения | | yd_ad_images_delete | Удалить изображения |

Яндекс Директ — Видео и креативы

| Инструмент | Описание | |-----------|----------| | yd_videos_upload | Загрузить видео из файла | | yd_videos_get | Получить видео | | yd_creatives_add | Создать видеокреатив | | yd_creatives_get | Получить креативы |

Яндекс Директ — Фиды

| Инструмент | Описание | |-----------|----------| | yd_feeds_add | Добавить фид (RETAIL, HOTELS, REALTY, AUTOMOBILES, FLIGHTS, OTHER) | | yd_feeds_get | Получить фиды | | yd_feeds_update | Обновить фид | | yd_feeds_delete | Удалить фиды |

Яндекс Директ — Визитки

| Инструмент | Описание | |-----------|----------| | yd_vcards_add | Создать визитку для кампании | | yd_vcards_get | Получить визитки | | yd_vcards_delete | Удалить визитки |

Яндекс Директ — Смарт-таргеты

| Инструмент | Описание | |-----------|----------| | yd_smart_targets_add | Создать смарт-таргет (фильтр фида) | | yd_smart_targets_get | Получить смарт-таргеты | | yd_smart_targets_action | Пауза / возобновление / удаление смарт-таргетов |

Яндекс Директ — Площадки и стратегия

| Инструмент | Описание | |-----------|----------| | yd_excluded_sites_get | Получить список заблокированных площадок | | yd_excluded_sites_update | Обновить список заблокированных площадок | | yd_blocked_ips_update | Заблокировать IP-адреса (до 25 шт.) | | yd_campaign_strategy_update | Сменить стратегию ставок, CPA, цель, недельный бюджет |

Яндекс Директ — Отчёты и справочники

| Инструмент | Описание | |-----------|----------| | yd_report | Статистика (TSV, любой тип: кампании, группы, объявления, фразы) | | yd_dictionaries | Справочники (регионы, валюты, категории, временные зоны и др.) | | yd_regions_get | Справочник регионов | | yd_interests_get | Справочник интересов | | yd_changes_check | Проверка изменений с заданной временной метки | | yd_clients_get | Информация об аккаунте (баланс, настройки, логин) | | yd_businesses_get | Организации из Яндекс Бизнеса |

Wordstat API

| Инструмент | Описание | |-----------|----------| | yd_wordstat_top_requests | Популярные запросы с ключевым словом (частотность, регионы, устройства) | | yd_wordstat_dynamics | Динамика частотности по периодам (день / неделя / месяц) | | yd_wordstat_regions | Региональное распределение запросов | | yd_wordstat_regions_tree | Дерево регионов Wordstat (ID для фильтрации) | | yd_wordstat_user_info | Квота API Wordstat |

Яндекс Метрика — Счётчики

| Инструмент | Описание | |-----------|----------| | yd_metrika_counters_get | Список счётчиков | | yd_metrika_counter_get | Детали счётчика | | yd_metrika_counter_create | Создать счётчик | | yd_metrika_counter_update | Обновить счётчик | | yd_metrika_counter_delete | Удалить счётчик |

Яндекс Метрика — Цели

| Инструмент | Описание | |-----------|----------| | yd_metrika_goals_get | Список целей счётчика | | yd_metrika_goal_create | Создать цель | | yd_metrika_goal_update | Обновить цель | | yd_metrika_goal_delete | Удалить цель |

Яндекс Метрика — Сегменты

| Инструмент | Описание | |-----------|----------| | yd_metrika_segments_get | Список сегментов | | yd_metrika_segment_create | Создать сегмент | | yd_metrika_segment_update | Обновить сегмент | | yd_metrika_segment_delete | Удалить сегмент |

Яндекс Метрика — Фильтры

| Инструмент | Описание | |-----------|----------| | yd_metrika_filters_get | Список фильтров счётчика | | yd_metrika_filter_create | Создать фильтр (IP, URL, заголовок и др.) | | yd_metrika_filter_update | Обновить фильтр | | yd_metrika_filter_delete | Удалить фильтр |

Яндекс Метрика — Доступы

| Инструмент | Описание | |-----------|----------| | yd_metrika_grants_get | Список прав доступа к счётчику | | yd_metrika_grant_add | Добавить доступ (view или edit) | | yd_metrika_grant_update | Обновить доступ | | yd_metrika_grant_delete | Удалить доступ | | yd_metrika_delegates_get | Список делегатов (глобальный доступ) | | yd_metrika_delegate_add | Добавить делегата | | yd_metrika_delegate_delete | Удалить делегата |

Яндекс Метрика — Отчёты

| Инструмент | Описание | |-----------|----------| | yd_metrika_report | Табличный отчёт (визиты, пользователи, конверсии, произвольные метрики) | | yd_metrika_report_by_time | Отчёт по времени (группировка: день, неделя, месяц) | | yd_metrika_report_comparison | Сравнение двух периодов (A vs B) | | yd_metrika_report_drilldown | Иерархический drilldown |

Яндекс Метрика — Метки и аннотации

| Инструмент | Описание | |-----------|----------| | yd_metrika_labels_get | Список меток | | yd_metrika_label_create | Создать метку | | yd_metrika_label_update | Обновить метку | | yd_metrika_label_delete | Удалить метку | | yd_metrika_label_link | Привязать счётчик к метке | | yd_metrika_label_unlink | Отвязать счётчик от метки | | yd_metrika_annotations_get | Список аннотаций на графиках | | yd_metrika_annotation_create | Создать аннотацию | | yd_metrika_annotation_update | Обновить аннотацию | | yd_metrika_annotation_delete | Удалить аннотацию |

Яндекс Метрика — Офлайн-данные

| Инструмент | Описание | |-----------|----------| | yd_metrika_upload_conversions | Загрузить офлайн-конверсии | | yd_metrika_conversions_status | Статус загрузки конверсий | | yd_metrika_upload_calls | Загрузить данные о звонках | | yd_metrika_upload_expenses | Загрузить рекламные расходы | | yd_metrika_upload_user_params | Загрузить параметры пользователей |

Яндекс Вебмастер — Хосты

| Инструмент | Описание | |-----------|----------| | yd_webmaster_user_get | Получить данные текущего пользователя (user_id) | | yd_webmaster_hosts_get | Список всех хостов (верифицированных и нет) | | yd_webmaster_host_add | Добавить хост на верификацию | | yd_webmaster_host_get | Детали хоста | | yd_webmaster_host_delete | Удалить (отвязать) хост | | yd_webmaster_host_summary | Сводка хоста: SQI и количество проблем | | yd_webmaster_owners_get | Список владельцев хоста |

Яндекс Вебмастер — Верификация

| Инструмент | Описание | |-----------|----------| | yd_webmaster_verification_get | Статус верификации хоста | | yd_webmaster_verification_start | Запустить верификацию (DNS, HTML-файл, мета-тег и др.) |

Яндекс Вебмастер — Диагностика и SQI

| Инструмент | Описание | |-----------|----------| | yd_webmaster_diagnostics_get | Диагностика и список проблем хоста | | yd_webmaster_sqi_history | История SQI (Site Quality Index) |

Яндекс Вебмастер — Индексирование

| Инструмент | Описание | |-----------|----------| | yd_webmaster_indexing_history | История crawled-страниц | | yd_webmaster_indexing_samples | Примеры проиндексированных страниц | | yd_webmaster_insearch_history | История страниц в поиске | | yd_webmaster_insearch_samples | Примеры страниц в поиске | | yd_webmaster_search_events_samples | Примеры страниц, добавленных или удалённых из поиска |

Яндекс Вебмастер — Поисковые запросы

| Инструмент | Описание | |-----------|----------| | yd_webmaster_search_queries_popular | Популярные поисковые запросы (показы, клики, CTR, позиция) | | yd_webmaster_search_queries_history | Агрегированная история поисковых запросов |

Яндекс Вебмастер — Карты сайта

| Инструмент | Описание | |-----------|----------| | yd_webmaster_sitemaps_get | Карты сайта, известные Яндексу | | yd_webmaster_user_sitemaps_get | Карты сайта, добавленные пользователем | | yd_webmaster_user_sitemap_add | Добавить карту сайта | | yd_webmaster_user_sitemap_delete | Удалить карту сайта |

Яндекс Вебмастер — Ссылки

| Инструмент | Описание | |-----------|----------| | yd_webmaster_external_links_samples | Примеры внешних ссылок (бэклинков) | | yd_webmaster_external_links_history | История количества внешних ссылок | | yd_webmaster_broken_links_samples | Примеры битых внутренних ссылок |

Яндекс Вебмастер — Рекроул

| Инструмент | Описание | |-----------|----------| | yd_webmaster_recrawl_submit | Отправить URL на переиндексацию | | yd_webmaster_recrawl_list | Список задач очереди рекроула | | yd_webmaster_recrawl_task | Статус задачи рекроула | | yd_webmaster_recrawl_quota | Дневная квота рекроула | | yd_webmaster_important_urls | Мониторируемые важные страницы |

Переменные окружения

Все переменные опциональны — сервер запускается без них и проведёт настройку через инструменты.

| Переменная | Описание | |-----------|----------| | YANDEX_OAUTH_CLIENT_ID | Client ID OAuth-приложения (seed; сохраняется через yd_set_client_id) | | YD_OAUTH_TOKEN | OAuth access_token (seed; сохраняется через yd_set_token) | | YC_FOLDER_ID | ID каталога Yandex Cloud для Wordstat (seed; сохраняется через yd_set_token) | | YC_SA_ID | ID сервисного аккаунта Yandex Cloud (seed; сохраняется через yd_set_service_account) | | YC_SA_KEY_ID | ID авторизованного ключа сервисного аккаунта (seed) | | YC_SA_PRIVATE_KEY | Приватный ключ сервисного аккаунта в PEM (seed) | | YC_IAM_TOKEN | Готовый IAM-токен из yc iam create-token (seed; временный обходной путь) | | YD_SANDBOX | true — тестовый режим Директа (sandbox) | | YD_LOGIN | Логин клиента по умолчанию (для агентских аккаунтов) | | YD_READONLY | true — блокирует все изменяющие инструменты; только чтение и отчёты | | YD_CONFIRM | true — изменяющие вызовы сначала возвращают превью; для выполнения нужен confirm=true | | YD_ALLOWED_LOGINS | Белый список логинов клиентов через запятую (только для инструментов Директа) | | YD_LOG_LEVEL | DEBUG / INFO / WARNING / ERROR (по умолчанию INFO) | | YD_LOG_FILE | Путь к лог-файлу (пусто — только stderr, файл не создаётся) | | YD_LOG_BODIES | true — писать тела запросов и ответов в лог |

Режимы безопасности

• Read-only (YD_READONLY=true) — агент видит и анализирует данные, но физически не может создать, изменить или удалить кампании, ставки, счётчики или цели.
• Confirm-режим (YD_CONFIRM=true) — любой изменяющий вызов сначала возвращает превью операции; для выполнения нужно повторить вызов с confirm=true.
• Мульти-аккаунт — инструменты Директа принимают необязательный аргумент client_login; YD_ALLOWED_LOGINS ограничивает доступные логины.
• Partial-success — изменяющие ответы Директа разбираются на per-item Errors/Warnings и сводятся в поле _partial_success.
• Логи — файл создаётся только при заданном YD_LOG_FILE; тела запросов пишутся только при YD_LOG_BODIES=true.

Лицензия

MIT