Yandex Wordstat MCP

Yandex Wordstat MCP

Yandex Wordstat MCP 将 AI 应用连接到 Yandex 搜索需求统计数据。询问某个短语的搜索频率、哪些月份关注度会上升，以及哪些城市对某个主题更感兴趣，助手便会收集 Wordstat 数据并解读结果。服务通过 Yandex Cloud Search API 运行，因此无需访问 Yandex Direct 广告账户。

• 五种工具。 热门和相关搜索词、需求趋势、地区分布、地区目录以及 API 技术请求。
• 只读。 Wordstat API 不会创建广告系列、广告、关键词或其他对象。
• 需求与季节性。 热门搜索词和地区数据涵盖最近 30 天；趋势可按天、周或月，针对所需时段生成。
• 地区与设备。 报告可限定到特定地区，还可以比较电脑、手机和平板电脑上的需求。
• 无需 Yandex Direct OAuth。 需要 Search API 的 API 密钥和 Yandex Cloud 文件夹 ID。

从安全的请求开始：

“购买自行车”的月搜索量是多少？有哪些相关搜索词？

连接服务 · 查看使用场景 · 打开技术文档

一分钟了解其工作方式

目录

• 快速开始
• 可以委托哪些任务
• 如何解读需求数据
• 如何获取访问权限
• 哪些操作可能更改数据
• 数据、限制与后台运行
• 技术文档
• 支持

快速开始

需要 Node.js 20 或更高版本、Yandex Cloud Search API 的 API 密钥，以及 Yandex Cloud 目录 ID。

1. 获取访问权限，并将服务添加到 AI 应用中——下方提供了五种应用的说明。
2. 提问：“每月有多少人搜索‘买自行车’，还有哪些类似的查询？”

codex mcp add yandex-wordstat \
  --env WORDSTAT_API_KEY=ваш_ключ \
  --env WORDSTAT_FOLDER_ID=ваш_folder_id \
  -- npx -y mcp-yandex-wordstat@latest

codex mcp list

claude mcp add \
  --env WORDSTAT_API_KEY=ваш_ключ \
  --env WORDSTAT_FOLDER_ID=ваш_folder_id \
  --transport stdio \
  --scope user \
  yandex-wordstat \
  -- npx -y mcp-yandex-wordstat@latest

claude mcp list

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "ваш_ключ",
        "WORDSTAT_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "ваш_ключ",
        "WORDSTAT_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}

{
  "servers": {
    "yandex-wordstat": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "${input:wordstat_api_key}",
        "WORDSTAT_FOLDER_ID": "${input:wordstat_folder_id}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "wordstat_api_key",
      "description": "API-ключ Yandex Cloud",
      "password": true
    },
    {
      "type": "promptString",
      "id": "wordstat_folder_id",
      "description": "ID каталога Yandex Cloud"
    }
  ]
}

可以委托的任务

挖掘并评估需求

• “这个短语每月被搜索多少次？有哪些类似的查询？”
• “帮我找出‘披萨配送’相关的查询及其搜索频率。”
• “分别展示包含我的短语的查询和语义相似的查询。”

了解季节性

• “展示‘滑雪’一年来每个月的需求。”
• “这项服务的需求在哪些周上升或下降？”
• “比较手机和电脑上的查询趋势。”

比较地区

• “哪些城市对‘公寓装修’的关注度高于平均水平？”
• “比较莫斯科和圣彼得堡的需求。”
• “找到所需地区的 ID，并将下一份报告范围缩小到该地区。”

如何阅读需求数据

top_requests 显示包含指定短语的热门查询，以及语义相近的查询。总计数 totalCount 指的是最近 30 天。

dynamics 返回包含 {date, count, share} 的序列，支持按天、周或月细分。regions 按地区分布最近 30 天的需求；affinityIndex 高于 100% 表示关注度高于平均水平。计数值可能以字符串形式返回：Yandex 会以这种形式在 JSON 中传递较大的整数。

单次调用只能针对一个短语生成数据。对于较长的关键词列表，最好先缩小列表范围，而不是依次运行所有查询：同一个密钥共用 Yandex Cloud Search API 的配额。

如何获取访问权限

1. 在 Yandex Cloud 中创建服务账号，并为其分配 search-api.webSearch.user 角色。
2. 为该账号生成作用域为 yc.search-api.execute 的 API 密钥——具体步骤见 AI Studio 文档。
3. 在 Yandex Cloud 控制台的目录页面及其 URL 中找到目录 ID（folderId）。
4. 将密钥作为 WORDSTAT_API_KEY 传入，将目录 ID 作为 WORDSTAT_FOLDER_ID 传入。

该服务调用 Yandex Cloud Search API v2。不使用旧版独立 Wordstat API 的 OAuth。API 密钥以明文形式存储在 MCP 客户端配置中——请将其视为密码。

可以更改数据的内容

不能更改 Yandex Wordstat 中的任何数据。所有五个工具，包括 raw_request，都只能读取数据。从技术上说，API 使用 POST，但 Wordstat 没有写入端点；服务还会阻止任意请求发送到其他主机。

数据、限制与后台运行

• 聚合数据。 服务获取的是搜索需求统计数据，而不是特定广告账户的数据。
• 地区目录缓存。 在长时间运行的进程中，地区树只加载一次，并在后续请求中重复使用。
• 临时错误时重试。 单次请求超时为 60 秒。遇到 429、5xx、网络错误或超时时，服务最多重试三次；会遵循 Retry-After，且延迟不超过 30 秒。
• 不进行后台监控。 AI 应用调用服务时，服务才会运行。如果应用支持定时任务，可以在其中设置针对所选短语的定期报告。
• 匿名遥测。 默认情况下，服务会发送随机安装标识符、事件或工具名称、服务版本、Node.js 版本、操作系统和 AI 客户端信息。遥测中不会包含 API 密钥、工具参数、你的消息、需求数据或环境变量值。要为 Ask Ads 的 MCP 服务关闭遥测：ASKADS_TELEMETRY=0。

技术文档

• MCP 功能目录 — 按用户任务划分的各工具页面。
• 所有工具和参数
• 开发文档
• 发布文档
• Yandex Cloud Search API 文档

支持

发现错误或缺少使用场景？创建 issue 或在 Telegram 上联系我们。