# Yandex Wordstat [Health: Active]

**Category:** 🎯 Marketing  
**Repository:** https://github.com/askads/mcp-yandex-wordstat  
**GitHub Stars:** 9  
**npm Downloads (last month):** 1587  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/yandex-wordstat

## Description
MCP server for Yandex Wordstat API: top & related queries, demand dynamics and regions.

## Tools
Capabilities this server exposes over MCP:

- **top_requests** — Возвращает поисковый спрос по фразе за последние 30 дней: самые популярные запросы, которые СОДЕРЖАТ фразу (results), и семантически ПОХОЖИЕ запросы, которые могут её не содержать (associations), плюс totalCount. Подходит для подбора ключевых фраз и оценки спроса. Значения счётчиков могут приходить строками (int64). Необязательные regionIds и devices сужают выборку; numPhrases задаёт, сколько фраз вернуть (1..2000).
- **dynamics** — Возвращает, как менялся спрос на фразу во времени, — ряд {date, count, share}, где share — доля от всех поисковых запросов Яндекса. Подходит для оценки сезонности и тренда. period задаёт шаг ряда (daily/weekly/monthly). fromDate/toDate ограничивают диапазон метками времени RFC3339, при этом toDate должен попадать на границу периода.
- **regions** — Возвращает, как спрос на фразу распределён по регионам за последние 30 дней. В каждой строке — id региона, count, share и affinityIndex (>100% — интерес в регионе выше среднего, <100% — ниже). regionMode выбирает группировку: all, cities (только города) или regions (только области и субъекты). Сопоставить id регионов с названиями помогает list_regions.
- **list_regions** — Возвращает справочное дерево регионов, которые поддерживает Вордстат, — id регионов и их названия (label). Эти id подставляются в regionIds/regionMode остальных инструментов, а названия расшифровывают id регионов в их ответах. Дерево большое и стабильное: достаточно запросить его один раз и закешировать.
- **raw_request** — Универсальный запрос: обращается напрямую к любому пути Wordstat в Yandex Cloud Search API — для эндпоинтов, у которых нет отдельного инструмента, например "v2/wordstat/topRequests". Все эндпоинты Вордстата работают методом POST; `body` отправляется как JSON (folderId подставляется автоматически).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "yandex-wordstat": {
    "command": "npx",
    "args": ["-y","mcp-yandex-wordstat@latest"],
    "env": {
      "WORDSTAT_API_KEY": "",
      "WORDSTAT_FOLDER_ID": ""
    }
  }
}
```

**Requires environment variables:** `WORDSTAT_API_KEY`, `WORDSTAT_FOLDER_ID` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Yandex Wordstat does

Yandex Wordstat provides an MCP interface to aggregated Yandex search-demand data. Its main use is researching a phrase: identify popular queries that contain it, discover semantically related queries, measure demand over time, and compare interest between regions. Top-query and regional reports cover the most recent 30 days, while historical analysis is available through configurable time-series intervals.

The server does not manage advertising campaigns or create keywords, ads, or other account objects. Although requests use HTTP POST, the exposed Wordstat operations are read-only. It also avoids the legacy standalone Wordstat API with Direct OAuth and instead uses Yandex Cloud Search API v2.

## How it works

An AI client starts the server over stdio and supplies a phrase or other tool parameters. The server sends requests to Yandex Cloud Search API, automatically adding the configured folder ID. `top_requests` returns matching and associated queries, their counts, and `totalCount`; `dynamics` returns `{date, count, share}` points; and `regions` reports counts, shares, and regional affinity. Counts may be returned as strings because large integers are represented that way in JSON.

Region filtering accepts region IDs and device selections can narrow reports to computers, phones, or tablets. The `period` parameter for dynamics supports daily, weekly, and monthly series. Date bounds use RFC3339 timestamps, with the end date aligned to the selected period. A single call analyzes one phrase.

`list_regions` supplies the region ID and name hierarchy used by other tools. The hierarchy is large and stable, so a long-running process can request it once and reuse the result. `raw_request` sends JSON to another Wordstat path when a dedicated tool is not available; it is restricted to the Yandex Cloud Search API host.

## Setup and configuration

Use Node.js 20 or newer and run the package with `npx -y mcp-yandex-wordstat@latest`. Configure these environment variables in the MCP client:

- `WORDSTAT_API_KEY`: an API key for Yandex Cloud Search API.
- `WORDSTAT_FOLDER_ID`: the Yandex Cloud folder ID used for requests.

Access requires a Yandex Cloud service account with the `search-api.webSearch.user` role. The API key should have the `yc.search-api.execute` scope. Treat the key as a password because MCP client configuration may store it in plain text.

The documented stdio configuration works with Codex, Claude Code, Claude Desktop, Cursor, and VS Code. Each client passes the two environment variables to the `npx` command. The server retries temporary failures, including rate limits, server errors, network failures, and timeouts, up to three times while observing `Retry-After` where available.

## Tools and capabilities

- `top_requests` returns popular queries containing the phrase, semantically similar associations, and a total count. Optional region IDs, devices, and a phrase limit from 1 to 2,000 refine the result.
- `dynamics` shows demand by day, week, or month, including each interval's count and share of all Yandex searches.
- `regions` groups the last 30 days of demand across all regions, cities, or administrative regions. An affinity index above 100% indicates above-average interest.
- `list_regions` resolves supported region IDs to names and provides the hierarchy for regional filters.
- `raw_request` supports Wordstat POST endpoints without a dedicated wrapper.

## Limitations and notes

Reports contain aggregated search statistics rather than data from a specific advertising account. The API quota is shared by requests made with the same key, so large keyword lists are better narrowed before querying. The server does not run background monitoring by itself; periodic reports depend on scheduling support in the connected AI application.

A request has a 60-second timeout. Regional reference data can be cached within a long-lived process. By default, the server sends anonymous installation, tool, runtime, operating-system, and client metadata for telemetry, along with limited tool-origin and error information.

_Full upstream README: https://allmcps.com/mcp/yandex-wordstat/readme_