Skip to main content
Glama
Yandex Wordstat MCP

Yandex Wordstat MCP

Яндекс Вордстат MCP

npm CI Glama License: MIT

Яндекс Вордстат MCP connects an AI application to Yandex search demand statistics. Ask how often a phrase is searched, in which months interest grows, and in which cities the topic is more popular — the assistant will collect Wordstat data and explain the result. The server works through Yandex Cloud Search API, so it does not require access to the Direct advertising account.

  • Five tools. Top and similar queries, demand dynamics, regional distribution, region reference, and a technical API request.

  • Read-only. The Wordstat API does not create campaigns, ads, key phrases, or other objects.

  • Demand and seasonality. Top queries and regions show the last 30 days; dynamics are built by day, week, or month for the desired period.

  • Region and device. Reports can be narrowed to a region and compare demand on computers, phones, and tablets.

  • No Direct OAuth. You need an API key and a Yandex Cloud folder ID for Search API.

Start with a safe request:

How many times a month is "buy a bike" searched, and what similar queries are there?

Connect the server · See scenarios · Open technical documentation


See it work in a minute

Related MCP server: Wordstat MCP

Contents

Quick start

You need Node.js 20 or newer, a Yandex Cloud API key for Search API, and a Yandex Cloud folder ID.

  1. Get access and add the server to your AI application — instructions for five applications below.

  2. Ask: "How many times a month is 'buy a bike' searched, and what similar queries are there?"

Through the application interface:

  1. Open Settings → Plugins → MCP servers.

  2. Click Add server.

  3. Add the launch command npx -y mcp-yandex-wordstat@latest and environment variables WORDSTAT_API_KEY, WORDSTAT_FOLDER_ID.

Through the command line:

codex mcp add yandex-wordstat \
  --env WORDSTAT_API_KEY=ваш_ключ \
  --env WORDSTAT_FOLDER_ID=ваш_folder_id \
  -- npx -y mcp-yandex-wordstat@latest

Check the connection:

codex mcp list

Official Codex instructions

claude mcp add \
  --env WORDSTAT_API_KEY=ваш_ключ \
  --env WORDSTAT_FOLDER_ID=ваш_folder_id \
  --transport stdio \
  --scope user \
  yandex-wordstat \
  -- npx -y mcp-yandex-wordstat@latest

Check the server:

claude mcp list

Claude Code documentation

Open Settings → Developer → Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "ваш_ключ",
        "WORDSTAT_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}

If Edit Config is unavailable, edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.

For all projects, create ~/.cursor/mcp.json; for the current project only, create .cursor/mcp.json:

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "ваш_ключ",
        "WORDSTAT_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}

Cursor documentation

Open the command palette and run MCP: Open User Configuration. Add to mcp.json:

{
  "servers": {
    "yandex-wordstat": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "${input:wordstat_api_key}",
        "WORDSTAT_FOLDER_ID": "${input:wordstat_folder_id}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "wordstat_api_key",
      "description": "API-ключ Yandex Cloud",
      "password": true
    },
    {
      "type": "promptString",
      "id": "wordstat_folder_id",
      "description": "ID каталога Yandex Cloud"
    }
  ]
}

Check the launch with the MCP: List Servers command.

VS Code documentation

What you can delegate

Find and evaluate demand

  • "How many times a month is this phrase searched, and what similar queries appear?"

  • "Find queries around 'pizza delivery' with their frequency."

  • "Show queries containing my phrase separately from semantically similar ones."

Understand seasonality

  • "Show demand for 'skis' by month for a year."

  • "In which weeks does demand for this service grow or fall?"

  • "Compare the dynamics of a query on phones and computers."

Compare regions

  • "In which cities is interest in 'apartment renovation' above average?"

  • "Compare demand in Moscow and St. Petersburg."

  • "Find the ID of the needed region and narrow the next report to it."

How to read demand data

top_requests shows popular queries that contain the given phrase and semantically close queries. The overall totalCount refers to the last 30 days.

dynamics returns a series {date, count, share} with daily, weekly, or monthly granularity. regions distributes demand over the last 30 days by region, and an affinityIndex above 100% means above-average interest. Counter values may come as strings: Yandex passes large integers in JSON in this form.

