mcpField
Y
Yandex Search MCP

Yandex Search MCP

Local
github.comSearch19Updated 2d ago
RepositoryVisit website

About Yandex Search MCP

Yandex Search MCP connects MCP clients to Yandex Search API v2 on Yandex Cloud. It returns ranked web results with titles, snippets, URLs, and metadata, with search localization selected from the query text.

Key features

  1. 01Search the web with Yandex
  2. 02Return ranked, structured results
  3. 03Set result count and page
  4. 04Specify region and family mode
  5. 05Select localization from query text
  6. 06Retry on rate limits and server errors

Use cases

  1. 01Find web pages relevant to a query
  2. 02Retrieve snippets and URLs for research
  3. 03Search with a region or safe-search setting

MCP support

Exposes Yandex Search API v2 web search as an MCP tool. The tool accepts a query and optional result count, region, page, and family-mode settings.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "stufently-yandex-search": {
      "command": "npx",
      "args": [
        "-y",
        "@stufently/yandex-search-mcp"
      ],
      "env": {
        "YANDEX_SEARCH_API_KEY": "<YANDEX_SEARCH_API_KEY>",
        "YANDEX_FOLDER_ID": "<YANDEX_FOLDER_ID>"
      }
    }
  }
}
Run commandnpx -y @stufently/yandex-search-mcp
Environment variables to set
YANDEX_SEARCH_API_KEYSecretYandex Cloud API key (service account with search-api.webSearch.user)
YANDEX_FOLDER_IDYandex Cloud folder ID

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@stufently/yandex-search-mcp2.2.1

Tools

1

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
pagenumberNoPage number (0-based, default: 0)
querystringYesSearch query text
regionnumberNoYandex region ID
familyModeenumNoSafe search filterFAMILY_MODE_NONE | FAMILY_MODE_MODERATE | FAMILY_MODE_STRICT
maxResultsnumberNoMaximum results to return (default: 10)

Details

From the project README

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

VariableRequiredDescription
YANDEX_SEARCH_API_KEYYesAPI key from Yandex Cloud Console
YANDEX_FOLDER_IDYesFolder 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:

ParameterTypeRequiredDefaultDescription
querystringYes--Search query text
maxResultsnumberNo10Maximum results to return (1-100)
regionnumberNo--Yandex region ID
pagenumberNo0Page number (0-based)
familyModeenumNoFAMILY_MODE_MODERATESafe search: FAMILY_MODE_NONE, FAMILY_MODE_MODERATE, FAMILY_MODE_STRICT

Response fields:

Each result contains:

FieldTypeDescription
positionnumberRanking position (1-based)
urlstringResult URL
domainstringHostname extracted from URL
titlestringPage title
headlinestringMeta description
passagesstring[]Relevant text passages
snippetstringCombined headline and passages
sizenumberDocument size in bytes
langstringDocument language
cachedUrlstringYandex 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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.