Yandex Wordstat MCP

yandex-wordstat-mcp

通过 Yandex Cloud Search API v2 提供 Yandex Wordstat 的 MCP 服务。研究关键词、分析搜索量趋势，并探索俄罗斯和独联体市场的区域搜索分布。

v2.0： Yandex 于 2026 年关闭了旧版 api.wordstat.yandex.net API。现在，服务会调用 searchapi.api.cloud.yandex.net/v2/wordstat/*，并使用 Yandex Cloud API 密钥而非 OAuth 令牌进行身份验证。工具名称和参数保持不变。

安装

此软件包以 @stufently/yandex-wordstat-mcp 发布；未加作用域的名称 yandex-wordstat-mcp 属于无关的发布者（请参阅根目录 README 中的说明）。 该作用域下目前尚无可用软件包，因此请从源代码运行：

git clone https://github.com/stufently/yandex-mcp.git
cd yandex-mcp && bun install
node packages/yandex-wordstat-mcp/src/index.mjs

配置

添加到 MCP 客户端配置中：

{
  "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..."
      }
    }
  }
}

也可以将凭据放入 ~/.config/yandex-cloud/wordstat.env（未设置环境变量时会将其用作备用配置）：

WORDSTAT_API_KEY=AQVN...
WORDSTAT_FOLDER_ID=b1g...

环境变量

变量	必填	描述
WORDSTAT_API_KEY	是	服务账号的 Yandex Cloud API 密钥（机密，AQVN...）
WORDSTAT_FOLDER_ID	是	用于计费和访问权限检查的 Yandex Cloud 文件夹 ID（b1g...）

身份验证（如何获取密钥）

1. 登录 Yandex Cloud 控制台，然后选择（或创建）一个文件夹——其 ID 显示在 URL 中：console.yandex.cloud/folders/<folderId>/...。云账号必须关联一个计费账号。
2. 在该文件夹中创建一个具有 search-api.webSearch.user 角色的服务账号。
3. 打开服务账号 → 创建新密钥 → API 密钥，范围选择 yc.search-api.execute。
4. 将密钥（仅显示一次）复制到 WORDSTAT_API_KEY；密钥标识符（ajel...）仅在之后轮换或撤销密钥时需要。

速率限制

服务使用滑动窗口在客户端实施每秒 10 个请求的速率限制。超出限制的请求会自动排队。此外，429 和 5xx 响应会触发带指数退避的自动重试。

工具参考

get-regions-tree

获取 Yandex Wordstat 区域层级树。

参数	类型	必填	默认值	描述
depth	number	否	3	最大树深度（1-5）

返回区域树，其中包含 value（区域 ID）、label（名称）和 children。

get-region-children

从缓存的树中获取指定区域的子区域。不会调用 API——直接使用缓存的区域树。

参数	类型	必填	默认值	描述
regionId	number	是	--	要获取子区域的区域 ID
depth	number	否	2	最大子树深度（1-3）

top-requests

查找包含关键词的热门搜索查询（最近 30 天），以及相关查询。

参数	类型	必填	默认值	描述
phrase	string	是	--	要搜索的关键词或短语（最多 400 个字符）
regions	number[]	否	--	用于筛选的区域 ID
devices	enum[]	否	--	设备类型：desktop、phone、tablet
limit	number	否	100	响应中的短语数量上限（1-2000）

返回按搜索量排序的 { topRequests: [{ phrase, count }], associations: [{ phrase, count }], totalCount }。

dynamics

分析某个关键词的搜索量随时间变化的趋势。

参数	类型	必填	默认值	描述
phrase	string	是	--	关键词或短语（最多 400 个字符）
period	enum	否	monthly	聚合周期：daily、weekly、monthly
fromDate	string	否	auto	开始日期（YYYY-MM-DD）
toDate	string	否	auto	结束日期（YYYY-MM-DD）
regions	number[]	否	--	区域 ID
devices	enum[]	否	--	设备类型：desktop、phone、tablet

API 强制执行的时间范围规则没有任何文档说明，违反规则时会返回原始 gRPC 错误（已于 2026-07-29 对线上 API 进行验证）：

周期	规则
daily	fromDate 必须在最近 60 天内，恰好往前 60 天会被拒绝
weekly	fromDate 必须是星期一，toDate 必须是星期日，且该周必须已经结束
monthly	fromDate 必须是某月的 1 日，toDate 必须是该月的最后一天，且该月必须已经结束

传入的日期会自动调整到最近的有效时间范围，而不会被拒绝；所有调整都会列在文本摘要和 structuredContent 的 adjustments 中。落在同一周或同一月内的日期范围会扩展为整个周期。仅覆盖当前未结束的周或月的范围无法处理——API 会拒绝此类请求——因此工具会说明这一点，并指出最新可用的 toDate，而不是转发 400 错误。

各周期的默认日期范围：

• daily：最近 58 天（比限制少一天，确保请求不会在 UTC 日期切换时过期）
• weekly：最近 52 个完整周，星期一至星期日
• monthly：最近 12 个完整月，从每月 1 日至月末

所有日期计算均使用 UTC。

返回由 { date, count, share } 数据点组成的数组。

regions

获取某个关键词搜索兴趣的区域分布。

参数	类型	必填	默认值	描述
phrase	string	是	--	关键词或短语（最多 400 个字符）
regions	number[]	否	--	用于筛选的区域 ID（在客户端筛选，包含下级区域）
devices	enum[]	否	--	设备类型：desktop、phone、tablet
limit	number	否	20	最大结果数（1-50）

返回按搜索量排序的 { regionId, regionName, count, share, affinityIndex } 数组。区域名称通过缓存的区域树补充。

缓存

首次调用 get-regions-tree、get-region-children 或 regions 时会获取区域树，并在整个服务会话期间缓存。系统还会构建一个扁平查找映射，以便通过 O(1) 时间复杂度解析区域名称。

许可证

MIT