Yandex Search API MCP server — StreamableHTTP build

Self-hostable Model Context Protocol server for the Yandex Search API v2 — all search types, served over StreamableHTTP (/mcp) so it can run as an HTTP-MCP backend in a Docker/Compose stack (alongside other HTTP-MCP servers).

This is a fork of the official yandex/yandex-search-mcp-server (which exposes only stdio and always includes the AI/Yazeka endpoint). Not an official Yandex product and not endorsed by Yandex. Two deviations:

1. HTTP transport — adds run_http.py, which re-exports the same FastMCP instance and serves it over StreamableHTTP, so the container behaves like any HTTP-MCP service.

2. All search types — builds on upstream's web_search and also exposes the other Search API v2 endpoints (gen_search, image_search, image_search_by_image, plus deferred text search). Russian is the default search type (SEARCH_TYPE_RU, LOCALIZATION_RU, region 225 = Россия).

⚠️ Derivative work. Files inherited from upstream (server.py, detail.py) are © 2025 YANDEX LLC, Apache-2.0. See LICENSE.

Tools

All search types of the Yandex Search API v2 are exposed. Russian is the default (SEARCH_TYPE_RU, LOCALIZATION_RU, region 225 = Россия).

gen_search requires the FOLDER_ID env var (the Yandex folder the key belongs to).

Docs (search types & modes): https://aistudio.yandex.ru/ru/docs/search-api/concepts/

Related MCP server: yandex-search-mcp

Container image (GHCR)

Every push to main (and every v* tag) builds and publishes the image to the GitHub Container Registry:

ghcr.io/msklv/yandex-search-mcp-server:latest     # default branch
ghcr.io/msklv/yandex-search-mcp-server:main       # branch ref
ghcr.io/msklv/yandex-search-mcp-server:v1.2.3   # semver tag

The container serves the MCP server over StreamableHTTP on port 8766:

docker run --rm -p 8766:8766 \
  -e SEARCH_API_KEY=... [-e FOLDER_ID=...] \
  ghcr.io/msklv/yandex-search-mcp-server:latest
# MCP endpoint: http://<host>:8766/mcp

Requirements

• Python 3.10+ / Docker 20+.

• A Yandex Search API key (and optionally a folder id). Credentials come from env vars at runtime — the repository contains no secrets.

Run

# local, stdio (upstream behaviour)
export SEARCH_API_KEY=...
python3 server.py

# local, StreamableHTTP on 8766 (/mcp)
export SEARCH_API_KEY=...
python3 run_http.py

# docker
docker build -t yandex-search-mcp-server .
docker run --rm -p 8766:8766 \
  -e SEARCH_API_KEY=... [-e FOLDER_ID=...] \
  yandex-search-mcp-server

web_search

await mcp.call_tool("web_search", {"body": {"query": "кофемашина", "region": 213}})

• query (required) — search query; Cyrillic supported natively.

• search_region (optional) — ru (default) / tr / com / kk / be / uz.

• region (optional) — numeric Yandex region id to bias ranking (only ru/tr); default 225 (Россия) for ru, e.g. 213 = Москва, 2 = Санкт-Петербург.

License

Apache-2.0. Original copyright on derived files: 2025 YANDEX LLC. This fork's additions (run_http.py, HTTP Dockerfile, this README) by msklv, Apache-2.0.