yandex-wordstat-mcp
Provides access to Yandex Wordstat keyword statistics through the Yandex Cloud Search API, including search volume, exact/base frequencies, trends over time, regional distribution, region lookup, and filters by region and device.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yandex-wordstat-mcp How many people search for "buy apartment" in Kazan from phones?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
yandex-wordstat-mcp
MCP-сервер для статистики Яндекс Вордстата. Через него Claude, Cursor и другие MCP-клиенты получают частотность запросов, динамику по времени и разбивку по регионам. Данные берутся из официального Search API в Yandex Cloud.
English: an MCP server for Yandex Wordstat keyword statistics (search volume, trends, regional split) via the official Yandex Cloud Search API. Setup is below; env vars and tool names are the same in any language.
Что умеет
Инструмент | Что возвращает |
| Сколько раз искали фразу за последние 30 дней, популярные запросы с этой фразой и похожие запросы |
| Базовую и точную частотность сразу для списка фраз — до 100 за один вызов |
| Изменение частотности по месяцам, неделям или дням и долю фразы среди всех запросов |
| Регионы или города, где ищут фразу, с индексом интереса: больше 100 — ищут чаще среднего |
| ID региона по названию для фильтров |
Фильтры: регионы (по ID или по точному названию — "Москва") и устройства (desktop, phone, tablet).
Во фразах работают операторы Вордстата: "кавычки" фиксируют набор слов, !слово — словоформу, +слово учитывает стоп-слова, -слово исключает слово.
Базовая и точная частотность
У одной фразы две частотности, и они отличаются в разы.
Базовая — все запросы, в которых есть слова фразы. В «карьерный коуч» попадают и «карьерный коуч онлайн», и «курсы карьерных коучей».
Точная — запросы только из этих слов в этих же словоформах. Сервер сам превращает фразу в
"!карьерный !коуч".
Пример: у «карьерный коуч» базовая частотность — 821 в месяц, точная — 37. Именно так запрос набирают 37 раз, остальное — более длинные запросы.
Когда решаете, нужна ли фразе отдельная страница, смотрите на точную частотность. frequencies возвращает обе цифры и долю точной в базовой:
{"phrase": "карьерный коуч", "base": 821, "exact": 37, "exact_share_percent": 4.5}На каждую фразу уходит до двух запросов к API. Если нужна одна цифра, передайте mode: "exact" или mode: "base" — запросов будет вдвое меньше. Во фразе может быть не больше 7 слов: для более длинной вернётся ошибка, остальные фразы посчитаются.
Примеры запросов к агенту:
Сколько ищут «купить квартиру» в Казани с телефонов?
Покажи сезонность запроса «шины зимние» по месяцам за два года.
В каких городах больше всего интересуются «ипотека для IT»?
Сравни точную частотность фраз «карьерный коуч», «бизнес коуч» и «коуч ICF» в Москве.
Related MCP server: Yandex Wordstat MCP
Что нужно
Аккаунт в Yandex Cloud с платёжным аккаунтом.
Сервисный аккаунт с ролью
search-api.editorв вашем каталоге.API-ключ для этого сервисного аккаунта, область действия
yc.search-api.execute.ID каталога — строка вида
b1g....uv.
Запросы к Вордстату платные и тарифицируются как запросы к Search API. Рекомендуем задать бюджет или квоту в консоли.
Установка
Claude Code
claude mcp add -s user wordstat \
-e YANDEX_SEARCH_API_KEY=ваш_ключ \
-e YANDEX_FOLDER_ID=ваш_folder_id \
-- uvx --from git+https://github.com/sergeiteterin/yandex-wordstat-mcp yandex-wordstat-mcpПерезапустите Claude Code и проверьте подключение командой /mcp.
Claude Desktop, Cursor и другие клиенты
{
"mcpServers": {
"wordstat": {
"command": "uvx",
"args": ["--from", "git+https://github.com/sergeiteterin/yandex-wordstat-mcp", "yandex-wordstat-mcp"],
"env": {
"YANDEX_SEARCH_API_KEY": "ваш_ключ",
"YANDEX_FOLDER_ID": "ваш_folder_id"
}
}
}
}Переменные окружения
Переменная | Обязательна | Описание |
| да* | API-ключ сервисного аккаунта |
| да* | IAM-токен вместо ключа. Живёт 12 часов, подходит для разовых запусков |
| да | ID каталога |
* Нужна одна из двух.
Что важно знать
Данные отстают на несколько недель. Если запросить слишком свежий период, API вернёт ошибку, и сервер подскажет сдвинуть даты.
Дневная статистика — только за последние 60 дней. Помесячная и понедельная доступны за несколько лет.
Даты выравниваются сами. Для недель — с понедельника по воскресенье, для месяцев — с 1-го по последнее число. API требует именно так.
share_percent— доля фразы среди всех запросов в Яндексе, в процентах.Ключ остаётся у вас. Сервер работает локально и обращается только к
searchapi.api.cloud.yandex.net. Ключ не пишется в логи и не попадает в сообщения об ошибках.
Разработка
git clone https://github.com/sergeiteterin/yandex-wordstat-mcp
cd yandex-wordstat-mcp
uv sync
uv run pytestТесты не ходят в сеть: ответы API подменяются через respx.
Чтобы проверить сервер вручную, запустите MCP Inspector:
YANDEX_SEARCH_API_KEY=... YANDEX_FOLDER_ID=... npx @modelcontextprotocol/inspector uv run yandex-wordstat-mcpЛицензия
MIT. Проект неофициальный и не связан с Яндексом.
Available Tools
5 toolsdynamicsARead-only
How search volume for a phrase changes over time. share_percent is the phrase's
share of all Yandex queries in that period. Dates are snapped automatically:
weeks to Monday–Sunday, months to the 1st and the last day.
Data lags by about a month; daily data covers only the last 60 days.
Inputs: phrase (required), period, devices, regions, +2 more. Returns: result
find_regionARead-only
Find Wordstat region IDs by name. Returns id, name and the path in the region tree.
Inputs: query (required), limit. Returns: result
frequenciesARead-only
Base and exact search volume over the last 30 days for a list of phrases in one call.
Use it to check real demand for specific wordings instead of calling top_requests per phrase.
base counts every query containing the words, so it is inflated by longer queries.
exact counts only queries made of exactly these words in these forms ("!word1 !word2") —
trust it when deciding whether a phrase deserves its own page. exact_share_percent is
exact / base. Each phrase costs up to 2 API requests (1 with mode "exact" or "base").
A phrase that fails gets an error field; the others are still returned.
Inputs: phrases (required), mode, devices, regions. Returns: result
regions_distributionBRead-only
Where people search for a phrase over the last 30 days. affinity_index > 100 means
the region searches for it more than average, < 100 less.
Inputs: phrase (required), limit, devices, region_type. Returns: result
top_requestsBRead-only
Search volume for a phrase over the last 30 days, plus the most popular queries containing it and similar ("associated") queries. Use for keyword research.
Inputs: phrase (required), devices, regions, num_phrases. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
The main overlap risk is between top_requests and frequencies, since both return 30-day search volume, but the descriptions clearly split them: top_requests for discovery (associated queries) and frequencies for batch base/exact checks. The remaining three tools (dynamics, regions_distribution, find_region) target time series, geography, and region lookup respectively, so intent is easy to infer.
All names use lowercase snake_case, which keeps formatting consistent. Semantically, four are noun-phrases naming the data returned (top_requests, frequencies, dynamics, regions_distribution) while find_region uses a verb_noun form, a minor stylistic deviation that is still readable.
Five tools is a well-scoped surface for a keyword-research API, with no redundant or filler endpoints. Each tool covers a distinct query dimension (volume, time, geography, region resolution).
The surface covers volume, base/exact frequency, trends over time, regional breakdown, and region ID resolution, which is close to full lifecycle for Wordstat research. Minor gaps remain, such as no explicit tool for comparing multiple phrases over time or fetching the full associated-query list separately from volume, but the core workflows are achievable with the given tools.
Maintenance
Related MCP Connectors
MCP servers for Yandex APIs: Wordstat, Search, Webmaster, Metrika, Direct. Open source, by Seyka AI.
Remote MCP server that gives Claude, ChatGPT, Cursor or any MCP client Google search volume, CPC, competition and similar keywords for 50+ countries. Works with no signup at 20 lookups a day; sign in with OAuth or an API key for higher limits, or $4.99 a month for unlimited.
Yandex search results, images, and SERP data via the Apify Yandex Search Scraper, hosted MCP.
Yandex rank tracking and bulk SERP data, billed per result, hosted MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceLocal-first MCP server for Yandex Webmaster that exposes tools for SEO operations including search query analytics, sitemap management, indexing history, recrawl quota, and diagnostics.15MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for querying Yandex Wordstat via Yandex Cloud Search API. Enables checking phrase frequency, similar queries, regional demand, and seasonality trends.2MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for the Yandex Wordstat v2 API, enabling keyword search volume queries, regional distribution, and trends analysis via Wordstat tools.MIT
- AlicenseAqualityCmaintenanceEnables collecting real Yandex Wordstat v2 data and running managed semantic-core research workflows, including query frequencies, regional demand, dynamics, and AI-assisted cleaning, intent labeling, clustering, and reporting.5MIT