Yandex Wordstat MCP

yandex-wordstat-mcp

MCP server for Yandex Wordstat via Yandex Cloud Search API v2. Research keywords, analyze search volume trends, and explore regional search distribution for Russian and CIS markets.

v2.0: the legacy api.wordstat.yandex.net API was shut down by Yandex in 2026. The server now talks to searchapi.api.cloud.yandex.net/v2/wordstat/* and authenticates with a Yandex Cloud API key instead of an OAuth token. Tool names and parameters are unchanged.

Installation

This package is published as @stufently/yandex-wordstat-mcp; the unscoped name yandex-wordstat-mcp belongs to an unrelated publisher (see the note in the root README). Nothing is on the scope yet, so run it from source:

git clone https://github.com/stufently/yandex-mcp.gitcd yandex-mcp && bun installnode packages/yandex-wordstat-mcp/src/index.mjs

Configuration

Add to your MCP client config:

{  "mcpServers": {    "yandex-wordstat": {      "command": "node",      "args": ["/path/to/yandex-mcp/packages/yandex-wordstat-mcp/src/index.mjs"],      "env": {        "WORDSTAT_API_KEY": "AQVN...",        "WORDSTAT_FOLDER_ID": "b1g..."      }    }  }}

Alternatively, put the credentials into ~/.config/yandex-cloud/wordstat.env (used as a fallback when the env vars are not set):

WORDSTAT_API_KEY=AQVN...WORDSTAT_FOLDER_ID=b1g...

Environment Variables

Authentication (how to get the key)

1. Sign in to the Yandex Cloud console and pick (or create) a folder — its ID is visible in the URL: console.yandex.cloud/folders/<folderId>/.... A billing account must be linked to the cloud.
2. Create a service account in that folder with the search-api.webSearch.user role.
3. Open the service account → Create new key → API key, scope yc.search-api.execute.
4. Copy the secret (shown once) into WORDSTAT_API_KEY; the key identifier (ajel...) is only needed to rotate or revoke the key later.

Rate Limiting

The server enforces a client-side rate limit of 10 requests per second using a sliding window. Requests exceeding the limit are automatically queued. Additionally, 429 and 5xx responses trigger automatic retry with exponential backoff.

Tool Reference

get-regions-tree

Get the Yandex Wordstat regions hierarchy tree.

Returns a tree of regions with value (region ID), label (name), and children.

get-region-children

Get children of a specific region from the cached tree. Does not make an API call -- works from the cached region tree.

top-requests

Find popular search queries containing a keyword (last 30 days), plus associated queries.

Returns { topRequests: [{ phrase, count }], associations: [{ phrase, count }], totalCount } sorted by search volume.

dynamics

Analyze search volume trends over time for a keyword.

The API enforces window rules that are documented nowhere and are returned as raw gRPC errors when broken (verified against the live API on 2026-07-29):

Dates you pass are snapped to the nearest valid window instead of being rejected; every shift is listed in adjustments in both the text summary and structuredContent. A range that falls inside a single week or month expands to that whole period. A range that covers only the current, unfinished week or month cannot be served at all — the API rejects it — so the tool says so and names the latest available toDate instead of forwarding a 400.

Default date ranges by period:

• daily: last 58 days (kept one day inside the limit so a request never expires on a UTC date rollover)
• weekly: last 52 full weeks, Monday to Sunday
• monthly: last 12 full months, 1st to end of month

All date math is done in UTC.

Returns an array of { date, count, share } data points.

regions

Get regional distribution of search interest for a keyword.

Returns an array of { regionId, regionName, count, share, affinityIndex } sorted by count. Region names are enriched from the cached region tree.

Caching

The region tree is fetched once on the first call to get-regions-tree, get-region-children, or regions, and cached for the entire server session. A flat lookup map is built for O(1) region name resolution.

License

MIT