yandex-search-mcp

MCP server for Yandex Search API v2 (Cloud). Search the web through Yandex and get structured results with titles, snippets, URLs, and metadata.

Installation

This package is published as @stufently/yandex-search-mcp; the unscoped name yandex-search-mcp belongs to an unrelated publisher (see the note in the root README). Nothing is on the scope yet, so run it from source:

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

Configuration

Add to your MCP client config:

{
  "mcpServers": {
    "yandex-search": {
      "command": "node",
      "args": ["/path/to/yandex-mcp/packages/yandex-search-mcp/src/index.mjs"],
      "env": {
        "YANDEX_SEARCH_API_KEY": "your-api-key",
        "YANDEX_FOLDER_ID": "your-folder-id"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
`YANDEX_SEARCH_API_KEY`	Yes	API key from Yandex Cloud Console
`YANDEX_FOLDER_ID`	Yes	Folder ID from Yandex Cloud

No OAuth flow is needed. Get both values from the Yandex Cloud Console.

Tool Reference

search

Search the web using Yandex Search API. Returns ranked results with titles, snippets, and URLs.

Parameters:

Parameter	Type	Required	Default	Description
`query`	string	Yes	--	Search query text
`maxResults`	number	No	10	Maximum results to return (1-100)
`region`	number	No	--	Yandex region ID
`page`	number	No	0	Page number (0-based)
`familyMode`	enum	No	`FAMILY_MODE_MODERATE`	Safe search: `FAMILY_MODE_NONE`, `FAMILY_MODE_MODERATE`, `FAMILY_MODE_STRICT`

Response fields:

Each result contains:

Field	Type	Description
`position`	number	Ranking position (1-based)
`url`	string	Result URL
`domain`	string	Hostname extracted from URL
`title`	string	Page title
`headline`	string	Meta description
`passages`	string[]	Relevant text passages
`snippet`	string	Combined headline and passages
`size`	number	Document size in bytes
`lang`	string	Document language
`cachedUrl`	string	Yandex cached copy URL

Language detection:

The search type and localization are automatically selected based on the query. Queries containing Cyrillic characters use the Russian search index; Latin-only queries use the international index.

API Details

Endpoint: POST https://searchapi.api.cloud.yandex.net/v2/web/search
Auth: Api-Key header
Response: JSON with base64-encoded XML in rawData field
Automatic retry with exponential backoff on 429/5xx errors

License

MIT

Edit on GitHub · 2026-07-30