SkillFoxx

Yandex Search API MCP with deferred search

Yandex Search MCP Server (Async Mode)

A fork of Yandex's official server defaulting to deferred async search, cutting Search API cost by up to 94%

  • 0 ★ on the repository
  • Last commit
MCP server

Extended access

Why this level

  • Runs a Python server that submits deferred search requests with a Yandex Cloud key
  • Stores operation IDs in local SQLite; requests are billed
All reasons and checks
Russian stack

hdworker/ydex-async-search-mcp-serverAuthor:hdworker

Install

Manual install

docker build -t yandex-mcp-server-async:latest . && docker run -i --rm -e SEARCH_API_KEY=<your_api_key> -e FOLDER_ID=<your_folder_id> -v $(pwd)/data:/app/data yandex-mcp-server-async:latest

Build and run in Docker with the SQLite store persisted via a volume.

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

  • Runs a Python server that submits deferred search requests with a Yandex Cloud key
  • Stores operation IDs in local SQLite; requests are billed

This is third-party code. Review the repository files before installing.

What it does

The server extends the official yandex/yandex-search-mcp-server: the web_search tool defaults to deferred (async) mode instead of sync, because Yandex's deferred pricing tier is far cheaper, especially at night. Operation status and results are checked with a separate get_search_status tool by operation_id, get_pending_searches lists unfinished requests, and cleanup_old_searches clears old records. Operation IDs are stored in a local SQLite database rather than only in memory, so they can be checked later even after the server restarts.

Who it is for. For those who search a lot through the Yandex Search API and want to pay the deferred tariff instead of the synchronous one.

Good fit when

  • Query volume is high enough that the sync-versus-async price gap matters
  • The agent can wait for a result or check it later with a separate call
  • You need to track a batch of requests and automatically clean up old records

Not a fit when

  • You need an instant synchronous answer to every query: you can pass mode sync, but then there is no savings
  • You need image or generative search: the server is focused on web_search

Example request

Search for coffee machine information in deferred mode and let me know when the result is ready

MCP

Transport
stdio
Authentication
API key

Environment variables

SEARCH_API_KEY required, secret
Yandex Cloud service-account API key with yc.search-api.execute scope
FOLDER_ID required
Yandex Cloud folder ID

Limitations

Async mode by default means the result is not instant; the agent must poll get_search_status or explicitly pass wait true. A Yandex Cloud service account with the search-api.webSearch.user role and an API key with yc.search-api.execute scope are required. The prices in the README are as of publication and may change on Yandex's side.

How to disable. Stop the container or server process and remove it from your MCP client configuration.

FAQ

Can I get a synchronous answer like the original?

Yes, pass mode sync in the web_search call, but then the more expensive synchronous tariff applies.

Where are operation IDs stored?

In a local SQLite database, mounted as the /app/data volume in Docker.

Discussion

No questions or reviews yet.

All Yandex Search tools
Russian stack

A self-hosted MCP for Yandex Search API v2: web, image and generative search across all six Yandex indexes

MCP serverExtended access3

Yandex Search API v2 MCP server over HTTP

Yandex Search API MCP server, StreamableHTTP build

Russian stack

A fork of Yandex's official server adding HTTP transport and the full range of search types: web, generative, image

MCP serverExtended access1
Russian stack

A search MCP server on the Yandex Cloud Search API with a monitoring dashboard, Brave fallback and an offline bundle for air-gapped networks

MCP serverExtended access
Russian stack

An MCP server for the Yandex Cloud Search API v2: Wordstat and web search with file caching, date normalization and 429-retry handling

MCP serverExtended access

README in short

The Russian README compares sync and deferred Yandex pricing tiers with concrete savings in percent and rubles, walks through setting up the Yandex CLI, a service account and an API key, install via Docker or Python, configs for Claude Desktop, Cursor and opencode, a description of all four tools, and an architecture diagram.

README badge

Report a problem