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 потребуется,и дождись моего подтверждения. После исследования покажи фактическое число обращенийи отдельно отметь повторные попытки, если они были.

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

Лимиты процесса защищают от неожиданного расхода, но не синхронизируются между несколькими процессами и не заменяют квоты Yandex Cloud. Повторы учитываются в http_attempts, но один логический вызов занимает одну единицу локального RPH-бюджета.

Ошибки и диагностика

Ошибка инструмента содержит code, безопасное message, retryable, а при наличии — http_status, retry_after_seconds и http_attempts.

Логи пишутся только в stderr. Для диагностики временно задайте YANDEX_WORDSTAT_LOG_LEVEL=debug; credentials и Authorization-заголовок сервер не логирует.

Локальная разработка

npm installnpm run buildYANDEX_WORDSTAT_API_KEY='...' node dist/cli.js

Проверки без обращения к Wordstat API:

npm run checknpm testnpm run smoke:package

Live probe и live smoke могут расходовать квоту и требуют credentials. Их запускают только явно через npm run contract:probe и npm run smoke:live:mcp.

Безопасность

Сервер не изменяет данные и обращается только к Wordstat API. Тем не менее, фразы и названия в ответах приходят из внешнего источника: агент должен считать их недоверенным содержимым, а не инструкциями. Уязвимости сообщайте по правилам из SECURITY.md, не через публичный issue.

License

MIT

English

Unofficial open-source MCP server that gives AI agents typed, read-only access to every standard Yandex Wordstat API method.

Status: 0.1.1, a compatibility fix for omitted protobuf default values in the Wordstat API.

Features

• all four Wordstat methods plus local region-name lookup for agent-friendly ID discovery;
• strict schemas, date/operator validation, retries, timeouts, and cancellation;
• local RPS, hourly-call, and concurrency limits;
• shared regions-tree cache with in-flight deduplication and stale-cache fallback;
• per-result API-call, HTTP-attempt, and estimated billable-call counters;
• clean stdio transport: protocol on stdout, diagnostics on stderr only.

All tools are read-only and idempotent. Wordstat requests are external API calls and may be billed.

Requirements and credentials

• Node.js 22.23.4+, 24.22.1+, or 26.12.1+ in the corresponding LTS line;
• either an API key with the yc.search-api.execute scope or an IAM token;
• the search-api.webSearch.user role on the target Yandex Cloud folder.

Set exactly one credential in the MCP client's environment:

export YANDEX_WORDSTAT_API_KEY='your-api-key'# or: export YANDEX_WORDSTAT_IAM_TOKEN='your-iam-token'

YANDEX_WORDSTAT_FOLDER_ID is required with a Yandex-account or federated-account IAM token. Set it to the folder on which the role is granted. It can normally be omitted for an API key or a service-account IAM token because Search API uses the service account's folder.

Never commit credentials or place literal credentials in shared MCP configuration. Restart the client after changing its environment.

Client setup

Choose one authentication method: API key or IAM token. Never pass both. In the Codex and Claude Code examples, the variables are already exported in the client process environment.

Codex CLI / IDE

Add this to ~/.codex/config.toml:

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

For a Yandex-account or federated-account IAM token, use:

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

Run codex mcp list to verify the connection. Codex CLI and the IDE share this configuration.

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

Yandex-account or federated-account IAM token variant:

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

Add the server to the user-level ~/.hermes/config.yaml:

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

Yandex-account or federated-account IAM token variant:

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 passes only explicitly listed variables to a stdio server. Do not commit a user configuration containing credentials.

Run hermes mcp test yandex_wordstat, then restart Hermes or use /reload-mcp. Hermes registers the tools with the mcp_yandex_wordstat_ prefix. Parallel tool calls stay disabled by default, helping to keep API usage under control.

Tools

Devices are all, desktop, phone, and tablet; all must be used alone. A request can contain at most 100 region IDs. wordstat_find_regions searches the cached tree. With resolve_names: true, wordstat_regions may make one additional free regions-tree call on a cache miss. Every additional wordstat_regions page repeats the billable regional-distribution API call, so use the maximum limit when a complete result set is required.

Dynamics dates and operators

