yandex-wordstat-mcp
by krutovvv
README.md
# yandex-wordstat-mcp
MCP-сервер Яндекс Вордстата: частотность запросов, сезонность и география спроса — прямо в Claude, Kimi Code,
Cursor и других MCP-клиентах. Работает через официальный Wordstat API в Yandex Cloud (Search API v2).
## Инструменты
| Инструмент | Что делает |
|---|---|
| `wordstat_top_requests` | Частотность фразы за последние 30 дней и что вокруг неё ищут: похожие и связанные запросы |
| `wordstat_dynamics` | Динамика частотности по дням, неделям или месяцам — сезонность и тренд |
| `wordstat_regions` | Где ищут фразу: страны, регионы или города, с индексом интереса (affinity) |
| `wordstat_find_region` | ID региона по названию — для параметра `regions` |
Сервер сам приводит параметры к формату API (устройства, периоды, уровни регионов, даты RFC3339, конец
месяца или недели), переводит числа из int64-строк в числа и повторяет запрос при ответе 429.
## Что нужно
- Node.js 18 или новее.
- **Ключ API Yandex Cloud** с областью действия `yc.search-api.execute` — у сервисного аккаунта с ролью
`search-api.webSearch.user` (консоль Yandex Cloud → Сервисные аккаунты → Создать API-ключ).
- **ID каталога** Yandex Cloud, в котором работает Search API.
## Подключение
Claude Code:
```bash
claude mcp add yandex-wordstat \
-e WORDSTAT_API_KEY=ваш_ключ -e WORDSTAT_FOLDER_ID=ваш_каталог \
-- npx -y @krutov.v.v/yandex-wordstat-mcp
```
Kimi Code, Claude Desktop, Cursor и другие клиенты — в настройках MCP (`mcp.json` и т. п.):
```json
{
"mcpServers": {
"yandex-wordstat": {
"command": "npx",
"args": ["-y", "@krutov.v.v/yandex-wordstat-mcp"],
"env": {
"WORDSTAT_API_KEY": "ваш_ключ",
"WORDSTAT_FOLDER_ID": "ваш_каталог"
}
}
}
}
```
## Переменные окружения
| Переменная | Обязательна | Что это |
|---|---|---|
| `WORDSTAT_API_KEY` | да | API-ключ Yandex Cloud (`yc.search-api.execute`) |
| `WORDSTAT_FOLDER_ID` | да | ID каталога Yandex Cloud |
## Примеры запросов
- «Какая частотность у "автообзвон" за месяц и что ещё ищут рядом?»
- «Покажи сезонность запроса "колл-центр на аутсорсе" по месяцам за два года»
- «В каких городах чаще всего ищут "виртуальная АТС"?»
## Лицензия
MIT