yandex-search-mcp

По-русски → README.ru.md

Self-hosted MCP server for Yandex Search API v2: web search, image search, and generative search (AI answer with cited sources). Built for Russian-language search (all 6 Yandex indexes: ru/com/tr/kk/be/uz), STDIO or Streamable HTTP transport, fully typed tool parameters, structured output.

Works with Claude Code, Codex CLI, and opencode (any MCP client with stdio support).

Why

The official yandex/yandex-search-mcp-server is a Turkish-market demo: only tr/en regions, XML parsed with regexes, a non-existent dependency pin, and a json.loads(resp[1:-1]) hack on generative search. This server is a from-scratch replacement modeled on the structure and quality of brave/brave-search-mcp-server:

• proper XML parsing with defusedxml (untrusted web content), parser written against live API fixtures;
• typed parameters with fail-fast validation (no body: dict);
• retries with exponential backoff on 429/5xx/network only; a unified JSON error contract;
• the API key never leaks into logs or error messages (covered by tests);
• image results contain URLs and metadata only — never base64 (a lesson from Brave's 2.0 breaking change);
• LLM-facing tool descriptions with "when to use / when NOT to use" guidance.

Tools

Getting credentials

1. Create an API key for a service account with scope yc.search-api.execute.
2. Grant the service account the search-api.editor role on the folder.
3. Get your Folder ID (how to find it).

API docs: Search API v2 · REST reference.

Installation

Requires Python ≥ 3.11.

Fastest — from PyPI via uv:

YANDEX_SEARCH_API_KEY=<key> YANDEX_FOLDER_ID=<folder> uvx yandex-search-mcp

With a client: claude mcp add yandex-search -e YANDEX_SEARCH_API_KEY=<key> -e YANDEX_FOLDER_ID=<folder> -- uvx yandex-search-mcp. Or pip install yandex-search-mcp. Unreleased main: uvx --from git+https://github.com/oleg-cat/yandex-search-mcp yandex-search-mcp.

Updating: uvx caches the package. To pull the latest release, refresh and print the version (the server does not start), then restart your MCP client:

uvx --refresh yandex-search-mcp --version

yandex-search-mcp --help lists every environment variable.

From source:

git clone https://github.com/oleg-cat/yandex-search-mcp.git
cd yandex-search-mcp
python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e .

Quick check (secrets go through env only — CLI arguments are visible in ps):

YANDEX_SEARCH_API_KEY=<key> YANDEX_FOLDER_ID=<folder> .venv/bin/python -m yandex_search_mcp
# server listens on STDIO; Ctrl+C to exit

Claude Code

claude mcp add yandex-search \
  -e YANDEX_SEARCH_API_KEY=<key> \
  -e YANDEX_FOLDER_ID=<folder> \
  -- /abs/path/to/yandex-search-mcp/.venv/bin/python -m yandex_search_mcp

Use the absolute path to the venv python. Verify with claude mcp list (should show "✔ Connected").

Codex CLI

codex mcp add yandex-search \
  --env YANDEX_SEARCH_API_KEY=<key> \
  --env YANDEX_FOLDER_ID=<folder> \
  -- /abs/path/to/yandex-search-mcp/.venv/bin/python -m yandex_search_mcp

Or manually in ~/.codex/config.toml:

[mcp_servers.yandex-search]
command = "/abs/path/to/yandex-search-mcp/.venv/bin/python"
args = ["-m", "yandex_search_mcp"]
tool_timeout_sec = 180  # default 60s is too low for yandex_gen_search

[mcp_servers.yandex-search.env]
YANDEX_SEARCH_API_KEY = "<key>"
YANDEX_FOLDER_ID = "<folder>"

Note: Codex's default tool_timeout_sec is 60 seconds; yandex_gen_search can take tens of seconds — raise it to 180. Check the connection with /mcp inside the Codex TUI.

opencode

opencode.json in your project root (secrets via {file:...} or {env:...}, not inline):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "yandex-search": {
      "type": "local",
      "command": ["/abs/path/to/yandex-search-mcp/.venv/bin/python", "-m", "yandex_search_mcp"],
      "environment": {
        "YANDEX_SEARCH_API_KEY": "{file:~/.secrets/yandex_search_api_key}",
        "YANDEX_FOLDER_ID": "{file:~/.secrets/yandex_folder_id}"
      }
    }
  }
}

Docker

docker build -t yandex-search-mcp .
docker run -i --rm \
  -e YANDEX_SEARCH_API_KEY=<key> \
  -e YANDEX_FOLDER_ID=<folder> \
  yandex-search-mcp

The container speaks STDIO by default (-i is required). For a long-running shared server use HTTP mode:

docker run --rm -p 8000:8000 \
  -e YANDEX_MCP_TRANSPORT=http -e YANDEX_MCP_HOST=0.0.0.0 \
  -e YANDEX_SEARCH_API_KEY_FILE=/run/secrets/yandex_key -v ./yandex_key:/run/secrets/yandex_key:ro \
  -e YANDEX_FOLDER_ID=<folder> \
  yandex-search-mcp
# MCP endpoint: http://localhost:8000/mcp

HTTP transport

YANDEX_MCP_TRANSPORT=http serves MCP Streamable HTTP at http://<host>:<port>/mcp (default 127.0.0.1:8000). On localhost DNS-rebinding protection is on automatically. The endpoint has no authentication — bind to 0.0.0.0 only behind a reverse proxy or inside a private network, since anyone who reaches it spends your Yandex quota.

Environment variables

Tool parameters

yandex_web_search

Returns: {query, corrected_query, found, page, has_more, results[{rank, url, domain, title, snippet, modified_at}]}.

yandex_image_search

Returns: {query, found, page, has_more, results[{rank, image_url, format, width, height, page_url, domain}]} — URLs and metadata only, no base64.

yandex_gen_search

Returns: {answer, sources[{url, title, used}], search_queries, is_answer_rejected, is_bullet_answer, problematic_answer, fixed_misspell_query}. Quota is 1 request/second; responses take tens of seconds.

Quotas

Defaults (current limits):

The server retries 429 and 5xx (3 attempts, exponential backoff, honoring Retry-After up to 10 s) but does not work around quotas. Generative search is never re-sent after a read timeout or a dropped connection — the request may already have been processed and billed.

Troubleshooting

Development

.venv/bin/pip install -e ".[dev]"
make check          # ruff check + ruff format --check + pytest (67 tests on live fixtures)

Fixtures are re-captured with scripts/capture_fixtures.py (reads credentials from env or a local keys.json, which is gitignored).

Implementation notes baked into the parser (verified against live API responses):

• the generative endpoint returns a JSON array [{...}], not a bare object;
• an empty result set arrives as <error code="15"> inside the XML — the parser maps it to results: [], not an error;
• typo corrections arrive as <reask> (not <misspell>);
• <found priority="..."> exists both at response level and inside groupings — only the response-level one is used.

Releasing

Bump version in pyproject.toml and __init__.py, add a CHANGELOG entry, merge, then create a GitHub Release with tag vX.Y.Z. The Release workflow tests, builds and publishes to PyPI via Trusted Publishing (no tokens); it fails if the tag does not match the package version.

License

MIT