Yandex Wordstat MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| WORDSTAT_LANG | No | Accept-Language header. | ru |
| WORDSTAT_TOKEN | No | OAuth token for api.wordstat.yandex.net (required for oauth flavor). | |
| WORDSTAT_FLAVOR | No | Backend flavor: cloud or oauth. | cloud |
| WORDSTAT_API_KEY | No | API key for Yandex Cloud (required for cloud flavor). | |
| WORDSTAT_API_BASE | No | Override API base URL. | |
| WORDSTAT_FOLDER_ID | No | Folder ID for Yandex Cloud (required for cloud flavor). | |
| WORDSTAT_TIMEOUT_MS | No | Request timeout in milliseconds. | 60000 |
| WORDSTAT_MAX_RETRIES | No | Number of retries on 429/5xx. | 3 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Яндекс Вордстат — агрегированная статистика поискового спроса в поиске Яндекса: как часто фразу набирают, когда и где. Это не Яндекс Директ: кампаний, объявлений, ставок, кликов и расхода тут нет, а данные не привязаны ни к какому рекламному аккаунту. Всё только на чтение: у API нет эндпоинтов записи, а raw_request работает только методом POST и не может уйти с хоста Search API. Один вызов — одна фраза, поэтому сравнение N ключевых фраз стоит N вызовов из квоты Yandex Cloud Search API — она считается на ключ и общая для всех вызовов. Дерево регионов кешируется в процессе, поэтому перечитывать его бесплатно. Диапазон дат принимает только dynamics; top_requests и regions всегда считают последние 30 дней. Значения count — int64 и часто приходят JSON-строками, а не числами. 429, 5xx и сетевые ошибки сервер сам повторяет до 3 раз с нарастающими паузами (не дольше 30 с каждая), поэтому такая ошибка в ответе означает, что повторы уже исчерпаны: немедленный повтор вряд ли поможет, а позже сбой может пройти. 401/403 означает, что у ключа нет доступа к Search API или WORDSTAT_FOLDER_ID указывает не на тот каталог, — это чинит оператор, дело не в фразе.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| top_requestsA | Возвращает поисковый спрос по фразе за последние 30 дней: самые популярные запросы, которые СОДЕРЖАТ фразу (results), и семантически ПОХОЖИЕ запросы, которые могут её не содержать (associations), плюс totalCount. Подходит для подбора ключевых фраз и оценки спроса. Значения счётчиков могут приходить строками (int64). Необязательные regionIds и devices сужают выборку; numPhrases задаёт, сколько фраз вернуть (1..2000). |
| dynamicsA | Возвращает, как менялся спрос на фразу во времени, — ряд {date, count, share}, где share — доля от всех поисковых запросов Яндекса. Подходит для оценки сезонности и тренда. period задаёт шаг ряда (daily/weekly/monthly); period и fromDate обязательны, значений по умолчанию у API нет. fromDate/toDate — метки времени RFC3339. Границы диапазона API сверяет по UTC и требует выравнивать по шагу: monthly — fromDate первое число месяца, toDate последний день месяца; weekly — fromDate понедельник, toDate воскресенье; daily — любые дни, но fromDate не старше 60 дней. Без toDate ряд идёт до последних доступных данных. |
| regionsA | Возвращает, как спрос на фразу распределён по регионам за последние 30 дней. В каждой строке — id региона, count, share и affinityIndex (>100% — интерес в регионе выше среднего, <100% — ниже). regionMode выбирает группировку: all, cities (только города) или regions (только области и субъекты). Сопоставить id регионов с названиями помогает list_regions. |
| list_regionsA | Возвращает справочное дерево регионов, которые поддерживает Вордстат, — id регионов и их названия (label). Эти id подставляются в regionIds инструментов top_requests и dynamics, а названия расшифровывают id регионов в их ответах. Дерево большое и стабильное: достаточно запросить его один раз и закешировать. |
| raw_requestA | Универсальный запрос: обращается напрямую к любому пути Wordstat в Yandex Cloud Search API — для эндпоинтов, у которых нет отдельного инструмента, например "v2/wordstat/topRequests". Все эндпоинты Вордстата работают методом POST; |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 5 tools
Each tool targets a distinct facet: top_requests (popular/similar queries), dynamics (time series), regions (geo distribution of demand), list_regions (region id→name reference), and raw_request (escape hatch). The main risk is confusing 'regions' with 'list_regions' due to near-identical names, and raw_request technically overlaps every other tool since it can call any endpoint. Descriptions mitigate this by scoping raw_request to endpoints without a dedicated tool.
All names are snake_case and readable, but conventions are mixed: some use a verb_noun form (list_regions), others are bare nouns (dynamics, regions, top_requests) or compound nouns (raw_request). The 'regions' vs 'list_regions' pair especially highlights the inconsistent verb-prefix usage for related concepts.
Five tools is within a sensible range and each maps to a real Wordstat capability (top queries, dynamics, geo, region reference, raw fallback). It is slightly lean, and raw_request is essentially a catch-all that duplicates the surface of the other tools, but overall the set is well-scoped.
The core keyword-research lifecycle is covered: query discovery (top_requests), trend analysis (dynamics), geographic breakdown (regions), region id resolution (list_regions), plus raw_request as an escape hatch preventing dead ends. Minor gaps exist (no dedicated device-only or dedicated endpoint tools), but the raw fallback lets agents work around them.