Content
# Yandex Wordstat MCP
[](https://www.npmjs.com/package/mcp-yandex-wordstat)
[](https://github.com/askads/mcp-yandex-wordstat/actions/workflows/ci.yml)
[](https://glama.ai/mcp/servers/askads/mcp-yandex-wordstat)
[](./LICENSE)
MCP server for **Yandex Wordstat**: query search query statistics - frequency, similar queries, seasonality, and geography - from Claude, Cursor, Codex, and other AI clients in natural language.
The assistant independently selects keywords, evaluates demand and its dynamics, and compares regions - what in the Wordstat web interface requires manual navigation through three tabs.
<img src="docs/demo.gif" alt="Demo: one question - the assistant calls top_requests, dynamics, and regions and collects frequency, seasonality, and top demand cities" width="1000">
<sub>Real MCP session: real server, handshake, and tools/call via stdio through the official SDK; Yandex Cloud Search API (Wordstat) responses - recorded fixtures (<a href="docs/demo">docs/demo</a>), so the demo is reproducible without a key and network - <a href="docs/demo.tape">vhs docs/demo.tape</a>.</sub>
## Quick Start
1. [Get an API key](#getting-access) for Yandex Cloud - the same type of key as for YandexGPT.
2. Add the server - for example, in Claude Code ([other clients](#installation)):
```bash
claude mcp add yandex-wordstat \
-e WORDSTAT_API_KEY=your_key -e WORDSTAT_FOLDER_ID=your_folder \
-- npx -y mcp-yandex-wordstat
```
3. Ask the assistant: "How many times a month do people search for 'buy a bike' and what are some similar queries?"
## Capabilities
- **Top and similar queries** - `top_requests`: popular queries with the phrase + semantically close (`associations`) and total volume for 30 days.
- **Dynamics** - `dynamics`: a series of `{date, count, share}` by day/week/month - seasonality and trend.
- **Regions** - `regions`: distribution of demand by regions with `affinityIndex` (where interest is higher/lower than average); modes `all` / `cities` / `regions`.
- **Region directory** - `list_regions`: tree `id → name` for filters and region decoding.
- **Universal `raw_request`** - direct call to any API path.
- **Yandex Cloud Search API v2** - auth, endpoints, and schemes are hidden behind normalized tools.
- **Fault tolerance** - retries on 429/5xx with backoff and request timeout.
## Query Examples
Ask the assistant in Russian - for example:
- "How many times a month do people search for 'buy a bike' and what are some similar queries?"
- "Show the seasonality of demand for 'skis' by month for a year"
- "In which cities is interest in 'pizza delivery' the highest?"
- "Select keys around 'apartment repair' with frequency"
## API Access
The server works through **Yandex Cloud Search API v2** (host `searchapi.api.cloud.yandex.net`, authorization by Yandex Cloud API key). Wordstat data is public aggregated demand statistics (not tied to an advertising account), so one API key serves the entire server. Self-service is available, using the same key as YandexGPT - no applications or active campaigns are required.
> **The old separate Wordstat API (`api.wordstat.yandex.net`, OAuth) is no longer available.** Yandex has moved this functionality to Yandex Search API on the Yandex Cloud platform (this is the backend of the server); the web version remains separate on [wordstat.yandex.ru](https://wordstat.yandex.ru). Support for the `oauth` flavor has been removed in version 2.0.0.
## Installation
<details open>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add yandex-wordstat \
-e WORDSTAT_API_KEY=your_key -e WORDSTAT_FOLDER_ID=your_folder \
-- npx -y mcp-yandex-wordstat
```
Or through the plugin marketplace - the token will be requested by the dialog when enabled and saved in the system keychain (not in the config in plain text):
```
/plugin marketplace add askads/claude-plugins
/plugin install yandex-wordstat@askads
```
</details>
<details>
<summary><b>Claude Desktop</b></summary>
`claude_desktop_config.json` - macOS `~/Library/Application Support/Claude/`, Windows `%APPDATA%\Claude\`
```json
{
"mcpServers": {
"yandex-wordstat": {
"command": "npx",
"args": ["-y", "mcp-yandex-wordstat"],
"env": { "WORDSTAT_API_KEY": "your_key", "WORDSTAT_FOLDER_ID": "your_folder" }
}
}
}
```
</details>
<details>
<summary><b>Cursor</b></summary>
`~/.cursor/mcp.json` (or `.cursor/mcp.json` in the project)
```json
{
"mcpServers": {
"yandex-wordstat": {
"command": "npx",
"args": ["-y", "mcp-yandex-wordstat"],
"env": { "WORDSTAT_API_KEY": "your_key", "WORDSTAT_FOLDER_ID": "your_folder" }
}
}
}
```
</details>
<details>
<summary><b>VS Code</b></summary>
`.vscode/mcp.json` - key `servers` (not `mcpServers`)
```json
{
"servers": {
"yandex-wordstat": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-yandex-wordstat"],
"env": { "WORDSTAT_API_KEY": "your_key", "WORDSTAT_FOLDER_ID": "your_folder" }
}
}
}
```
</details>
## Getting Access
1. Create a service account with the `search-api.webSearch.user` role and obtain an API key with the `yc.search-api.execute` scope - see [AI Studio documentation](https://yandex.cloud/en/docs/ai-studio/operations/get-api-key).
2. Find out the `folderId` - the catalog ID is visible in the [Yandex Cloud console](https://console.yandex.cloud/) on the catalog page (and in its URL).
3. Write the key in `WORDSTAT_API_KEY`, the catalog - in `WORDSTAT_FOLDER_ID`.
⚠️ The key is stored **in plain text** in the client config - treat it like a password.
## Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
| `WORDSTAT_API_KEY` | yes | - | Yandex Cloud API key (Search API). |
| `WORDSTAT_FOLDER_ID` | yes | - | Yandex Cloud catalog ID. |
| `WORDSTAT_LANG` | no | `ru` | `Accept-Language` header. |
| `WORDSTAT_API_BASE` | no | `https://searchapi.api.cloud.yandex.net` | API root (override). |
| `WORDSTAT_TIMEOUT_MS` | no | `60000` | Request timeout, ms. |
| `WORDSTAT_MAX_RETRIES` | no | `3` | Retries on 429/5xx. |
## Requirements
- Node.js 20+ (launched via `npx`, no separate installation required).
- Access to Yandex Cloud Search API - see [Getting Access](#getting-access).
## Limitations
- **Read-only.** Wordstat API has no modifying operations - the server only reads.
- **General quota.** The limit (by Yandex Cloud Search API billing) is considered for one key, common for all calls. Cache `list_regions` and responses by phrases, do not drive frequency.
## Documentation
- [All tools](https://github.com/askads/mcp-yandex-wordstat/blob/main/docs/TOOLS.md) - complete list with description.
- [Development](https://github.com/askads/mcp-yandex-wordstat/blob/main/docs/DEVELOPMENT.md) - build, tests, smoke check.
- [Publishing](https://github.com/askads/mcp-yandex-wordstat/blob/main/docs/PUBLISHING.md) - release and listing in MCP directories.
## See Also
- **[Ask Ads](https://askads.ru)** - chat-analytic and "Guardian" of advertising cabinets from the authors of this server: alerts about budget drains and tracking breakdowns - in Telegram.
- **[askads/claude-plugins](https://github.com/askads/claude-plugins)** - Claude plugin marketplace: Ask Ads servers are installed with one command, tokens are requested when enabled.
## Support
Questions, ideas, and improvements - write in Telegram: [@gistrec](http://t.me/gistrec).
## License
MIT - see [LICENSE](./LICENSE).
