Skip to main content
Glama
N1arko

Yandex Wordstat MCP

by N1arko
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Remote

Yandex Wordstat MCP

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

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

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

  • Проверять частотность фраз.

  • Смотреть похожие запросы и ассоциации.

  • Сравнивать спрос по регионам.

  • Смотреть динамику по дням, неделям или месяцам.

  • Быстро находить ID региона Яндекса по названию.

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

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

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

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

Related MCP server: io.github.dontsovcmc/yandex-metrika

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

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

Установи 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.

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • yandex-mcp

    SvechaPVL
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for Yandex Direct, Metrika, Wordstat, and Webmaster APIs, providing 132 tools to manage advertising campaigns, analytics, keyword research, and reporting through any MCP-compatible client.
    59
    MIT

  • io.github.dontsovcmc/yandex

    dontsovcmc
    A
    license
    A
    quality
    D
    maintenance
    MCP server for Yandex Metrika API, enabling reporting, counter management, goals, filters, and other operations via natural language.
    12
    2
    MIT

  • Yandex Webmaster MCP

    askads
    A
    license
    A
    quality
    A
    maintenance
    MCP server for the Yandex Webmaster API, enabling natural-language queries about site indexing, search queries, IKS, diagnostics, sitemaps, and external links, as well as actions like recrawling, from AI assistants such as Claude, Cursor, and Codex.
    20
    80
    MIT