yandex-marketing-mcp

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

153 инструмента для полного цикла работы с рекламой и поиском из 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 API
  • 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 Метрики перед сохранением.

Для Wordstat также передайте yc_folder_id (ID каталога Yandex Cloud).

Проверка статуса: yd_auth_status — показывает, что настроено, валиден ли токен, и подсказывает следующий шаг.

---

Возможности

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

---

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

Авторизация

Инструмент	Описание
yd_auth_status	Проверить статус авторизации: client_id, токен, folder_id
yd_set_client_id	Сохранить Client ID OAuth-приложения и получить ссылку для авторизации
yd_set_token	Сохранить OAuth access_token (с валидацией через Метрику); опционально — folder_id

---

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

Инструмент	Описание
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)
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