# Wordstat Readonly MCP

ИИ-помощник для статистики поисковых запросов Яндекса: топ фраз, динамика, регионы и дерево кодов Wordstat. Сервер только читает данные Search API. Изменить что-либо в Яндексе через этот MCP нельзя.

**[Установка на Ubuntu → DEPLOY.md](DEPLOY.md)** · [Примеры](USAGE.md) · [Инструкция для ИИ](AI_GUIDE.md) · [Каталог методов](CAPABILITIES.md)

## Что можно смотреть

| Инструмент | Метод API | Назначение |
|---|---|---|
| `wordstat_top` | GetTop | Топ популярных запросов с указанными словами за 30 дней |
| `wordstat_dynamics` | GetDynamics | Динамика частоты фразы по месяцам, неделям или дням |
| `wordstat_regions` | GetRegionsDistribution | Распределение запросов по регионам за 30 дней |
| `wordstat_regions_tree` | GetRegionsTree | Дерево кодов регионов Wordstat |
| `wordstat_status` | - | Конфигурация без раскрытия ключей |

Другие сервисы Yandex Cloud и любые мутации исключены.

## Как устроено

```text
ChatGPT Web
        ↓ OAuth 2.0 Authorization Code + PKCE S256
   Cloudflare Quick Tunnel или named tunnel
        ↓
  Ubuntu VPS → Wordstat Readonly MCP → ключ Search API
                                 → searchapi.api.cloud.yandex.net
```

Ключ Яндекса и `YANDEX_FOLDER_ID` хранятся только в `.env` на сервере и используются только для исходящих запросов к Search API. ChatGPT подключается к MCP через OAuth: на странице входа вводятся логин и пароль MCP, не ключ Яндекса. Для локального Cursor доступен запуск через stdio.

## Быстрый старт разработчика

Нужен Node.js 22 или новее.

```bash
git clone https://github.com/zimuspro156-lab/mcp-wordstat-readonly.git
cd mcp-wordstat-readonly
npm ci
npm test
npm run check
```

Секреты в чат и в Git не вставляйте. Для сервера используйте [DEPLOY.md](DEPLOY.md).

Исходный код - [MIT](LICENSE). Проект не является официальным продуктом Яндекса.