Skip to main content
Glama
yandex-wordstat-mcp

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