Yandex Search MCP Server

https://github.com/yandex/yandex-search-mcp-server
Admin
Yandex Search MCP Server is a Model Context Protocol server that enables AI assistants like Claude...
Tokens:5,687
Snippets:48
Trust Score:8.5
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Python Dependencies

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

Install the required Python libraries for the MCP server. This command reads dependencies from `requirements.txt`.

```bash
pip install -r requirements.txt
```

--------------------------------

### Example Prompt for Cursor with Yandex Search

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

This is an example prompt to use with Cursor after configuring the Yandex Search MCP. It demonstrates how to invoke the search tool.

```text
use yandexSearch to find information about the best AI Agent frameworks in 2025
```

--------------------------------

### Web Search Example Request

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

Example JSON request to perform a web search. Specify the query and the desired search region.

```json
{
    "query": "Who won the most recent Formula 1 race in 2025?",
    "search_region": "en"
}
```

--------------------------------

### Docker Deployment for Yandex MCP Server

Source: https://context7.com/yandex/yandex-search-mcp-server/llms.txt

Builds a minimal Python image, installs dependencies, copies server files, and runs as a non-root user for stdio-based MCP communication.

```bash
# Build the image
docker build -t yandex-mcp-server-image:latest .

# Run as a one-shot MCP stdio server (used by MCP clients)
docker run -i --rm \
  --name yandex-mcp-container \
  -e SEARCH_API_KEY="your_api_key" \
  -e FOLDER_ID="your_folder_id" \
  yandex-mcp-server-image:latest

# MCP client config (mcp.json / claude_desktop_config.json)
{
  "mcpServers": {
    "yandex-search-api-docker": {
      "type": "stdio",
      "command": "sh",
      "args": [
        "-c",
        "docker rm -f yandex-mcp-container; docker run -i --name yandex-mcp-container --env SEARCH_API_KEY=<your_api_key> --env FOLDER_ID=<your_folder_id> yandex-mcp-server-image:latest"
      ]
    }
  }
}
```

--------------------------------

### Invoke ai_search_with_yazeka using MCP SDK

Source: https://context7.com/yandex/yandex-search-mcp-server/llms.txt

Example of invoking the `ai_search_with_yazeka` tool using the `mcp` Python SDK. This code sets up a stdio client, initializes a session, calls the tool with a query, and prints the AI-generated response and its sources. Ensure environment variables for API key and folder ID are set.

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import asyncio, json

async def run_ai_search():
    server_params = StdioServerParameters(
        command="python3",
        args=["server.py"],
        env={
            "SEARCH_API_KEY": "your_api_key_here",
            "FOLDER_ID": "your_folder_id_here"
        }
    )
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "ai_search_with_yazeka",
                arguments={
                    "body": {
                        "query": "Who won the most recent Formula 1 race in 2025?",
                        "search_region": "en"
                    }
                }
            )
            parsed = json.loads(result.content[0].text)
            print(parsed["response"])
            # "Max Verstappen won the 2025 Bahrain Grand Prix on March 2nd..."
            print(parsed["sources"])
            # ["https://formula1.com/results/...", "https://motorsport.com/..."]

asyncio.run(run_ai_search())
```

--------------------------------

### Launch Local MCP Server

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

Launch the Yandex Search MCP server directly on your machine using Python. Ensure Python 3.10+ is installed and the `SEARCH_API_KEY` environment variable is set.

```bash
python3 server.py
```

--------------------------------

### Clone Yandex Search MCP Server Repository

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

This bash command clones the Yandex Search MCP server repository. Navigate into the cloned directory to proceed with local setup.

```bash
git clone git@github.com:yandex/yandex-search-mcp-server.git
cd /path/to/yandex-search-mcp-server
```

--------------------------------

### Direct Python Usage for web_search

Source: https://context7.com/yandex/yandex-search-mcp-server/llms.txt

Demonstrates how to directly invoke the `web_search` tool using Python when the server is running via stdio. Ensure the `request` dictionary is correctly formatted with the desired query and search region.

```python
import json, subprocess, sys

request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "web_search",
        "arguments": {
            "body": {
                "query": "best Python web frameworks 2025",
                "search_region": "en"
            }
        }
    }
}

