# Яндекс Вордстат: Топ и похожие запросы — MCP-инструмент (tool)

**MCP-инструмент (tool) для Яндекс Вордстата:** Возвращает поисковый спрос по фразе за последние 30 дней: самые популярные запросы, которые СОДЕРЖАТ фразу (results), и семантически ПОХОЖИЕ запросы, которые могут её не содержать (associations), плюс totalCount.

Техническое имя: `top_requests`

## Какую задачу решает

> Я хочу получить поисковый спрос по фразе за последние 30 дней.

Возвращает поисковый спрос по фразе за последние 30 дней: самые популярные запросы, которые СОДЕРЖАТ фразу (results), и семантически ПОХОЖИЕ запросы, которые могут её не содержать (associations), плюс totalCount.

## Когда использовать

Используйте эту возможность, когда нужен результат «Топ и похожие запросы» без ручной работы в интерфейсе Яндекс Вордстата. Операция выполняется только по вызову из AI-приложения.

## Что нужно передать

- `phrase` — **обязательно**. Поисковая фраза для анализа, например «купить велосипед».
- `regionIds` — **необязательно**. Id регионов, которыми ограничить спрос, например [213] (Москва), [2] (Санкт-Петербург). Id берутся из list_regions. Без параметра — все регионы.
- `devices` — **необязательно**. Фильтр по устройствам: любые из all, desktop, phone, tablet. Без параметра — все устройства.
- `numPhrases` — **необязательно**. Сколько топовых фраз вернуть (1..2000; по умолчанию 20).

## Что вернёт

Возвращает поисковый спрос по фразе за последние 30 дней: самые популярные запросы, которые СОДЕРЖАТ фразу (results), и семантически ПОХОЖИЕ запросы, которые могут её не содержать (associations), плюс totalCount.

## Что изменится в Яндекс Вордстате

Инструмент только читает данные или состояние подключения и не изменяет их.

## Пример запроса

> Получить поисковый спрос по фразе за последние 30 дней в Яндекс Вордстате. Если не хватает обязательных идентификаторов, сначала уточни их.

## Возможные ошибки и ограничения

Подходит для подбора ключевых фраз и оценки спроса. Значения счётчиков могут приходить строками (int64). Необязательные regionIds и devices сужают выборку; numPhrases задаёт, сколько фраз вернуть (1..2000).

Доступ также зависит от прав токена, квот и ограничений исходного API.

## Связанные MCP-инструменты

- [Динамика спроса во времени](./dynamics.md) — `dynamics`
- [Справочное дерево регионов](./list-regions.md) — `list_regions`
- [Распределение по регионам](./regions.md) — `regions`

## Технические сведения

- **Воздействие:** только чтение
- **Группа:** Поисковый спрос
- **Источник описания:** регистрация `top_requests` в `src/tools/wordstat.ts`
- [Полный технический справочник](../TOOLS.md)
- [Все MCP-возможности](./index.md)