yandex-search

This MCP server provides two tools to let AI assistants search the web via Yandex Search: ai_search_post and web_search_post. The ai_search_post tool performs a real-time web search and returns an AI-generated answer based on the search results using Yandex Yazeka AI model. The web_search_post tool also performs a real-time web search but returns an answer with sources, enabling you to cite where information came from. To use these tools, configure your MCP client to expose the yandex-search-api server and authorize with your API credentials. Once running, your agent can invoke the tools to fetch fresh information from the web and incorporate it into responses. The server is designed to protect safety and provide up-to-date results by querying Yandex’s Search API in real time.

Prerequisites:

• Python 3.10+
• Docker 20+ or Podman 3+ (optional for containerized deployment)
• Access to a Yandex Search API key with yc.search-api.execute scope and a valid Folder ID

Option 1: Run directly with Python

1. Install dependencies (if any are specified in the project):
   • Create and activate a virtual environment (optional but recommended): python -m venv venv source venv/bin/activate # Unix/macOS venv\Scripts\activate # Windows
2. Ensure you have your server code (server.py) in place and your API credentials ready.
3. Start the MCP server: python server.py
4. Ensure your MCP client configuration points to the running Python server, and provide environment variables:
   • SEARCH_API_KEY: <your_api_key>
   • FOLDER_ID: <your_folder_id>

Option 2: Run with Docker

1. Build the container image (from the repository root): docker build -t yandex-mcp-server-image:latest .
2. Run the container, passing credentials as environment variables: docker run -d --name yandex-mcp-container
   -e SEARCH_API_KEY=<your_api_key>
   -e FOLDER_ID=<your_folder_id>
   yandex-mcp-server-image:latest
3. Ensure your MCP client configuration points to the container and the server exposes the appropriate interface (e.g., stdio or HTTP/SSE as supported).

Option 3: Use Podman (alternative to Docker)

1. Build the image: podman build -t yandex-mcp-server-image:latest .
2. Run the container with credentials: podman run -d --name yandex-mcp-container
   -e SEARCH_API_KEY=<your_api_key>
   -e FOLDER_ID=<your_folder_id>
   yandex-mcp-server-image:latest
3. Connect your MCP client to the running container as needed.

Notes:

• Replace <your_api_key> and <your_folder_id> with your actual credentials. Ensure only one instance runs at a time to avoid conflicts.
• The server exposes tools named ai_search_post and web_search_post for web querying. Your MCP client should be configured to use these tools.
• If using Docker/Podman, ensure network accessibility between the MCP client and the container is properly configured (ports, hostnames, etc.).

Tips and common issues:

• API key and Folder ID must be valid and have the yc.search-api.execute scope and the search-api.editor role respectively.
• If you encounter authentication errors, double-check that the environment variables are correctly passed to the server process.
• When running in container environments, ensure that the container has network access to the MCP client and that any required ports are exposed or reachable.
• For Claude/Cursor integration, the MCP client configuration should reference the running server's URL or local endpoint and include the necessary headers or options as shown in the README (ApiKey and FolderId).
• If you see rate-limiting or quota errors from Yandex, verify your plan limits and consider implementing backoff handling in your MCP client calls.