# Expected response structure:
# {
#   "responses": [
#     { "data": "Django remains the most popular...", "source": "https://example.com/article" },
#     { "data": "FastAPI has seen massive growth...", "source": "https://another.com/blog" },
#     ...
#   ]
# }
```

--------------------------------

### Configure MCP Server with Podman

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

Configure your MCP client to use the Yandex Search API via Podman. Replace placeholders with your actual API key and folder ID. Ensure only one server instance is active.

```json
{
  "mcpServers": {
    "yandex-search-api-podman": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 60,
      "type": "stdio",
      "command": "sh",
      "args": [
        "-c",
        "podman rm -f yandex-mcp-container; podman run -i --name yandex-mcp-container --env SEARCH_API_KEY=<your_api_key> --env FOLDER_ID=<your_folder_id> yandex-mcp-server-image:latest"
      ]
    }
  }
}
```

--------------------------------

### Configure MCP Server with Docker

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

Configure your MCP client to use the Yandex Search API via Docker. Replace placeholders with your actual API key and folder ID. Ensure only one server instance is active.

```json
{
  "mcpServers": {
    "yandex-search-api-docker": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 60,
      "type": "stdio",
      "command": "sh",
      "args": [
        "-c",
        "docker rm -f yandex-mcp-container; docker run -i --name yandex-mcp-container --env SEARCH_API_KEY=<your_api_key> --env FOLDER_ID=<your_folder_id> yandex-mcp-server-image:latest"
      ]
    }
  }
}
```

--------------------------------

### Configure Claude Desktop with Yandex Search MCP

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

Add this JSON configuration to your Claude Desktop's config.json file to enable the Yandex Search MCP server. Ensure you replace `<your_api_key>` and `<your_folder_id>` with your actual credentials.

```json
{
  "mcpServers": {
    "yandexSearch": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://d5de9siimt9bkld7viic.emzafcgx.apigw.yandexcloud.net:3000/sse",
        "--header", "ApiKey:<your_api_key>",
        "--header", "FolderId:<your_folder_id>"
      ]
    }
  }
}
```

--------------------------------

### Configure MCP Server with Python

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

Configure your MCP client to use the Yandex Search API via a local Python script. Replace placeholders with your actual API key, folder ID, and the correct path to the server script.

```json
{
  "mcpServers": {
    "yandex-search-api": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 60,
      "type": "stdio",
      "command": "env",
      "args": [
        "SEARCH_API_KEY=<your_api_key>",
        "FOLDER_ID=<your_folder_id>",
        "python3",
        "/path/to/mcp-server-demo/server.py"
      ]
    }
  }
}
```

--------------------------------

### Configure Remote SSE Endpoint for Claude Desktop

Source: https://context7.com/yandex/yandex-search-mcp-server/llms.txt

This configuration snippet is for `claude_desktop_config.json` to connect to the Yandex Search MCP Server's remote SSE endpoint. Replace `YOUR_API_KEY` and `YOUR_FOLDER_ID` with your actual credentials.

```json
{
  "mcpServers": {
    "yandexSearch": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://d5de9siimt9bkld7viic.emzafcgx.apigw.yandexcloud.net:3000/sse",
        "--header", "ApiKey:YOUR_API_KEY",
        "--header", "FolderId:YOUR_FOLDER_ID"
      ]
    }
  }
}
```

--------------------------------

### Authenticate with Docker Hub (Podman)

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

Authenticate with Docker Hub for Podman users to pull images. Enter your Docker Hub username and password when prompted.

```bash
podman login docker.io
```

--------------------------------

### Build Podman Container

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

Build the Podman container image for the MCP server. This command creates an image tagged as `yandex-mcp-server-image:latest`.

```bash
podman build -t yandex-mcp-server-image:latest .
```

--------------------------------

### Configure Cursor with Yandex Search MCP

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

Add this JSON configuration to your Cursor's mcp.json file to enable the Yandex Search MCP server. Replace `<your_api_key>` and `<your_folder_id>` with your actual credentials.

```json
{
  "mcpServers": {
    "yandexSearch": {
      "type": "sse",
      "url": "https://d5de9siimt9bkld7viic.emzafcgx.apigw.yandexcloud.net:3000/sse",
      "headers": {
        "ApiKey": "<your_api_key>",
        "FolderId": "<your_folder_id>"
      }
    }
  }
}
```

--------------------------------

### Build Docker Container

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

Build the Docker container image for the MCP server. This command creates an image tagged as `yandex-mcp-server-image:latest`.

```bash
docker build -t yandex-mcp-server-image:latest .
```

--------------------------------

### Set Environment Variable for API Key

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

Set the `SEARCH_API_KEY` environment variable for running the local MCP server. Replace `<your_api_key>` with your actual Yandex Search API key.

```bash
export SEARCH_API_KEY=<your_api_key>
```

--------------------------------

### Generic Authenticated HTTP POST Request

Source: https://context7.com/yandex/yandex-search-mcp-server/llms.txt

Reusable HTTP POST helper with configurable timeout, optional Base64 response decoding, and unified RuntimeError wrapping of requests exceptions. Used by both call_web_search and call_ai_search_with_yazeka.

```python
from detail import make_http_request

