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-серверу только явно перечисленные переменные. Не добавляйте пользовательский ко

... View full README on GitHub