Yandex Wordstat MCP

Яндекс Вордстат MCP

[npm] [CI] [Glama] [License: MIT]

Яндекс Вордстат MCP подключает AI-приложение к статистике поискового спроса Яндекса. Спросите, как часто ищут фразу, в какие месяцы интерес растёт и в каких городах тема популярнее, — ассистент соберёт данные Вордстата и объяснит результат. Сервер работает через Yandex Cloud Search API, поэтому не требует доступа к рекламному кабинету Директа.

• Пять инструментов. Топ и похожие запросы, динамика спроса, распределение по регионам, справочник регионов и технический запрос к API.
• Только чтение. API Вордстата не создаёт кампании, объявления, ключевые фразы и другие объекты.
• Спрос и сезонность. Топ запросов и регионы показывают последние 30 дней; динамика строится по дням, неделям или месяцам за нужный период.
• Регион и устройство. Отчёты можно сузить до региона и сравнить спрос на компьютерах, телефонах и планшетах.
• Без OAuth Директа. Нужны API-ключ и ID каталога Yandex Cloud для Search API.

Начните с безопасного запроса:

Сколько в месяц ищут «купить велосипед» и какие есть похожие запросы?

Подключить сервер · Посмотреть сценарии · Открыть техническую документацию

Увидеть работу за минуту

Содержание

• Быстрый старт
• Что можно поручить
• Как читать данные спроса
• Как получить доступ
• Что может изменить данные
• Данные, лимиты и работа в фоне
• Техническая документация
• Поддержка

Быстрый старт

Нужны Node.js 20 или новее, API-ключ Yandex Cloud для Search API и ID каталога Yandex Cloud.

1. Получите доступ и добавьте сервер в AI-приложение — инструкции для пяти приложений ниже.
2. Спросите: «Сколько в месяц ищут „купить велосипед“ и какие есть похожие запросы?»

codex mcp add yandex-wordstat \  --env WORDSTAT_API_KEY=ваш_ключ \  --env WORDSTAT_FOLDER_ID=ваш_folder_id \  -- npx -y mcp-yandex-wordstat@latest

codex mcp list

claude mcp add \  --env WORDSTAT_API_KEY=ваш_ключ \  --env WORDSTAT_FOLDER_ID=ваш_folder_id \  --transport stdio \  --scope user \  yandex-wordstat \  -- npx -y mcp-yandex-wordstat@latest

claude mcp list

{  "mcpServers": {    "yandex-wordstat": {      "command": "npx",      "args": ["-y", "mcp-yandex-wordstat@latest"],      "env": {        "WORDSTAT_API_KEY": "ваш_ключ",        "WORDSTAT_FOLDER_ID": "ваш_folder_id"      }    }  }}

{  "mcpServers": {    "yandex-wordstat": {      "command": "npx",      "args": ["-y", "mcp-yandex-wordstat@latest"],      "env": {        "WORDSTAT_API_KEY": "ваш_ключ",        "WORDSTAT_FOLDER_ID": "ваш_folder_id"      }    }  }}

{  "servers": {    "yandex-wordstat": {      "type": "stdio",      "command": "npx",      "args": ["-y", "mcp-yandex-wordstat@latest"],      "env": {        "WORDSTAT_API_KEY": "${input:wordstat_api_key}",        "WORDSTAT_FOLDER_ID": "${input:wordstat_folder_id}"      }    }  },  "inputs": [    {      "type": "promptString",      "id": "wordstat_api_key",      "description": "API-ключ Yandex Cloud",      "password": true    },    {      "type": "promptString",      "id": "wordstat_folder_id",      "description": "ID каталога Yandex Cloud"    }  ]}

Что можно поручить

Подобрать и оценить спрос

• «Сколько раз за месяц ищут эту фразу и какие похожие запросы встречаются?»
• «Подбери запросы вокруг „доставка пиццы“ с их частотностью».
• «Покажи запросы, содержащие мою фразу, отдельно от семантически похожих».

Понять сезонность

• «Покажи спрос на „лыжи“ по месяцам за год».
• «В какие недели спрос на эту услугу растёт или падает?»
• «Сравни динамику запроса на телефонах и компьютерах».

Сравнить регионы

• «В каких городах интерес к „ремонту квартир“ выше среднего?»
• «Сравни спрос в Москве и Санкт-Петербурге».
• «Найди ID нужного региона и сузь следующий отчёт до него».

Как читать данные спроса

top_requests показывает популярные запросы, которые содержат заданную фразу, и семантически близкие запросы. Общий totalCount относится к последним 30 дням.

dynamics возвращает ряд {date, count, share} с дневной, недельной или месячной детализацией. regions распределяет спрос за последние 30 дней по регионам, а affinityIndex выше 100% означает интерес выше среднего. Значения счётчиков могут приходить строками: Яндекс передаёт большие целые числа в JSON в таком виде.

Один вызов строит данные только для одной фразы. Для большого списка ключевых слов лучше сначала сузить список, а не запускать все запросы подряд: квота Yandex Cloud Search API общая для одного ключа.

Как получить доступ

1. В Yandex Cloud создайте сервисный аккаунт с ролью search-api.webSearch.user.
2. Выпустите для него API-ключ со scope yc.search-api.execute — шаги описаны в документации AI Studio.
3. Найдите ID каталога (folderId) в консоли Yandex Cloud на странице каталога и в URL страницы.
4. Передайте ключ как WORDSTAT_API_KEY, а каталог как WORDSTAT_FOLDER_ID.

Сервер обращается к Yandex Cloud Search API v2. Старый отдельный Wordstat API с OAuth не используется. API-ключ хранится в конфигурации MCP-клиента открытым текстом — относитесь к нему как к паролю.

Что может изменить данные

Ничего в Яндекс Вордстате. Все пять инструментов, включая raw_request, работают только на чтение. Технически API использует POST, но у Wordstat нет эндпоинтов на запись; сервер дополнительно не позволяет произвольному запросу уйти на другой хост.

Данные, лимиты и работа в фоне

• Агрегированные данные. Сервер получает статистику поискового спроса, а не данные конкретного рекламного кабинета.
• Кэш справочника регионов. В долгоживущем процессе дерево регионов загружается один раз и переиспользуется в следующих запросах.
• Повторы при временных ошибках. Таймаут одного запроса — 60 секунд. Сервер делает до трёх повторов после 429, 5xx, сетевой ошибки или тайм-аута; учитывает Retry-After, а задержка не превышает 30 секунд.
• Нет фонового наблюдения. Сервер работает, когда его вызывает AI-приложение. Если приложение поддерживает задания по расписанию, в нём можно настроить периодический отчёт по выбранным фразам.
• Анонимная телеметрия. По умолчанию сервер отправляет случайный идентификатор установки, имя события или инструмента, версии сервера, Node.js, ОС и AI-клиента. При вызове инструмента сервер также отправляет его исход, а при ошибке - фрагмент её текста: код и сообщение, в которых e-mail, адреса, токены, числа от 4 цифр и текст в кавычках заменены на «#». Если в тексте ошибки есть значение из запроса, оно тоже может попасть во фрагмент. В неё не попадают API-ключ, аргументы инструментов, ваши сообщения, данные спроса и значения переменных окружения. Отключить её для MCP-серверов Ask Ads: ASKADS_TELEMETRY=0.

Техническая документация

• Каталог MCP-возможностей — страницы по пользовательским задачам для каждого инструмента.
• Все инструменты и параметры
• Документация по разработке
• Документация по публикации
• Документация Yandex Cloud Search API

Поддержка

Нашли ошибку или не хватает сценария? Создайте issue или напишите в Telegram.