# Plain JSON response
response_text = make_http_request(
    url="https://searchapi.api.cloud.yandex.net/v2/web/search",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Api-Key YOUR_KEY"
    },
    json_body={"query": {"queryText": "Python tips"}, "folderId": "YOUR_FOLDER"},
    timeout=10,
    decode_base64=True   # set True for web/search endpoint; False for gen/search
)

# Error handling
try:
    result = make_http_request("https://invalid.endpoint", timeout=5)
except RuntimeError as e:
    print(f"Request failed: {e}")
    # "Request failed: API request failed: HTTPSConnectionPool..."

```

--------------------------------

### web_search — Fast structured web search

Source: https://context7.com/yandex/yandex-search-mcp-server/llms.txt

Performs a real-time web search against the Yandex Search API v2. Results are returned as a JSON object containing a `responses` array, where each entry holds a `data` (headline or snippet) and `source` (URL) field. This tool is best used for simple, factual queries where a list of relevant sources suffices.

```APIDOC
## web_search

### Description
Performs a real-time web search against `https://searchapi.api.cloud.yandex.net/v2/web/search`. Results are returned as a JSON object containing a `responses` array, where each entry holds a `data` (headline or snippet) and `source` (URL) field. The response is decoded from Base64-encoded XML before parsing. Best used for simple, factual queries where a list of relevant sources suffices.

### Method
POST (via MCP tool call)

### Endpoint
Not directly exposed as an HTTP endpoint; invoked via MCP tool call.

### Parameters
#### Arguments for `web_search` tool:
- **body** (object) - Required - The search query and region.
  - **query** (string) - Required - The search query string.
  - **search_region** (string) - Optional - The search region (e.g., "en", "tr"). Defaults to "en".

### Request Example (MCP tool call)
```json
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "web_search",
        "arguments": {
            "body": {
                "query": "best Python web frameworks 2025",
                "search_region": "en"
            }
        }
    }
}
```

### Response
#### Success Response
- **responses** (array) - A list of search results.
  - **data** (string) - The headline or snippet from the search result.
  - **source** (string) - The URL of the source.

#### Response Example
```json
{
  "responses": [
    { "data": "Django remains the most popular...", "source": "https://example.com/article" },
    { "data": "FastAPI has seen massive growth...", "source": "https://another.com/blog" }
  ]
}
```
```

--------------------------------

### Validate Input Data Keys

Source: https://context7.com/yandex/yandex-search-mcp-server/llms.txt

Lightweight guard to check a dictionary for required keys before an API call. Returns an error string if keys are missing, or None if all required keys are present.

```python
from detail import validate_input_data

data = {"query": "hello"}
required = {"query", "search_region"}

error = validate_input_data(data, required)
if error:
    print(error)  # "Missing required keys: search_region"
else:
    print("Input valid")

# Valid case
error = validate_input_data({"query": "hi", "search_region": "en"}, required)
print(error)  # None
```

--------------------------------

### ai_search_with_yazeka — AI-powered generative search

Source: https://context7.com/yandex/yandex-search-mcp-server/llms.txt

Calls `https://searchapi.api.cloud.yandex.net/v2/gen/search` to perform a deep web search and synthesize an AI-generated answer using Yandex's Yazeka model. The response includes a natural-language `response` string and a `sources` array of URLs that were actually used in generating the answer. This endpoint has a longer timeout (200 s) and is suited for complex questions requiring aggregation across multiple sources.

