Yandex Wordstat MCP Server

Yandex Wordstat MCP Server

Неофициальный open-source MCP-сервер, который даёт AI-агентам типизированный read-only доступ ко всем стандартным методам Yandex Wordstat API.

Статус: 0.1.1, исправление совместимости с пропущенными protobuf-default значениями Wordstat API.

English

Возможности

• все четыре метода Wordstat API и дополнительный локальный поиск ID региона по названию;
• строгие входные и выходные схемы, безопасные авто-диапазоны дат и проверка операторов;
• повторы временных ошибок с учётом Retry-After, таймауты и отмена запросов;
• локальные лимиты RPS, запросов в час и параллельности;
• кэш дерева регионов, дедупликация одновременных запросов и fallback на устаревший кэш;
• счётчики API-вызовов, HTTP-попыток и приблизительно тарифицируемых вызовов;
• stdio-транспорт без записи логов в протокольный stdout.

Все инструменты помечены как read-only и idempotent. Запросы к Wordstat являются внешними API-вызовами и могут тарифицироваться.

Требования и доступ

• Node.js 22.23.4+, 24.22.1+ или 26.12.1+ в соответствующей LTS-линейке;
• API-ключ со scope yc.search-api.execute или IAM-токен;
• роль search-api.webSearch.user на нужный каталог Yandex Cloud.

Задайте ровно один credential в окружении MCP-клиента:

export YANDEX_WORDSTAT_API_KEY='your-api-key'

или: export YANDEX_WORDSTAT_IAM_TOKEN='your-iam-token'

Не сохраняйте реальные credentials в репозитории или общей MCP-конфигурации. Перезапустите клиент после изменения его окружения.

Когда нужен YANDEX_WORDSTAT_FOLDER_ID

Переменная обязательна для IAM-токена аккаунта Яндекса или федеративного аккаунта. Укажите ID каталога, на который назначена роль search-api.webSearch.user:

export YANDEX_WORDSTAT_FOLDER_ID='b1g...'

Для API-ключа или IAM-токена сервисного аккаунта переменную обычно не задают: Search API использует каталог сервисного аккаунта.

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

Выберите один способ авторизации: API-ключ или IAM-токен. Не передавайте оба одновременно. В примерах Codex и Claude Code переменные уже экспортированы в окружение процесса клиента.

Codex CLI / IDE

Добавьте в ~/.codex/config.toml:

[mcp_servers.yandex-wordstat]

command = "npx" args = ["-y", "wordstat-mcp-server@latest"] env_vars = ["YANDEX_WORDSTAT_API_KEY"]

Для IAM-токена аккаунта Яндекса или федеративного аккаунта используйте:

[mcp_servers.yandex-wordstat]

command = "npx" args = ["-y", "wordstat-mcp-server@latest"] env_vars = ["YANDEX_WORDSTAT_IAM_TOKEN", "YANDEX_WORDSTAT_FOLDER_ID"]

Затем проверьте подключение командой codex mcp list. Codex CLI и IDE используют общую конфигурацию.

Claude Code

claude mcp add-json --scope user yandex-wordstat \

'{"command":"npx","args":["-y","wordstat-mcp-server@latest"],"env":{"YANDEX_WORDSTAT_API_KEY":"${YANDEX_WORDSTAT_API_KEY}"}}' claude mcp list

Вариант с IAM-токеном аккаунта Яндекса или федеративного аккаунта:

claude mcp add-json --scope user yandex-wordstat \

'{"command":"npx","args":["-y","wordstat-mcp-server@latest"],"env":{"YANDEX_WORDSTAT_IAM_TOKEN":"${YANDEX_WORDSTAT_IAM_TOKEN}","YANDEX_WORDSTAT_FOLDER_ID":"${YANDEX_WORDSTAT_FOLDER_ID}"}}' claude mcp list

Hermes Agent

Добавьте сервер в пользовательский ~/.hermes/config.yaml:

mcp_servers:

yandex_wordstat: command: "npx" args: ["-y", "wordstat-mcp-server@latest"] env: YANDEX_WORDSTAT_API_KEY: "your-api-key"

Вариант с IAM-токеном аккаунта Яндекса или федеративного аккаунта:

mcp_servers:

yandex_wordstat: command: "npx" args: ["-y", "wordstat-mcp-server@latest"] env: YANDEX_WORDSTAT_IAM_TOKEN: "your-iam-token" YANDEX_WORDSTAT_FOLDER_ID: "your-folder-id"

Hermes передаёт stdio-серверу только явно перечисленные переменные. Не добавляйте пользовательский конфиг с credential в репозиторий.

Проверьте подключение командой hermes mcp test yandex_wordstat, затем перезапустите Hermes или выполните /reload-mcp. Инструменты будут зарегистрированы с префиксом mcp_yandex_wordstat_. Параллельные вызовы по умолчанию выключены, что помогает контролировать квоту.

Инструменты

Значения devices: all, desktop, phone, tablet; all нельзя сочетать с другими значениями. В одном запросе допускается до 100 region_ids.

