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