Yandex Search.API MCP Server

MCP server for Yandex Search API over REST with 7 tools:

• web_search

• image_search

• generative_search

• wordstat_get_top

• wordstat_get_dynamics

• wordstat_get_regions_distribution

• wordstat_get_regions_tree

The server reads credentials from MCP client env config:

• FOLDER_ID

• API_KEY

For local development, .env is loaded automatically.

Features

• Uses only REST endpoints (/v2/web/search, /v2/image/search, /v2/gen/search, Wordstat REST paths)

• Minimal tool inputs by default to keep model context compact

• searchType is available for all relevant tools and defaults to SEARCH_TYPE_COM

• Web search always forces responseFormat: FORMAT_XML

• Web/image tools decode rawData from Base64 and parse XML into structured groups

• Error handling with clear API status and details

Install

npm install yandex-searchapi-mcp

MCP client config example

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

Tools

web_search

Use this tool when you need classic web search results (links + snippets), not a generated answer.

Inputs:

• query (required)

• searchType (optional, default SEARCH_TYPE_COM)

• page (optional)

• docsOnPage (optional)

• familyMode (optional)

• fixTypoMode (optional)

Returns:

• groups[] with documents[] where each document contains:

  • url

  • title

  • language

  • passages

• requestId

• found

Note: for web search this input is mapped to groupSpec.groupsOnPage on the upstream API.

image_search

Use this tool when you need image search results and image metadata (thumbnail/original links and dimensions).

Inputs:

• query (required)

• searchType (optional, default SEARCH_TYPE_COM)

• page (optional)

• site (optional)

• docsOnPage (optional)

• imageSpec (optional: format, size, orientation, color)

Returns:

• groups[] with documents[] where each document contains:

  • url

  • extras.image-properties (if present)

• requestId

• found

generative_search

Use this tool when you need a ready-to-use grounded answer synthesized from search results.

Inputs:

• query (required)

• searchType (optional, default SEARCH_TYPE_COM)

• fixMisspell (optional)

• getPartialResults (optional)

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

Returns only core generative fields (without wrapper objects):

• message

• sources

• searchQueries

• fixedMisspellQuery

• isAnswerRejected

• isBulletAnswer

• hints

• problematicAnswer

wordstat_get_top

Use this tool to understand what related queries users search for around a keyword.

Inputs:

• phrase (required)

• numPhrases (optional, default 20)

• regions (optional)

• devices (optional)

Returns:

• totalCount

• results

• associations

wordstat_get_dynamics

Use this tool to track demand trends over time for a keyword.

Inputs:

• phrase (required)

• period (optional, default PERIOD_WEEKLY)

• fromDate (optional, default now-30d, ISO datetime)

• toDate (optional, default now, ISO datetime)

• regions (optional)

• devices (optional)

Returns:

• results

wordstat_get_regions_distribution

Use this tool to see in which regions/cities a keyword is relatively more popular.

Inputs:

• phrase (required)

• region (optional, default REGION_ALL)

• devices (optional)

Returns:

• results

wordstat_get_regions_tree

Use this tool to get valid region IDs and names for regional Wordstat filters.

Inputs:

• none

Returns:

• regions

Development

npm install
npm run build
npm run dev