内容
# 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服务器，用于 **Yandex Wordstat（Яндекс Вордстат）**：查询搜索需求统计 - 搜索频率、相似查询、季节性和地理分布 - 来自Claude、Cursor、Codex和其他AI客户端的自然语言。
助手自动选择关键词，评估需求及其动态，并比较地区 - 在Wordstat网页上需要手动浏览三个选项卡。
<img src="docs/demo.gif" alt="演示：一个问题 - 助手调用top_requests、dynamics和regions，并收集搜索频率、季节性和需求最高的城市" width="1000">
<sub>真正的MCP会话：实时服务器、握手和通过官方SDK的stdio进行tools/call；Yandex Cloud Search API（Wordstat）的响应 - 记录的fixture（<a href="docs/demo">docs/demo</a>），因此演示可以在没有密钥和网络的情况下重现 - <a href="docs/demo.tape">vhs docs/demo.tape</a>.</sub>
## 快速开始
1. [获取Yandex Cloud API密钥](#获取访问权限) - 与YandexGPT使用的密钥类型相同。
2. 添加服务器 - 例如，在Claude Code中（[其他客户端](#安装)）：
```bash
claude mcp add yandex-wordstat \
-e WORDSTAT_API_KEY=您的密钥 -e WORDSTAT_FOLDER_ID=您的目录 \
-- npx -y mcp-yandex-wordstat
```
3. 向助手提问：“每月有多少人搜索'购买自行车'，有哪些类似的查询？”
## 功能
- **热门和相似查询** - `top_requests`：包含短语的热门查询 + 语义相似的查询（`associations`）和30天的总搜索量。
- **动态** - `dynamics`：按天/周/月排列的搜索量 - 季节性和趋势。
- **地区** - `regions`：按地区分布的需求，附带亲和力指数（`affinityIndex`）（兴趣高于或低于平均水平）；`all` / `cities` / `regions`模式。
- **地区目录** - `list_regions`：用于筛选和解码地区的`id → name`树。
- **通用`raw_request`** - 直接调用任何API路径。
- **Yandex Cloud Search API v2** - 认证、端点和模式隐藏在规范化工具后面。
- **容错性** - 带有回退和超时设置的429/5xx重试。
## 查询示例
用中文向助手提问 - 例如：
- “每月有多少人搜索'购买自行车'，有哪些类似的查询？”
- “显示'滑雪'需求的月度季节性”
- “哪些城市对'披萨外卖'的兴趣最高？”
- “围绕'房屋装修'选择具有搜索量的关键词”
## API访问
服务器通过 **Yandex Cloud Search API v2** （主机`searchapi.api.cloud.yandex.net`，使用Yandex Cloud API密钥授权）。Wordstat的数据是公开的聚合搜索统计数据（不与广告账户绑定），因此一个API密钥可用于整个服务器。
自助服务可用，与YandexGPT使用的密钥相同 - 无需申请或活跃的广告活动。
> **旧版独立Wordstat API（`api.wordstat.yandex.net`，OAuth）不再可用。** Яндекс已将此功能转移到Yandex Cloud上的Yandex Search API（这是服务器的后端）；网页版保留在[wordstat.yandex.ru](https://wordstat.yandex.ru)。`oauth`版本的支持已在2.0.0版本中删除。
## 安装
<details open>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add yandex-wordstat \
-e WORDSTAT_API_KEY=您的密钥 -e WORDSTAT_FOLDER_ID=您的目录 \
-- npx -y mcp-yandex-wordstat
```
或者通过插件市场 - 启用时将通过对话框询问令牌并保存在系统密钥链中（不以明文存储在配置文件中）：
```
/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": "您的密钥", "WORDSTAT_FOLDER_ID": "您的目录" }
}
}
}
```
</details>
<details>
<summary><b>Cursor</b></summary>
`~/.cursor/mcp.json`（或项目中的`.cursor/mcp.json`）
```json
{
"mcpServers": {
"yandex-wordstat": {
"command": "npx",
"args": ["-y", "mcp-yandex-wordstat"],
"env": { "WORDSTAT_API_KEY": "您的密钥", "WORDSTAT_FOLDER_ID": "您的目录" }
}
}
}
```
</details>
<details>
<summary><b>VS Code</b></summary>
`.vscode/mcp.json` - 关键字`servers`（不是`mcpServers`）
```json
{
"servers": {
"yandex-wordstat": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-yandex-wordstat"],
"env": { "WORDSTAT_API_KEY": "您的密钥", "WORDSTAT_FOLDER_ID": "您的目录" }
}
}
}
```
</details>
## 获取访问权限
1. 创建具有`search-api.webSearch.user`角色的服务账户，并为其获取具有`yc.search-api.execute`范围的API密钥 - 请参阅 [AI Studio文档](https://yandex.cloud/ru/docs/ai-studio/operations/get-api-key)。
2. 获取`folderId` - 目录ID在 [Yandex Cloud控制台](https://console.yandex.cloud/) 的目录页面（及其URL）中可见。
3. 将密钥记录在`WORDSTAT_API_KEY`中，将目录记录在`WORDSTAT_FOLDER_ID`中。
⚠️ 密钥以**明文**存储在客户端配置文件中 - 请像密码一样对待。
## 配置
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `WORDSTAT_API_KEY` | 是 | - | Yandex Cloud（Search API）API密钥。 |
| `WORDSTAT_FOLDER_ID` | 是 | - | Yandex Cloud目录ID。 |
| `WORDSTAT_LANG` | 否 | `ru` | `Accept-Language`头部。 |
| `WORDSTAT_API_BASE` | 否 | `https://searchapi.api.cloud.yandex.net` | API根（覆盖）。 |
| `WORDSTAT_TIMEOUT_MS` | 否 | `60000` | 请求超时，毫秒。 |
| `WORDSTAT_MAX_RETRIES` | 否 | `3` | 429/5xx重试次数。 |
## 要求
- Node.js 20+（通过`npx`运行，不需要单独安装）。
- 访问Yandex Cloud Search API - 请参阅 [获取访问权限](#获取访问权限)。
## 限制
- **只读。** Wordstat API没有更改操作 - 服务器只读。
- **总体配额。** 搜索配额（按Yandex Cloud Search API计费）被视为一个密钥，适用于所有调用。缓存`list_regions`和短语响应，不要发送频率。
## 文档
- [所有工具](https://github.com/askads/mcp-yandex-wordstat/blob/main/docs/TOOLS.md) - 带有描述的完整列表。
- [开发](https://github.com/askads/mcp-yandex-wordstat/blob/main/docs/DEVELOPMENT.md) - 构建、测试、烟雾检查。
- [发布](https://github.com/askads/mcp-yandex-wordstat/blob/main/docs/PUBLISHING.md) - 发布和列出在MCP目录中。
## 参见
- **[Ask Ads](https://askads.ru)** - 作者的聊天分析仪和广告账户“守卫”：来自此服务器的警报发送到Telegram。
- **[askads/claude-plugins](https://github.com/askads/claude-plugins)** - Claude插件市场：Ask Ads服务器通过一个命令安装，令牌在启用时询问。
## 支持
问题、想法和改进 - 请在Telegram上联系 [@gistrec](http://t.me/gistrec)。
## 许可证
MIT - 请参阅 [LICENSE](./LICENSE)。