```APIDOC
## ai_search_with_yazeka

### Description
Calls `https://searchapi.api.cloud.yandex.net/v2/gen/search` to perform a deep web search and synthesize an AI-generated answer using Yandex's Yazeka model. The response includes a natural-language `response` string and a `sources` array of URLs that were actually used in generating the answer. This endpoint has a longer timeout (200 s) and is suited for complex questions requiring aggregation across multiple sources.

### Method
POST (via MCP tool call)

### Endpoint
Not directly exposed as an HTTP endpoint; invoked via MCP tool call.

### Parameters
#### Arguments for `ai_search_with_yazeka` tool:
- **body** (object) - Required - The search query and region.
  - **query** (string) - Required - The search query string.
  - **search_region** (string) - Optional - The search region (e.g., "en", "tr"). Defaults to "en".

### Request Example (MCP tool call)
```python
# Invoke via MCP tool call (example using the mcp Python SDK)
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import asyncio, json

async def run_ai_search():
    server_params = StdioServerParameters(
        command="python3",
        args=["server.py"],
        env={
            "SEARCH_API_KEY": "your_api_key_here",
            "FOLDER_ID": "your_folder_id_here"
        }
    )
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "ai_search_with_yazeka",
                arguments={
                    "body": {
                        "query": "Who won the most recent Formula 1 race in 2025?",
                        "search_region": "en"
                    }
                }
            )
            parsed = json.loads(result.content[0].text)
            print(parsed["response"])
            print(parsed["sources"])

asyncio.run(run_ai_search())
```

### Response
#### Success Response
- **response** (string) - An AI-generated natural-language answer to the query.
- **sources** (array) - An array of URLs that were used to generate the answer.

#### Response Example
```json
{
  "response": "Max Verstappen won the 2025 Bahrain Grand Prix on March 2nd...",
  "sources": ["https://formula1.com/results/...", "https://motorsport.com/..."]
}
```
```

--------------------------------

### Call Yandex Web Search v2 API

Source: https://context7.com/yandex/yandex-search-mcp-server/llms.txt

Internal function to build and send POST requests to the Yandex Web Search v2 endpoint. Handles Base64 decoding of XML rawData and returns raw XML. Region selection affects searchType and l10n fields.

```python
import os
from detail import call_web_search

os.environ["SEARCH_API_KEY"] = "your_api_key"
os.environ["FOLDER_ID"] = "your_folder_id"

xml_result = call_web_search({
    "query": "OpenAI GPT-5 release date",
    "search_region": "en"  # or "tr" for Turkish
})

# xml_result is decoded XML, e.g.:
# <yandexsearch>
#   <response>
#     <results>
#       <doc id="1">
#         <url>https://openai.com/...</url>
#         <title>GPT-5 ...</title>
#         <headline>OpenAI announces...</headline>
#       </doc>
#       ...
#     </results>
#   </response>
# </yandexsearch>
```

--------------------------------

### Call Yandex Generative Search API

Source: https://context7.com/yandex/yandex-search-mcp-server/llms.txt

Internal function to POST to the Yandex Generative Search endpoint. Wraps the query as an MCP-style messages array, applies language/search-type filters, and enables spell-fix and NRFM enrichment. Returns the raw JSON response string.

```python
import os, json
from detail import call_ai_search_with_yazeka

os.environ["SEARCH_API_KEY"] = "your_api_key"
os.environ["FOLDER_ID"] = "your_folder_id"

raw = call_ai_search_with_yazeka({
    "query": "What are the latest advances in quantum computing?",
    "search_region": "en"
})

# Strip outer quotes added by the API wrapper and parse
parsed = json.loads(raw[1:-1])
print(parsed["message"]["content"])   # AI-generated answer text
print([s["url"] for s in parsed["sources"] if s["used"]])  # cited URLs
```

--------------------------------

### Yandex Search MCP URL for Remote Connection

Source: https://github.com/yandex/yandex-search-mcp-server/blob/main/readme.md

This is the URL to use for remote connections to the Yandex Search MCP server.

```text
https://d5de9siimt9bkld7viic.emzafcgx.apigw.yandexcloud.net:3000/sse
```
Tokens:
Raw