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