One call builds data for only one phrase. For a large list of keywords, it is better to first narrow the list rather than run all queries in a row: the Yandex Cloud Search API quota is shared for one key.

How to get access

  1. In Yandex Cloud, create a service account with the role search-api.webSearch.user.

  2. Issue an API key for it with the scope yc.search-api.execute — the steps are described in the AI Studio documentation.

  3. Find the folder ID (folderId) in the Yandex Cloud console on the folder page and in the page URL.

  4. Pass the key as WORDSTAT_API_KEY and the folder as WORDSTAT_FOLDER_ID.

The server accesses Yandex Cloud Search API v2. The old separate Wordstat API with OAuth is not used. The API key is stored in plain text in the MCP client configuration — treat it like a password.

What can change the data

Nothing in Яндекс Вордстат. All five tools, including raw_request, work read-only. Technically, the API uses POST, but Wordstat has no write endpoints; the server additionally does not allow an arbitrary request to go to another host.

Data, limits, and background work

  • Aggregated data. The server receives search demand statistics, not data from a specific advertising account.

  • Region reference cache. In a long-lived process, the region tree is loaded once and reused in subsequent requests.

  • Retries on temporary errors. The timeout for one request is 60 seconds. The server makes up to three retries after 429, 5xx, a network error, or a timeout; it respects Retry-After, and the delay does not exceed 30 seconds.

  • No background monitoring. The server works when the AI application calls it. If the application supports scheduled tasks, you can set up a periodic report for selected phrases there.

  • Anonymous telemetry. By default, the server sends a random installation ID, the event or tool name, server, Node.js, OS, and AI client versions. It does not include the API key, tool arguments, your messages, demand data, or environment variable values. To disable it for Ask Ads MCP servers: ASKADS_TELEMETRY=0.

Technical documentation

Support

Found a bug or missing a scenario? Create an issue or write to Telegram.

Available Tools

5 tools
dynamicsДинамика спроса во времениA
Read-onlyIdempotent

Возвращает, как менялся спрос на фразу во времени, — ряд {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 ряд идёт до последних доступных данных.

Inputs: period (required), phrase (required), fromDate (required), toDate, +2 more.

list_regionsСправочное дерево регионовA
Read-onlyIdempotent

Возвращает справочное дерево регионов, которые поддерживает Вордстат, — id регионов и их названия (label). Эти id подставляются в regionIds инструментов top_requests и dynamics, а названия расшифровывают id регионов в их ответах. Дерево большое и стабильное: достаточно запросить его один раз и закешировать.

Inputs: no named parameters.

raw_requestПрямой вызов API ВордстатаA
Read-onlyIdempotent

Универсальный запрос: обращается напрямую к любому пути Wordstat в Yandex Cloud Search API — для эндпоинтов, у которых нет отдельного инструмента, например "v2/wordstat/topRequests". Все эндпоинты Вордстата работают методом POST; body отправляется как JSON (folderId подставляется автоматически).

Inputs: path (required), body, method.

regionsРаспределение по регионамA
Read-onlyIdempotent

Возвращает, как спрос на фразу распределён по регионам за последние 30 дней. В каждой строке — id региона, count, share и affinityIndex (>100% — интерес в регионе выше среднего, <100% — ниже). regionMode выбирает группировку: all, cities (только города) или regions (только области и субъекты). Сопоставить id регионов с названиями помогает list_regions.

Inputs: phrase (required), regionMode.

top_requestsТоп и похожие запросыA
Read-onlyIdempotent

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

Inputs: phrase (required), devices, regionIds, numPhrases.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables keyword research and search trend analysis for the Russian market through Yandex Wordstat API. Provides access to popular search queries, search volume dynamics over time, and regional distribution data.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects Claude or ChatGPT to Yandex Wordstat for keyword research, enabling frequency lookups, related phrase suggestions with noise filtering, and 24-month seasonality analysis directly in chat.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to read Yandex Wordstat search query statistics, including top phrases, dynamics, regional distribution, and region code trees, via the Yandex Search API in a read-only manner.
      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