Yandex Search MCP Server
This Model Context Protocol (MCP) server lets AI assistants like Claude and Cursor use the Yandex Search API for searching the web. Yandex Search enables LLM agents to safely and easily find up-to-date information on the internet.
Available Tools
The Yandex Search MCP server includes the following tools:
- ai_search_post Performs a real-time web search and returns an AI-generated answer based on the search results using Yandex Yazeka AI model.
- web_search_post: Performs a real-time web search and returns answer with sources
Getting API Key
To use this MCP server, you need to be a customer of Yandex Search API. Also you need a Yandex Search API key and folder id:
- API Key Documentation
- Must include
yc.search-api.executescope.
- Must include
- Folder ID Documentation
- The service account in this folder must have
search-api.editorrole.
- The service account in this folder must have
How to use Yandex Search MCP Remotely (recommended)
Yandex Search MCP URL for Remote Connection
https://d5dj4o5pbnqgca1d546v.cmxivbes.apigw.yandexcloud.net:3000/sse
How to Add Yandex Search MCP to Claude 🤖
1. Configure Claude Desktop to Recognize MCP Servers
Open the Claude Desktop app and enable Developer Mode from the top-left menu bar.
Once enabled, open Settings (also from the top-left menu bar) and navigate to the Developer Option.
Click the Edit Config button to open the claude_desktop_config.json file
2. Add Yandex Search MCP to Claude Desktop
Add the following text to your Claude Desktop configuration file:
{
"mcpServers": {
"yandexSearch": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://d5dj4o5pbnqgca1d546v.cmxivbes.apigw.yandexcloud.net:3000/sse",
"--header", "ApiKey:<your_api_key>",
"--header", "FolderId:<your_folder_id>"
]
}
}
}
3. Restart Claude Desktop
For the changes to take effect:
- Completely quit Claude Desktop (not just close the window)
- Start Claude Desktop again
- Click "Search and Tools" to verify that yandexSearch is enabled and running
How to Add Yandex Search MCP to Cursor 🤖
1. Configure Cursor to Recognize MCP Servers
Open Settings and navigate to Tools and Integrations in the left panel.
Click the Add Custom MCP button to create the mcp.json config file in cursor
2. Add Yandex Search MCP to Cursor
Add the following text to your Claude Desktop configuration file:
{
"mcpServers": {
"yandexSearch": {
"type": "sse",
"url": "https://d5dj4o5pbnqgca1d546v.cmxivbes.apigw.yandexcloud.net:3000/sse",
"headers": {
"ApiKey": "<your_api_key>",
"FolderId": "<your_folder_id>"
}
}
}
}
3. Find information on the web with yandexSearch
- Verify the setup by typing the following text in the chat:
use yandexSearch to find information about the best AI Agent frameworks in 2025
- Cursor will ask you to confirm that it should use yandexSearch, click the Run Tool button or press (⌘↵) to confirm.
- You should see "called search-api_post" in the chat and the answer based on the web search results.
How to Add Yandex Search MCP to Visual Studio Code 🤖
1. Configure Visual Studio Code to Recognize MCP Servers
Enable the chat.mcp.enabled setting in VS Code to enable MCP support.
Add a .vscode/mcp.json file in your workspace to configure MCP servers for a workspace.
2. Add Yandex Search MCP to Visual Studio Code
Add the following text to your Claude Desktop configuration file:
{
"mcpServers": {
"yandexSearch": {
"type": "sse",
"url": "https://d5dj4o5pbnqgca1d546v.cmxivbes.apigw.yandexcloud.net:3000/sse",
"headers": {
"ApiKey": "<your_api_key>",
"FolderId": "<your_folder_id>"
}
}
}
}
3. Open CoPilot in Agent Mode
- Open the Chat view (⌃⌘I), and select Agent mode from the dropdown.
- Select the Tools button to view the list of available tools.
- The AI Agent will automatically select yandexSearch when it needs to find information on the internet.
- To ensure that the AI Agent uses yandexSearch click the Add Context Button, and select search-api_post from the available tools.
- For advanced configuration settings visit the official VS Code MCP tutorial
How to run Yandex Search MCP locally
Prerequisites
- Python 3.10+
- Node.js 16+ (for MCP development)
- Docker 20+ or Podman 3+ (for containerized deployment)
Installation
git clone git@github.com:yandex/yandex-search-mcp-server.git
cd /path/to/yandex-search-mcp-server
Option 1: Use Yandex Search MCP with Docker/Podman
Step 1. Build the container
To run the MCP server in a container using Docker or Podman:
- Ensure Docker and Docker Compose, or Podman and Podman Compose, are installed on your system.
- For Podman users: If you need to pull images from Docker Hub, first authenticate:
Enter your Docker Hub username and password when prompted.podman login docker.io - Build the container:
- Using Docker:
docker build -t yandex-mcp-server-image:latest . - Using Podman:
podman build -t yandex-mcp-server-image:latest .
- Using Docker:
This will create an image named yandex-mcp-server-image.
Step 2. Add MCP server configs and set SEARCH_API_KEY.
For MCP clients that support direct interaction with Docker or Podman containers, add one of these configurations to the MCP config in your MCP client of choice (e.g. mcp.json in VS Code):
- Using Docker:
{
"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"
]
}
}
}
- Using Podman:
{
"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"
]
}
}
}
Important: Replace <your_api_key> and <your_folder_id> with your actual Yandex Search API key and folder id. Ensure that only one instance of the server (local or Docker) is active at a time to avoid conflicts.
After updating the configuration, the system should automatically detect and run the server, exposing the ai_search_with_yazeka and web_search tools for use.
Option 2: Use Python + MCP Config
Step 1. Install required libraries
pip install -r requirements.txt
Step 2.1 Configure the MCP Settings in an MCP client
To setup the MCP server on your system using Python, add the following configuration to your MCP settings and set SEARCH_API_KEY:
{
"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"
]
}
}
}
Important: Replace <your_api_key> and <your_folder_id> with your actual Yandex Search API key and folder id. Update /path/to/mcp-server-demo to the actual path where the repository is located on your system if necessary.
After updating the configuration, the system should automatically detect and run the server, exposing the ai_search_with_yazeka and web_search tools for use.
Step 2.2 Launch the local MCP Server directly
To run the MCP server directly on your machine without containerization:
- Ensure you have Python 3.10+ installed.
- Set the required environment variable for the API key (replace
<your_api_key>and<your_folder_id>with your actual Yandex Search API key and folder id):
export SEARCH_API_KEY=<your_api_key>
- Run the server:
python3 server.py
The server will start and listen for input on stdin, responding on stdout. Typically, this server is integrated with a system that communicates via MCP, however you can send requests to the server from the terminal.
Example Requests
Copy and Paste these example requests in the terminal with the Yandex Search MCP server running locally to see the search results and the generative AI answer right in the terminal.
Web Search Example
{
"query": "Who won the most recent Formula 1 race in 2025?",
"search_region": "en"
}
AI Search Example
{
"query": "Who won the most recent Formula 1 race in 2025?",
"search_region": "en"
}
Troubleshooting
- If the server fails to start, ensure all dependencies are installed correctly (
pip install -r requirements.txt). - If you encounter authentication errors, double-check that the
SEARCH_API_KEYis correctly set in your environment or configuration.
Built by the Yandex team with ❤️