Yandex Wordstat MCP

MCP-сервер для работы с Яндекс Вордстатом из Codex, Claude Desktop и других агентских клиентов.

После установки можно попросить агента проверить спрос, собрать похожие запросы, посмотреть сезонность. Данные берутся через официальный Yandex Cloud Search API. У каждого пользователя свой ключ Yandex Cloud.

Что можно делать

• Проверять частотность фраз.
• Смотреть похожие запросы и ассоциации.
• Сравнивать спрос по регионам.
• Смотреть динамику по дням, неделям или месяцам.
• Быстро находить ID региона Яндекса по названию.

Примеры задач:

Посмотри спрос по запросу "ремонт кофемашин" в Москве. Покажи топ похожих запросов и убери мусорные интенты.

Проверь сезонность по запросу "детский лагерь" за последний год по России. Дай вывод для маркетолога: когда спрос растёт и когда лучше запускать рекламу.

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

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

Больше примеров: examples/marketing-prompts.md.

Быстрая установка через агента

Скопируйте агенту эту фразу:

Установи Yandex Wordstat MCP из https://github.com/N1arko/yandex-wordstat-mcp. Поставь сервер локально через pipx, спроси у меня YC_SEARCH_API_KEY или YC_IAM_TOKEN и YC_FOLDER_ID, добавь сервер в конфиг текущего клиента и проверь вызовом wordstat_find_region(query="Москва").

Что нужно заранее

Нужны два значения из Yandex Cloud:

Что	Где взять
YC_SEARCH_API_KEY	API-ключ сервисного аккаунта со scope yc.search-api.execute
YC_FOLDER_ID	ID каталога Yandex Cloud

Можно использовать YC_IAM_TOKEN вместо YC_SEARCH_API_KEY.

Подробная инструкция по Yandex Cloud: docs/yandex-cloud-setup.md.

Как это выглядит в работе

Пользователь просит:

Проверь спрос на "онлайн психолог" по России и отдельно по Москве. Нужны выводы для рекламной кампании.

Агент вызывает инструменты Вордстата:

wordstat_find_region(query="Москва")
wordstat_top_requests(phrase="онлайн психолог", regions=["225"])
wordstat_top_requests(phrase="онлайн психолог", regions=["213"])
wordstat_dynamics(phrase="онлайн психолог", regions=["225"], period="PERIOD_MONTHLY", ...)

В ответ агент может собрать рабочий вывод:

• какие формулировки чаще используют;
• где запрос коммерческий, а где информационный;
• какие фразы стоит вынести в отдельные группы;
• когда спрос растёт;
• какие запросы выглядят как минус-слова.

Инструменты

Инструмент	Что делает
wordstat_top_requests	Возвращает популярные запросы и ассоциации по фразе
wordstat_dynamics	Возвращает динамику спроса по датам
wordstat_get_regions_tree	Возвращает дерево регионов Яндекса
wordstat_find_region	Находит ID региона по названию

По умолчанию используется Россия, регион 225. Для Москвы используйте ["213"].

Ручная установка

Установить пакет

python -m pip install --user pipx
python -m pipx ensurepath
pipx install git+https://github.com/N1arko/yandex-wordstat-mcp.git

Проверьте, что команда доступна:

Get-Command yandex-wordstat-mcp

Если Windows не находит команду, перезапустите терминал.

Подключить к Codex

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

[mcp_servers.yandex_wordstat]
command = "yandex-wordstat-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60

[mcp_servers.yandex_wordstat.env]
YC_SEARCH_API_KEY = "your-api-key-here"
YC_FOLDER_ID = "your-folder-id-here"

Пример: examples/codex-config.toml.

После настройки откройте новый чат или перезапустите Codex. В Codex можно проверить подключение через /mcp.

Подключить к Claude Desktop

Добавьте сервер в claude_desktop_config.json:

{
  "mcpServers": {
    "yandex_wordstat": {
      "command": "yandex-wordstat-mcp",
      "env": {
        "YC_SEARCH_API_KEY": "your-api-key-here",
        "YC_FOLDER_ID": "your-folder-id-here"
      }
    }
  }
}

Пример: examples/claude-desktop-config.json.

После изменения конфига перезапустите Claude Desktop.

Проверка

Сначала проверьте, что сервер видит регионы:

wordstat_find_region(query="Москва")

Потом проверьте запросы:

wordstat_top_requests(
  phrase="перевод документов",
  regions=["225"],
  limitResults=20
)

Если нужно проверить доступ из терминала:

python scripts/smoke_test.py

Smoke test требует реальные YC_SEARCH_API_KEY и YC_FOLDER_ID в окружении.

Если что-то не работает

Ошибка	Что проверить
Сервер не запускается	Python 3.10+, установка через pipx, доступность команды yandex-wordstat-mcp
Ошибка авторизации	API-ключ, IAM-токен, scope yc.search-api.execute
Нет доступа к API	роль сервисного аккаунта search-api.webSearch.user
Пустой или странный ответ	регион, формулировку запроса, операторы Вордстата
Codex или Claude не видит сервер	путь к конфигу, перезапуск клиента, список MCP-серверов

Для разработчиков

git clone https://github.com/N1arko/yandex-wordstat-mcp.git
cd yandex-wordstat-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
pytest
ruff check .

Структура репозитория

yandex-wordstat-mcp/
├── wordstat_mcp/
│   ├── server.py
│   ├── http_client.py
│   └── config.py
├── docs/
│   ├── agent-install-prompt.md
│   └── yandex-cloud-setup.md
├── examples/
│   ├── codex-config.toml
│   ├── claude-desktop-config.json
│   └── marketing-prompts.md
├── scripts/
│   └── smoke_test.py
├── tests/
├── README.md
└── LICENSE

Лицензия

MIT.