Yandex Wordstat MCP

MCP-сервер для Yandex Wordstat (Яндекс Вордстат): спрашивайте статистику поискового спроса — частотность, похожие запросы, сезонность и география — из Claude, Cursor, Codex и других AI-клиентов на естественном языке.

Ассистент сам подбирает ключевые слова, оценивает спрос и его динамику и сравнивает регионы — то, что в вебе Вордстата приходится листать по трём вкладкам вручную.

Настоящая MCP-сессия: реальный сервер, хендшейк и tools/call по stdio через официальный SDK; ответы Yandex Cloud Search API (Wordstat) — записанные фикстуры (docs/demo), поэтому демо воспроизводится без ключа и сети — vhs docs/demo.tape.

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

1. Получите API-ключ Yandex Cloud — тот же тип ключа, что для YandexGPT.

2. Добавьте сервер — например, в Claude Code (другие клиенты):

   claude mcp add yandex-wordstat \
     -e WORDSTAT_API_KEY=ваш_ключ -e WORDSTAT_FOLDER_ID=ваш_folder \
     -- npx -y mcp-yandex-wordstat

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

Что умеет

• Топ и похожие запросы — top_requests: популярные запросы с фразой + семантически близкие (associations) и общий объём за 30 дней.
• Динамика — dynamics: ряд {date, count, share} по дням/неделям/месяцам — сезонность и тренд.
• Регионы — regions: распределение спроса по регионам с affinityIndex (где интерес выше/ниже среднего); режимы all / cities / regions.
• Справочник регионов — list_regions: дерево id → name для фильтров и расшифровки регионов.
• Универсальный raw_request — прямой вызов любого пути API.
• Yandex Cloud Search API v2 — auth, endpoints и схемы скрыты за нормализованными инструментами.
• Устойчивость — ретраи на 429/5xx с бэкоффом и таймаут запроса.

Примеры запросов

Попросите ассистента на русском — например:

• «Сколько в месяц ищут "купить велосипед" и какие есть похожие запросы?»
• «Покажи сезонность спроса на "лыжи" по месяцам за год»
• «В каких городах выше всего интерес к "доставка пиццы"?»
• «Подбери ключи вокруг "ремонт квартир" с частотностью»

Доступ к API

Сервер работает через Yandex Cloud Search API v2 (хост searchapi.api.cloud.yandex.net, авторизация API-ключом Yandex Cloud). Данные Вордстата — публичная агрегированная статистика спроса (не привязана к рекламному аккаунту), поэтому один API-ключ обслуживает весь сервер. Открывается self-serve, тем же ключом, что и YandexGPT — заявок и активных кампаний не нужно.

Старый отдельный API Вордстата (api.wordstat.yandex.net, OAuth) больше недоступен. Яндекс перенёс эту функциональность в Yandex Search API на платформе Yandex Cloud (это и есть бэкенд сервера); отдельной осталась только веб-версия на wordstat.yandex.ru. Поддержка флейвора oauth удалена в версии 2.0.0.

Установка

claude mcp add yandex-wordstat \
  -e WORDSTAT_API_KEY=ваш_ключ -e WORDSTAT_FOLDER_ID=ваш_folder \
  -- npx -y mcp-yandex-wordstat

Либо через маркетплейс плагинов — токен спросится диалогом при включении и сохранится в системном keychain (не в конфиге открытым текстом):

/plugin marketplace add askads/claude-plugins
/plugin install yandex-wordstat@askads

claude_desktop_config.json — macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\

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

~/.cursor/mcp.json (или .cursor/mcp.json в проекте)

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

.vscode/mcp.json — ключ servers (не mcpServers)

{
  "servers": {
    "yandex-wordstat": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat"],
      "env": { "WORDSTAT_API_KEY": "ваш_ключ", "WORDSTAT_FOLDER_ID": "ваш_folder" }
    }
  }
}

Получение доступа

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

⚠️ Ключ хранится открытым текстом в конфиге клиента — относитесь как к паролю.

Настройка

| Переменная | Обяз. | По умолчанию | Описание | |---|---|---|---| | WORDSTAT_API_KEY | да | — | API-ключ Yandex Cloud (Search API). | | WORDSTAT_FOLDER_ID | да | — | Идентификатор каталога Yandex Cloud. | | WORDSTAT_LANG | нет | ru | Заголовок Accept-Language. | | WORDSTAT_API_BASE | нет | https://searchapi.api.cloud.yandex.net | Корень API (override). | | WORDSTAT_TIMEOUT_MS | нет | 60000 | Таймаут запроса, мс. | | WORDSTAT_MAX_RETRIES | нет | 3 | Повторы при 429/5xx. |

Требования

• Node.js 20+ (запускается через npx, отдельная установка не нужна).
• Доступ к Yandex Cloud Search API — см. Получение доступа.

Ограничения

• Read-only. У Wordstat API нет изменяющих операций — сервер только читает.
• Общая квота. Лимит (по биллингу Yandex Cloud Search API) считается на один ключ, общий для всех вызовов. Кэшируйте list_regions и ответы по фразам, не гоните частоту.

Документация

• Все инструменты — полный список с описанием.
• Разработка — сборка, тесты, smoke-проверка.
• Публикация — релиз и листинг в каталогах MCP.

Смотрите также

• Ask Ads — чат-аналитик и «Сторож» рекламных кабинетов от авторов этого сервера: алерты о сливах бюджета и поломках трекинга — в Telegram.
• askads/claude-plugins — маркетплейс плагинов Claude: серверы Ask Ads ставятся одной командой, токены спрашиваются при включении.

Поддержка

Вопросы, идеи и доработки — пишите в Telegram: @gistrec.

Лицензия

MIT — см. LICENSE.