wordstat_find_regions работает по кэшированному дереву. Он полезен, когда агент знает название региона, но не его ID. wordstat_regions при resolve_names: true делает дополнительный бесплатный вызов дерева только при промахе кэша. Каждая следующая страница wordstat_regions заново вызывает платный метод распределения по регионам, поэтому для полной выборки лучше использовать максимальный limit.

Даты и операторы

wordstat_dynamics принимает даты в формате YYYY-MM-DD. Если при auto_dates: true обе даты отсутствуют, сервер запрашивает последние 60 завершённых дней, 52 завершённые недели или 12 завершённых месяцев — в зависимости от детализации. Если отсутствует только одна граница, сервер вычисляет её; автоматически добавленный to_date всегда указывает на последний завершённый период. Явно переданные границы не сдвигаются. При auto_dates: false обязателен только from_date; to_date можно не задавать.

Дневной диапазон не может превышать 60 дней. Для недельной и месячной детализации Wordstat документирует диапазон от 3 недель или месяцев до 5 лет; самая ранняя доступная история начинается с января 2018 года. Неделя задаётся от понедельника до воскресенья, месяц — от первого до последнего дня месяца.

Live-проверки показали наблюдаемое, но не документированное поведение: последние календарные точки могут быть ещё не опубликованы, API возвращает только доступную часть пересекающегося диапазона, а диапазон целиком после последней опубликованной точки может получить HTTP 400. Поскольку HTTP 400 может иметь и другие причины, проверьте все параметры запроса; для недавнего диапазона попробуйте более ранние даты. Сервер не сдвигает явно заданный диапазон и не делает дополнительный платный запрос автоматически.

Для дневной динамики разрешены операторы -, !, +, кавычки, [], () и |; для недельной и месячной — только +. Явные неподдерживаемые операторы для недельной и месячной детализации отклоняются до платного API-вызова.

Метаданные результата

Каждый успешный ответ содержит:

• api_calls — логические вызовы Wordstat API, включая бесплатное дерево регионов;
• http_attempts — все HTTP-попытки, в том числе повторы;
• billable_calls_estimate — оценка платных вызовов; финальный биллинг определяет Yandex;
• local_hourly_budget_remaining — остаток локального часового лимита или null;
• content_truncated — был ли сокращён текстовый MCP-контент из-за размера.

Поля count и total_count возвращаются строками, чтобы не терять точность 64-битных целых.

Примеры запросов агенту

Расширение семантики

Подбери запросы по теме «онлайн-курсы английского». Покажи 100 популярных запросов

и похожие запросы за последний месяц. Сгруппируй их по смыслу: обучение, цена, формат, уровень и бренды. В каждой группе выдели 5 самых популярных фраз. Популярные и похожие запросы покажи отдельно.

Сравнение регионального спроса

Сравни спрос на «доставка цветов» в Москве и Санкт-Петербурге за последние 12 полных

месяцев. Найди нужные регионы сам. Покажи динамику по месяцам для каждого города, отметь месяцы с самым высоким и низким спросом и объясни различия в сезонности. Если каких-то данных нет, не додумывай их.

Интерес по регионам

Покажи, в каких регионах запросом «горнолыжный курорт» интересуются сильнее всего.

Составь два списка: топ-15 регионов по индексу интереса и топ-15 по числу запросов. Для каждого региона укажи число запросов, долю и индекс интереса. Коротко объясни, почему списки отличаются. Загружай дополнительные страницы только при необходимости.

Сезонность и сравнение с прошлым годом

Проанализируй спрос на «кондиционер» по России за последние 24 полных календарных месяца,

не включая текущий месяц. Используй регион «Россия» с ID 225 и обязательно задай начало и конец периода. Сравни каждый месяц с тем же месяцем годом ранее. Покажи изменение в запросах и процентах, а также начало и пик сезона. Если данных не хватает, перечисли пропущенные месяцы и сравни только полные пары. Если год назад было ноль запросов, процентное изменение не рассчитывай.

Различия по устройствам

Сравни спрос на «заказать продукты» с компьютеров, телефонов и планшетов за последние

60 полных дней. Для каждого типа устройства покажи общее число запросов, среднее за день и его долю среди трёх типов устройств. Сравнивай только даты, которые есть во всех выборках. Не называй число запросов количеством уникальных пользователей.

Влияние операторов Wordstat

Покажи, как кавычки влияют на статистику запроса «ремонт квартир». Сравни за последние

60 полных дней обычный запрос ремонт квартир и запрос в кавычках "ремонт квартир". Покажи общую частотность каждого варианта, разницу между ними и простыми словами объясни, что ограничивают кавычки в Wordstat.

Контроль стоимости исследования

Нужно изучить запрос «ипотека»: популярные и похожие запросы, динамику по месяцам

и интерес по регионам. Сначала скажи, сколько платных обращений к Wordstat потребуется, и дождись моего подтверждения. После исследования покажи фактическое число обращений и отдельно отметь повторные попытки, если они были.

Конфигурация