---
name: wordstat-keyword-research
description: Research Russian search demand with live Yandex Wordstat data — keyword lists, exact-phrase volumes, seasonality and regional split — through the Twelver MCP server. Use when the user asks how many people search for something in Russia or on Yandex, wants a semantic core / keyword list for SEO or Yandex Direct, compares niches or product ideas by demand, or asks about seasonality or regional interest (Вордстат, частотность, подбор ключевых слов, сезонность спроса).
license: MIT
metadata:
  author: Twelver
  homepage: https://twelver.ru/skills/ru/wordstat-keyword-research/
  version: "1"
---

# Yandex Wordstat keyword research

Yandex is the main search engine in Russia, and Wordstat is the only first-party
source of its query volumes. This skill turns a question about Russian demand into
numbers that are safe to act on.

## Connect the tools

The tools come from Twelver's remote MCP server (Streamable HTTP, one server per
toolset). No local install.

- URL: `https://twelver.ru/api/mcp/v1/wordstat` (accounts registered on
  twelver.ru) or `https://twelver.app/api/mcp/v1/wordstat` (twelver.app accounts).
  The two are separate account systems — use the one the key or login belongs to.
- Auth: OAuth sign-in (the client opens a browser; needs a registered account), or
  the header `Authorization: Bearer sk-…` with a key from `https://twelver.ru/api-keys`.
- Claude Code: `claude mcp add --transport http twelver-wordstat https://twelver.ru/api/mcp/v1/wordstat`

If none of the tools below are available, stop and tell the user how to connect
them. Do not guess volumes from memory. Made-up numbers are the most expensive
mistake this skill exists to prevent.

## Tools

| Tool | What it returns | Cost |
|---|---|---|
| `wordstat-get-top` | Top queries containing a phrase over the last 30 days, plus related queries | billed per call |
| `wordstat-get-dynamics` | Frequency of a phrase by month / week / day | billed per call |
| `wordstat-get-regions` | Split across Russian regions, with an affinity index (>100 = above-average interest) | billed per call |
| `wordstat-get-regions-tree` | Region name → numeric Yandex region ID (213 Moscow, 2 Saint Petersburg) | free |

The billed calls share a Yandex rate limit. If one is rejected for rate limiting,
wait a few seconds and retry once. Do not fire dozens of calls in a loop.

## Procedure

1. **Write the seed phrases in Russian, the way people type them.** Search
   queries are short, lowercase and colloquial: `удалить объект с видео`, not
   `удаление объектов из видеоматериалов`. Use 1–5 seeds that name the job, not
   the product category.
2. **Expand with `wordstat-get-top`** for each seed (`numPhrases` 50–200). This
   returns *broad-match* counts. Each count includes every longer query that
   contains the phrase, so the rows nest inside each other.
3. **Never add broad counts together.** `нейросеть` already contains
   `нейросеть для фото`, and summing them counts the same searches twice. To
   compare phrases, measure each one exactly (step 4).
4. **Measure exact demand with Wordstat operators** before quoting any number
   as "the volume" of a phrase:
   - `"купить велосипед"`: only queries made of exactly these words (in any
     form), with nothing extra. This is the real size of a head term.
   - `!купить !велосипед`: fixes the word form.
   - `[москва питер]`: fixes the word order.
   - `-бесплатно`: excludes a word. `(фото|видео)` groups alternatives.
   A broad count that is 20× the quoted count is a cluster of long-tail queries,
   not one keyword.
5. **Check intent before counting it as demand.** A bare brand or model name
   (`grok`, `wildberries`) is mostly people trying to reach that site, not
   buyers of an alternative. Commercial and how-to modifiers (`как`, `онлайн`,
   `бесплатно`, `купить`, `сделать`) carry the intent. Group the keyword list
   by intent (how-to, tool/online, buy, brand), not by alphabet.
6. **Seasonality with `wordstat-get-dynamics`.** Use `PERIOD_MONTHLY` over the
   last 24 months for a trend. Use `PERIOD_WEEKLY` for anything that launched or
   spiked recently. One month is noise: say "rising" only when the last 3 months
   beat the same 3 months a year earlier.
7. **Regions only when the user's business is local.** Resolve the city with
   `wordstat-get-regions-tree` (free) first, then pass its ID in `regions`. Use
   `wordstat-get-regions` to find where interest is concentrated.
8. **Report** as a table: phrase, exact volume (quoted form), broad volume,
   intent group, trend. Name the period (last 30 days, as of the call date) and
   the source (Yandex Wordstat). Give the recommendation first, then the table.

## Pitfalls

- Wordstat is Yandex only. It says nothing about Google, and nothing outside
  Russia and the CIS.
- Counts are searches per month, not people, and not clicks.
- A phrase under ~50 searches a month is within noise. Do not rank such
  phrases against each other.
- Latin and Cyrillic spellings are separate queries (`chatgpt` vs `чатгпт`).
  Check both for brand and model names.
- Do not re-query the same phrase with the same parameters within a
  conversation. Reuse the earlier result.

## Done when

The user has a keyword list grouped by intent, where every volume they would act
on was measured with the exact-match operator, and each trend claim is backed by a
dynamics call and names its period.