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%
Low risk
We rate an entry low when it mostly gives the agent instructions and reference material.
Why this level
- The server only reads public search results via the official API
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:latestBuild and run in Docker with the SQLite store persisted via a volume.
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 readyLimitations
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.editor 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.
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 |
Security check
- The server only reads public search results via the official API
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.
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.
Related
CLI, skill and Python library for browser control: the agent clicks, fills forms and reads pages over CDP
A skill that gathers the last 30 days of discussion on a topic from Reddit, X, YouTube, HN, Polymarket and GitHub into one brief
The Chrome DevTools team's official MCP server: the agent drives a live Chrome, reads network and console, and records performance traces
A fast Rust CLI for agent browser automation: accessibility snapshots with element refs, an MCP server and skills