内容
# Yandex Wordstat MCP
MCP服务器，用于从Codex、Claude Desktop等代理客户端与Яндекс Вордстатом合作。
安装完成后，可以让代理检查需求，收集类似查询，查看季节性。数据通过官方的Yandex Cloud Search API获取。每个用户都有自己的Yandex Cloud密钥。
## 功能
- 检查短语的频率。
- 查看类似查询和关联。
- 比较不同地区的搜索需求。
- 查看按天、周或月计算的需求动态。
- 快速根据名称找到Яндекс地区的ID。
示例任务：
```text
查看在莫斯科查询“维修咖啡机”的需求。显示类似查询的热门榜单并移除无用意图。
```
```text
检查过去一年内查询“儿童营地”在俄罗斯的需求季节性。为市场营销人员提供输出：需求增长时以及何时适合投放广告。
```
```text
为“文件翻译”的着陆页收集初始语义。需要商业查询、类似措辞和独立的否定关键词列表。
```
为了收集语义，建议要求代理使用否定关键词。默认情况下不使用它们。
更多示例：[examples/marketing-prompts.md](examples/marketing-prompts.md)。
## 通过代理快速安装
将以下内容复制给代理：
```text
从 https://github.com/N1arko/yandex-wordstat-mcp 安装 Yandex Wordstat MCP。通过 pipx 在本地设置服务器，向我询问 YC_SEARCH_API_KEY 或 YC_IAM_TOKEN 和 YC_FOLDER_ID，将服务器添加到当前客户端的配置中，并通过 wordstat_find_region(query="Москва") 调用进行检查。
```
## 提前准备
需要从Yandex Cloud获取两个值：
| 名称 | 获取方式 |
|---|---|
| `YC_SEARCH_API_KEY` | 具有 `yc.search-api.execute` 作用域的服务账户 API 密钥 |
| `YC_FOLDER_ID` | Yandex Cloud 目录 ID |
可以使用 `YC_IAM_TOKEN` 代替 `YC_SEARCH_API_KEY`。
有关Yandex Cloud的详细说明：[docs/yandex-cloud-setup.md](docs/yandex-cloud-setup.md)。
## 工作中的表现
用户请求：
```text
检查“在线心理咨询”在俄罗斯和莫斯科的需求。为广告活动提供结论。
```
代理调用Wordstat工具：
```text
wordstat_find_region(query="Москва")
wordstat_top_requests(phrase="在线心理咨询", regions=["225"])
wordstat_top_requests(phrase="在线心理咨询", regions=["213"])
wordstat_dynamics(phrase="在线心理咨询", regions=["225"], period="PERIOD_MONTHLY", ...)
```
代理可以收集并返回：
- 哪些表达方式更常用；
- 哪里是商业查询，哪里是信息查询；
- 哪些短语应该单独分组；
- 需求何时增长；
- 哪些查询看起来像否定关键词。
## 工具
| 工具 | 功能 |
|---|---|
| `wordstat_top_requests` | 返回基于短语的热门查询和关联 |
| `wordstat_dynamics` | 返回按日期计算的需求动态 |
| `wordstat_get_regions_tree` | 返回Яндекс地区的树状结构 |
| `wordstat_find_region` | 按名称查找地区ID |
默认使用俄罗斯，地区ID为`225`。对于莫斯科，请使用`["213"]`。
## 手动安装
### 安装软件包
```powershell
python -m pip install --user pipx
python -m pipx ensurepath
pipx install git+https://github.com/N1arko/yandex-wordstat-mcp.git
```
检查命令是否可用：
```powershell
Get-Command yandex-wordstat-mcp
```
如果Windows找不到该命令，请重新启动终端。
### 连接到 Codex
在 `~/.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"
```
示例：[examples/codex-config.toml](examples/codex-config.toml).
配置完成后，打开新的聊天窗口或重启Codex。在Codex中，可以通过 `/mcp` 检查连接。
### 连接到 Claude Desktop
在 `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"
}
}
}
}
```
示例：[examples/claude-desktop-config.json](examples/claude-desktop-config.json).
修改配置后，重启Claude Desktop。
## 检查
首先，检查服务器是否能识别地区：
```text
wordstat_find_region(query="Москва")
```
然后，检查查询：
```text
wordstat_top_requests(
phrase="文件翻译",
regions=["225"],
limitResults=20
)
```
如果需要从终端检查访问权限：
```powershell
python scripts/smoke_test.py
```
Smoke test需要环境中真实的`YC_SEARCH_API_KEY`和`YC_FOLDER_ID`。
## 故障排除
| 错误 | 检查内容 |
|---|---|
| 服务器无法启动 | Python 3.10+，通过 `pipx` 安装，`yandex-wordstat-mcp` 命令可用性 |
| 授权错误 | API 密钥，IAM令牌，作用域 `yc.search-api.execute` |
| 无法访问API | 服务账户角色 `search-api.webSearch.user` |
| 空或异常响应 | 地区，查询表达式，Wordstat运算符 |
| Codex 或 Claude 看不到服务器 | 配置文件路径，客户端重启，MCP服务器列表 |
## 开发者
```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 .
```
## 仓库结构
```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
```
## 许可证
MIT.
