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.git
cd yandex-mcp && bun install
node 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

| Variable | Required | Description | |----------|----------|-------------| | WORDSTAT_API_KEY | Yes | Yandex Cloud API key (secret, AQVN...) of a service account | | WORDSTAT_FOLDER_ID | Yes | Yandex Cloud folder ID (b1g...) used for billing and access checks |

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.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | depth | number | No | 3 | Maximum tree depth (1-5) |

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.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | regionId | number | Yes | -- | Region ID to get children for | | depth | number | No | 2 | Maximum subtree depth (1-3) |

top-requests

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

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | phrase | string | Yes | -- | Keyword or phrase to search for (max 400 chars) | | regions | number[] | No | -- | Region IDs to filter by | | devices | enum[] | No | -- | Device types: desktop, phone, tablet | | limit | number | No | 100 | Max phrases in response (1-2000) |

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

dynamics

Analyze search volume trends over time for a keyword.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | phrase | string | Yes | -- | Keyword or phrase (max 400 chars) | | period | enum | No | monthly | Aggregation: daily, weekly, monthly | | fromDate | string | No | auto | Start date (YYYY-MM-DD) | | toDate | string | No | auto | End date (YYYY-MM-DD) | | regions | number[] | No | -- | Region IDs | | devices | enum[] | No | -- | Device types: desktop, phone, tablet |

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

| Period | Rule | |--------|------| | daily | fromDate must be within the last 60 days — exactly 60 days back is rejected | | weekly | fromDate must be a Monday, toDate a Sunday, and the week must be over | | monthly | fromDate must be the 1st of a month, toDate the last day, and the month must be over |

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.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | phrase | string | Yes | -- | Keyword or phrase (max 400 chars) | | regions | number[] | No | -- | Region IDs to filter (client-side, includes descendants) | | devices | enum[] | No | -- | Device types: desktop, phone, tablet | | limit | number | No | 20 | Maximum results (1-50) |

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