Яндекс Вордстат MCP
Яндекс Вордстат 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.
- Получите доступ и добавьте сервер в AI-приложение — инструкции для пяти приложений ниже.
- Спросите: «Сколько в месяц ищут „купить велосипед“ и какие есть похожие запросы?»
Codex
Через интерфейс приложения:
- Откройте Settings → Plugins → MCP servers.
- Нажмите Add server.
- Добавьте команду запуска
npx -y mcp-yandex-wordstat@latest и переменные окружения WORDSTAT_API_KEY, WORDSTAT_FOLDER_ID.
Через командную строку:
codex mcp add yandex-wordstat \
--env WORDSTAT_API_KEY=ваш_ключ \
--env WORDSTAT_FOLDER_ID=ваш_folder_id \
-- npx -y mcp-yandex-wordstat@latest
Проверьте подключение:
Официальная инструкция Codex
Claude Code
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 Code
Claude Desktop
Откройте Settings → Developer → Edit Config и добавьте сервер в claude_desktop_config.json:
{
"mcpServers": {
"yandex-wordstat": {
"command": "npx",
"args": ["-y", "mcp-yandex-wordstat@latest"],
"env": {
"WORDSTAT_API_KEY": "ваш_ключ",
"WORDSTAT_FOLDER_ID": "ваш_folder_id"
}
}
}
}
Если Edit Config недоступна, отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json на macOS или %APPDATA%\Claude\claude_desktop_config.json на Windows.
Cursor
Для всех проектов создайте ~/.cursor/mcp.json; только для текущего проекта — .cursor/mcp.json:
{
"mcpServers": {
"yandex-wordstat": {
"command": "npx",
"args": ["-y", "mcp-yandex-wordstat@latest"],
"env": {
"WORDSTAT_API_KEY": "ваш_ключ",
"WORDSTAT_FOLDER_ID": "ваш_folder_id"
}
}
}
}
Документация Cursor
VS Code
Откройте палитру команд и выполните MCP: Open User Configuration. Добавьте в mcp.json:
{
"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"
}
]
}
Проверьте запуск командой MCP: List Servers.
Документация VS Code
Что можно поручить
Подобрать и оценить спрос
- «Сколько раз за месяц ищут эту фразу и какие похожие запросы встречаются?»
- «Подбери запросы вокруг „доставка пиццы“ с их частотностью».
- «Покажи запросы, содержащие мою фразу, отдельно от семантически похожих».
Понять сезонность
- «Покажи спрос на „лыжи“ по месяцам за год».
- «В какие недели спрос на эту услугу растёт или падает?»
- «Сравни динамику запроса на телефонах и компьютерах».
Сравнить регионы
- «В каких городах интерес к „ремонту квартир“ выше среднего?»
- «Сравни спрос в Москве и Санкт-Петербурге».
- «Найди ID нужного региона и сузь следующий отчёт до него».
Как читать данные спроса
top_requests показывает популярные запросы, которые содержат заданную фразу, и семантически близкие запросы. Общий totalCount относится к последним 30 дням.
dynamics возвращает ряд {date, count, share} с дневной, недельной или месячной детализацией. regions распределяет спрос за последние 30 дней по регионам, а affinityIndex выше 100% означает интерес выше среднего. Значения счётчиков могут приходить строками: Яндекс передаёт большие целые числа в JSON в таком виде.
Один вызов строит данные только для одной фразы. Для большого списка ключевых слов лучше сначала сузить список, а не запускать все запросы подряд: квота Yandex Cloud Search API общая для одного ключа.
Как получить доступ
- В Yandex Cloud создайте сервисный аккаунт с ролью
search-api.webSearch.user.
- Выпустите для него API-ключ со scope
yc.search-api.execute — шаги описаны в документации AI Studio.
- Найдите ID каталога (
folderId) в консоли Yandex Cloud на странице каталога и в URL страницы.
- Передайте ключ как
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-клиента. В неё не попадают API-ключ, аргументы инструментов, ваши сообщения, данные спроса и значения переменных окружения. Отключить её для MCP-серверов Ask Ads:
ASKADS_TELEMETRY=0.
Техническая документация
Поддержка
Нашли ошибку или не хватает сценария? Создайте issue или напишите в Telegram.