Yandex Search.API MCP 服务器

用于通过 REST 调用 Yandex Search API 的 MCP 服务器，包含 7 个工具：

• web_search

• image_search

• generative_search

• wordstat_get_top

• wordstat_get_dynamics

• wordstat_get_regions_distribution

• wordstat_get_regions_tree

服务器从 MCP 客户端环境变量配置中读取凭据：

• FOLDER_ID

• API_KEY

对于本地开发，.env 文件会自动加载。

功能特性

• 仅使用 REST 端点（/v2/web/search、/v2/image/search、/v2/gen/search 以及 Wordstat REST 路径）

• 默认最小化工具输入，以保持模型上下文简洁

• searchType 可用于所有相关工具，默认为 SEARCH_TYPE_COM

• 网页搜索始终强制使用 responseFormat: FORMAT_XML

• 网页/图片工具会对 rawData 进行 Base64 解码，并将 XML 解析为结构化分组

• 具备清晰的 API 状态和详细信息的错误处理机制

安装

npm install yandex-searchapi-mcp

MCP 客户端配置示例

{
  "mcpServers": {
    "yandex-searchapi": {
      "command": "npx",
      "args": ["-y", "yandex-searchapi-mcp"],
      "env": {
        "FOLDER_ID": "your-folder-id",
        "API_KEY": "your-api-key"
      }
    }
  }
}

工具

web_search

当你需要经典的网页搜索结果（链接 + 摘要）而非生成式答案时，请使用此工具。

输入：

• query (必填)

• searchType (可选，默认 SEARCH_TYPE_COM)

• page (可选)

• docsOnPage (可选)

• familyMode (可选)

• fixTypoMode (可选)

返回：

• groups[]，其中包含 documents[]，每个文档包含：

  • url

  • title

  • language

  • passages

• requestId

• found

注意：对于网页搜索，此输入映射到上游 API 的 groupSpec.groupsOnPage。

image_search

当你需要图片搜索结果和图片元数据（缩略图/原始链接及尺寸）时，请使用此工具。

输入：

• query (必填)

• searchType (可选，默认 SEARCH_TYPE_COM)

• page (可选)

• site (可选)

• docsOnPage (可选)

• imageSpec (可选：format, size, orientation, color)

返回：

• groups[]，其中包含 documents[]，每个文档包含：

  • url

  • extras.image-properties (如果存在)

• requestId

• found

generative_search

当你需要从搜索结果中合成的、可直接使用的基础答案时，请使用此工具。

输入：

• query (必填)

• searchType (可选，默认 SEARCH_TYPE_COM)

• fixMisspell (可选)

• getPartialResults (可选)

• scope (可选)：{ type: "site" | "host" | "url", values: string[] }

仅返回核心生成字段（不包含包装对象）：

• message

• sources

• searchQueries

• fixedMisspellQuery

• isAnswerRejected

• isBulletAnswer

• hints

• problematicAnswer

wordstat_get_top

使用此工具了解用户围绕某个关键词搜索的相关查询。

输入：

• phrase (必填)

• numPhrases (可选，默认 20)

• regions (可选)

• devices (可选)

返回：

• totalCount

• results

• associations

wordstat_get_dynamics

使用此工具跟踪关键词随时间的需求趋势。

输入：

• phrase (必填)

• period (可选，默认 PERIOD_WEEKLY)

• fromDate (可选，默认 now-30d，ISO 日期时间)

• toDate (可选，默认 now，ISO 日期时间)

• regions (可选)

• devices (可选)

返回：

• results

wordstat_get_regions_distribution

使用此工具查看关键词在哪些地区/城市相对更受欢迎。

输入：

• phrase (必填)

• region (可选，默认 REGION_ALL)

• devices (可选)

返回：

• results

wordstat_get_regions_tree

使用此工具获取用于区域 Wordstat 过滤器的有效区域 ID 和名称。

输入：

• 无

返回：

• regions

开发

npm install
npm run build
npm run dev