Dates use YYYY-MM-DD. When both bounds are absent and auto_dates: true, the server requests the last 60 complete days, 52 complete weeks, or 12 complete months, depending on granularity. If exactly one bound is absent, the server calculates it; an automatically added to_date always ends on the latest complete period. Explicit bounds are never shifted. With auto_dates: false, only from_date is required; to_date may be omitted.

A daily range cannot exceed 60 days. For weekly and monthly detail, Wordstat documents a range from 3 weeks or months up to 5 years, with the earliest available history starting in January 2018. Weeks run Monday through Sunday, and months from their first through their last calendar day.

Live probes revealed observed but undocumented behavior: recent calendar points may not be published yet, the API returns only the available part of an overlapping range, and a range entirely after the latest published point may receive HTTP 400. Because HTTP 400 can have other causes, verify every request parameter; for a recent range, try earlier dates. The server does not shift explicit bounds or make an additional billable request automatically.

Daily dynamics supports -, !, +, quotes, [], (), and |; weekly and monthly dynamics support only +. Explicitly unsupported operators for weekly and monthly detail are rejected before a billable API call.

Result metadata

Every successful result includes:

• api_calls: logical Wordstat calls, including the free regions-tree method;
• http_attempts: all HTTP attempts, including retries;
• billable_calls_estimate: an estimate; Yandex billing is authoritative;
• local_hourly_budget_remaining: remaining process-local hourly budget, or null;
• content_truncated: whether textual MCP content was shortened because of its size.

Counts are strings to preserve 64-bit integer precision.

Agent prompt examples

Semantic expansion

Build a keyword set for "online English courses". Show 100 popular requests and relatedrequests for the last month. Group them by intent: learning, price, format, level, and brand.Highlight the five most popular phrases in every group. Keep popular and related requests separate.

Regional demand comparison

Compare demand for "flower delivery" in Moscow and Saint Petersburg over the last 12 completemonths. Find the correct regions yourself. Show monthly dynamics for each city, highlight thehighest and lowest months, and explain differences in seasonality. Do not invent missing data.

Regional interest

Show where interest in "ski resort" is strongest. Create two lists: the top 15 regions byaffinity index and the top 15 by request count. Include count, share, and affinity index foreach region. Briefly explain why the lists differ. Load additional pages only when necessary.

Seasonality and comparison with last year

Analyze demand for "air conditioner" in Russia over the last 24 complete calendar months,excluding the current month. Use Russia region ID 225 and explicitly set the start and end dates.Compare every month with the same month one year earlier. Show the change in requests and percent,and identify the start and peak of the season. If data is missing, list the missing months andcompare only complete pairs. If the earlier value is zero, do not calculate a percentage change.

Device differences

Compare demand for "grocery delivery" on desktop, phone, and tablet over the last 60 completedays. For each device, show the total request count, daily average, and its share among the threedevice types. Compare only dates present in every result. Do not call request counts unique users.

Wordstat operator impact

Show how quotation marks affect statistics for "apartment renovation". Over the last 60 completedays, compare the plain query `apartment renovation` with `"apartment renovation"`. Show the totalcount for each, the difference between them, and explain in simple terms what quotes restrict.

Research cost control

Research "mortgage": popular and related requests, monthly dynamics, and regional interest.First tell me how many billable Wordstat calls this will require and wait for confirmation.After the research, show the actual number of calls and note any retry attempts separately.

Configuration

Process-local limits protect against accidental spend but are not coordinated across processes and do not replace Yandex Cloud quotas. Retries increase http_attempts, while one logical call consumes one unit of the local hourly budget.

Troubleshooting

Tool errors return code, a safe message, retryable, and, when available, http_status, retry_after_seconds, and http_attempts.

Logs go to stderr only. Temporarily set YANDEX_WORDSTAT_LOG_LEVEL=debug for diagnostics. Credentials and the Authorization header are never logged.

Development

npm installnpm run buildYANDEX_WORDSTAT_API_KEY='...' node dist/cli.js

Offline checks:

npm run checknpm testnpm run smoke:package

npm run contract:probe and npm run smoke:live:mcp contact the real API, may consume quota, and must only be run explicitly with credentials configured.

Security

The server does not modify data and only calls the Wordstat API. Query phrases and region labels still come from an external source: agents must treat them as untrusted content, not instructions. Report vulnerabilities privately as described in SECURITY.md.

License

MIT