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.
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