MCP Yandex Search Server

A Model Context Protocol (MCP) server that provides web search capabilities through the Yandex Search API. This server integrates with any MCP-compatible client.

Features

• Web Search: Full-text search through Yandex Search API
• Advanced Filtering: Language filtering, safe search, pagination support
• MCP Protocol: Compatible with any MCP client
• Async/Await: Built with async Python for optimal performance
• Structured Results: Returns formatted Markdown results
• Environment Config: Supports .env files for credential management

Installation

Prerequisites

• Python 3.10 or higher
• Yandex Cloud account with API credentials

Install Dependencies

Or install with pip in editable mode:

Configuration

1. Get Yandex Cloud credentials:

   • Create a service account in Yandex Cloud Console
   • Generate an API key for the service account
   • Note your Folder ID

2. Create a

   .env
   file in the project root:

3. Edit
   .env
   and add your credentials:

Note: The project uses

Usage

Standalone

Run the server directly:

Or using the installed script:

With MCP Inspector

Test the server using the MCP Inspector:

With MCP Client

For a global installation that works across all projects:

1. Install the package globally:

2. Create a global
   ~/.mcp.json
   file (or use the project
   .mcp.json
   as a reference):

Note: The project includes

Alternative Configuration with uv

Or with

Available Tools

yandex_search

Search the web using Yandex Search API.

Parameters:

• query
  (string, required): Search query text
• count
  (integer, optional): Number of results (1-10, default: 5)
• offset
  (integer, optional): Pagination offset (default: 0)
• language
  (string, optional): Language code (default: "en")
• safe_search
  (string, optional): Safe search level - "off", "moderate", "strict" (default: "moderate")

Example:

Development

Important: Security

Never commit credentials to version control!

• .env
  files with real credentials are gitignored
• .mcp.json
  with real API keys should be gitignored
• Use
  .env.example
  and template config files instead

The project includes a

• Virtual environments (
  venv/
  )
• Environment files (
  .env
  )
• Test cache and coverage (
  .pytest_cache/
  ,
  .coverage
  )
• User configurations (
  .mcp.json
  )

Running Tests

With coverage:

Project Structure

mcp-yandex-search/
├── mcp_server/
│   ├── __init__.py
│   ├── main.py          # MCP server entry point
│   ├── client.py        # Yandex Search API client
│   └── formatters.py    # Result formatting
├── tests/
│   ├── __init__.py
│   ├── test_server.py
│   └── test_client.py
├── requirements.txt
├── pyproject.toml
├── .env.example
├── .mcp.json            # Example MCP client config
└── README.md

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.

Installing on Other Computers

To use this MCP server on different computers:

Option 1: Copy the Project

1. Clone or copy this repository to the new computer
2. Install dependencies:
   pip install -r requirements.txt
3. Follow the configuration steps above

Environment Variables

For better security, use environment variables instead of hardcoding credentials:

Then in

The empty strings will be replaced by the shell environment variables.