# Yandex Wordstat MCP

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

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

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

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

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

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

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

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

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

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

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

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

```text
Установи 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](docs/yandex-cloud-setup.md).

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

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

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

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

```text
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"]`.

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

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

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

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

```powershell
Get-Command yandex-wordstat-mcp
```

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

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

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

```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](examples/codex-config.toml).

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

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

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

```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](examples/claude-desktop-config.json).

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

## Проверка

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

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

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

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

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

```powershell
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-серверов |

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

```powershell
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 .
```

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

```text
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.