Skip to main content
Glama
yandex-wordstat-mcp

yandex-wordstat-mcp

yandex-wordstat-mcp

CI

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.

Что умеет

Инструмент

Что возвращает

top_requests

Сколько раз искали фразу за последние 30 дней, популярные запросы с этой фразой и похожие запросы

frequencies

Базовую и точную частотность сразу для списка фраз — до 100 за один вызов

dynamics

Изменение частотности по месяцам, неделям или дням и долю фразы среди всех запросов

regions_distribution

Регионы или города, где ищут фразу, с индексом интереса: больше 100 — ищут чаще среднего

find_region

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

Что нужно

  1. Аккаунт в Yandex Cloud с платёжным аккаунтом.

  2. Сервисный аккаунт с ролью search-api.editor в вашем каталоге.

  3. API-ключ для этого сервисного аккаунта, область действия yc.search-api.execute.

  4. ID каталога — строка вида b1g....

  5. 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"
      }
    }
  }
}

Переменные окружения

Переменная

Обязательна

Описание

YANDEX_SEARCH_API_KEY

да*

API-ключ сервисного аккаунта

YANDEX_IAM_TOKEN

да*

IAM-токен вместо ключа. Живёт 12 часов, подходит для разовых запусков

YANDEX_FOLDER_ID

да

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 tools
dynamicsA
Read-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_regionA
Read-only

Find Wordstat region IDs by name. Returns id, name and the path in the region tree.

Inputs: query (required), limit. Returns: result

frequenciesA
Read-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_distributionB
Read-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_requestsB
Read-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

    A3.7/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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).

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Local-first MCP server for Yandex Webmaster that exposes tools for SEO operations including search query analytics, sitemap management, indexing history, recrawl quota, and diagnostics.
      15
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for querying Yandex Wordstat via Yandex Cloud Search API. Enables checking phrase frequency, similar queries, regional demand, and seasonality trends.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      5
      MIT