Content
# Yandex Wordstat MCP
MCP server for working with Yandex Wordstat from Codex, Claude Desktop, and other agent clients.
After installation, you can ask the agent to check demand, collect similar queries, and view seasonality. Data is taken through the official Yandex Cloud Search API. Each user has their own Yandex Cloud key.
## What can be done
- Check the frequency of phrases.
- View similar queries and associations.
- Compare demand by regions.
- View dynamics by days, weeks, or months.
- Quickly find the Yandex region ID by name.
Examples of tasks:
```text
Check the demand for the query "coffee machine repair" in Moscow. Show the top of similar queries and remove unnecessary intents.
```
```text
Check the seasonality for the query "children's camp" for the last year in Russia. Give a conclusion for the marketer: when demand grows and when it's better to launch advertising.
```
```text
Collect primary semantics for the landing page "document translation". Commercial queries, similar formulations, and a separate list of minus words are needed.
```
For collecting semantics, I recommend asking the agent to use minus words. By default, they are not used.
More examples: [examples/marketing-prompts.md](examples/marketing-prompts.md).
## Quick installation via agent
Copy this phrase to the agent:
```text
Install Yandex Wordstat MCP from https://github.com/N1arko/yandex-wordstat-mcp. Set up the server locally via pipx, ask me for YC_SEARCH_API_KEY or YC_IAM_TOKEN and YC_FOLDER_ID, add the server to the config of the current client, and check by calling wordstat_find_region(query="Moscow").
```
## What you need in advance
You need two values from Yandex Cloud:
| What | Where to get |
|---|---|
| `YC_SEARCH_API_KEY` | API key of the service account with scope `yc.search-api.execute` |
| `YC_FOLDER_ID` | ID of the Yandex Cloud catalog |
You can use `YC_IAM_TOKEN` instead of `YC_SEARCH_API_KEY`.
Detailed instructions for Yandex Cloud: [docs/yandex-cloud-setup.md](docs/yandex-cloud-setup.md).
## How it looks in work
The user asks:
```text
Check the demand for "online psychologist" in Russia and separately in Moscow. Conclusions for the advertising campaign are needed.
```
The agent calls Wordstat tools:
```text
wordstat_find_region(query="Moscow")
wordstat_top_requests(phrase="online psychologist", regions=["225"])
wordstat_top_requests(phrase="online psychologist", regions=["213"])
wordstat_dynamics(phrase="online psychologist", regions=["225"], period="PERIOD_MONTHLY", ...)
```
In response, the agent can collect a working output:
- which formulations are used more often;
- where the query is commercial, and where it is informational;
- which phrases are worth taking out in separate groups;
- when demand grows;
- which queries look like minus words.
## Tools
| Tool | What it does |
|---|---|
| `wordstat_top_requests` | Returns popular queries and associations by phrase |
| `wordstat_dynamics` | Returns demand dynamics by dates |
| `wordstat_get_regions_tree` | Returns the tree of Yandex regions |
| `wordstat_find_region` | Finds the region ID by name |
By default, Russia, region `225`, is used. For Moscow, use `["213"]`.
## Manual installation
### Install the package
```powershell
python -m pip install --user pipx
python -m pipx ensurepath
pipx install git+https://github.com/N1arko/yandex-wordstat-mcp.git
```
Check that the command is available:
```powershell
Get-Command yandex-wordstat-mcp
```
If Windows does not find the command, restart the terminal.
### Connect to Codex
Add the server to `~/.codex/config.toml`:
```toml
[mcp_servers.yandex_wordstat]
command = "yandex-wordstat-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60
[mcp_servers.yandex_wordstat.env]
YC_SEARCH_API_KEY = "your-api-key-here"
YC_FOLDER_ID = "your-folder-id-here"
```
Example: [examples/codex-config.toml](examples/codex-config.toml).
After configuration, open a new chat or restart Codex. In Codex, you can check the connection via `/mcp`.
### Connect to Claude Desktop
Add the server to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"yandex_wordstat": {
"command": "yandex-wordstat-mcp",
"env": {
"YC_SEARCH_API_KEY": "your-api-key-here",
"YC_FOLDER_ID": "your-folder-id-here"
}
}
}
}
```
Example: [examples/claude-desktop-config.json](examples/claude-desktop-config.json).
After changing the config, restart Claude Desktop.
## Verification
First, check that the server sees regions:
```text
wordstat_find_region(query="Moscow")
```
Then check queries:
```text
wordstat_top_requests(
phrase="document translation",
regions=["225"],
limitResults=20
)
```
If you need to check access from the terminal:
```powershell
python scripts/smoke_test.py
```
Smoke test requires real `YC_SEARCH_API_KEY` and `YC_FOLDER_ID` in the environment.
## If something does not work
| Error | What to check |
|---|---|
| Server does not start | Python 3.10+, installation via `pipx`, availability of the `yandex-wordstat-mcp` command |
| Authorization error | API key, IAM token, scope `yc.search-api.execute` |
| No access to API | role of the service account `search-api.webSearch.user` |
| Empty or strange response | region, query formulation, Wordstat operators |
| Codex or Claude does not see the server | path to config, client restart, list of MCP servers |
## For developers
```powershell
git clone https://github.com/N1arko/yandex-wordstat-mcp.git
cd yandex-wordstat-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
pytest
ruff check .
```
## Repository structure
```text
yandex-wordstat-mcp/
├── wordstat_mcp/
│ ├── server.py
│ ├── http_client.py
│ └── config.py
├── docs/
│ ├── agent-install-prompt.md
│ └── yandex-cloud-setup.md
├── examples/
│ ├── codex-config.toml
│ ├── claude-desktop-config.json
│ └── marketing-prompts.md
├── scripts/
│ └── smoke_test.py
├── tests/
├── README.md
└── LICENSE
```
## License
MIT.
