MCP MixSearch

A comprehensive Model Context Protocol (MCP) server for advanced web search functionality with multi-engine support and intelligent backend selection.

Features

• Multi-Engine Search: Access to multiple search engines (Brave, DuckDuckGo, Google, Bing, Yandex) via DDGS library
• Advanced Filtering: Time-based, geographic, language, and content type filtering
• Intelligent Backend Selection: Automatically chooses optimal search engine based on parameters
• Full Content Extraction: Extract readable content from search results and specific URLs
• Dual Interface: Both MCP protocol and REST API with identical functionality
• Graceful Fallbacks: Browser-based search for reliability when APIs fail

Quick Start

Install and Run

# Install
uv sync

# Run in MCP stdio mode (default)
uv run mcp-mixsearch

# Run in MCP HTTP mode
uv run mcp-mixsearch --mode mcp

# Or run with REST API
uv run mcp-mixsearch --mode rest

Use as a Dependency

See Using as Dependency for creating your own MCP servers.

Configuration

Set environment variables in a .env file or export them:

# Server Configuration
MCP_HOST=localhost
MCP_PORT=3000
MCP_TRANSPORT=stdio  # or 'http'
MCP_AUTH_ENABLED=true
MCP_CORS_ORIGINS="http://localhost:3000,http://localhost:5173"

# Web Search Configuration
BRAVE_API_KEY=your_brave_api_key_here
MAX_CONTENT_LENGTH=500000
MAX_CONCURRENT_REQUESTS=5

# Logging
LOG_LEVEL=INFO

Running Modes

mcp-mixsearch supports three distinct running modes:

1. MCP HTTP Mode

Runs MCP server over HTTP without REST API endpoints.

uv run mcp-mixsearch --mode mcp

2. MCP Stdio Mode (Default)

Runs MCP server over stdio without REST API endpoints.

uv run mcp-mixsearch --mode stdio
# Or just run without flags (default)
uv run mcp-mixsearch

3. REST API + MCP Mode

Runs both REST API endpoints and MCP protocol over HTTP.

uv run mcp-mixsearch --mode rest

Environment Variables

You can also control modes using environment variables:

# MCP over HTTP
MCP_TRANSPORT=http MCP_ONLY=true uv run mcp-mixsearch

# MCP over stdio
MCP_TRANSPORT=stdio MCP_ONLY=true uv run mcp-mixsearch

# REST API + MCP over HTTP
MCP_TRANSPORT=http MCP_ONLY=false uv run mcp-mixsearch

In HTTP modes, the server runs on http://localhost:3000 with:

• MCP endpoint: http://localhost:3000/mcp
• REST API docs: http://localhost:3000/docs (when REST API enabled)
• Health check: http://localhost:3000/health (when REST API enabled)

Available Tools

MCP Tools

1. full_web_search

   • Comprehensive web search with content extraction
   • Multi-engine search with intelligent backend selection
   • Advanced filtering: time, language, geographic, content type filters
   • Args: query, limit (1-10), include_content, max_content_length, top_n, recency_days, source, language, country

2. get_web_search_summaries

   • Lightweight search returning only summaries
   • Same advanced filtering capabilities as full_web_search
   • Args: query, limit (1-10), top_n, recency_days, source, language, country

3. get_single_web_page_content

   • Extract content from a specific URL
   • Args: url, max_content_length

REST API Endpoints

• GET /search/full_web_search - Same as full_web_search with identical parameters
• GET /search/get_web_search_summaries - Same as get_web_search_summaries with identical parameters
• GET /search/get_single_web_page_content - Same as get_single_web_page_content

Advanced Search Features

Multi-Engine Architecture

• Primary: DDGS library with multiple backend support (Brave, DuckDuckGo, Google, Bing, Yandex)
• Intelligent backend selection: Automatically chooses best engine based on parameters
• Fallbacks: Browser-based search for reliability

Supported Parameters

• Core: query (required), limit/top_n, include_content, max_content_length
• Time filtering: recency_days (1=day, 7=week, 30=month, 365=year)
• Content type: source ("news", "images", "videos", "web")
• Language filtering: language (e.g., "en", "es", "fr", "de")
• Geographic filtering: country (e.g., "US", "GB", "FR", "DE")

Usage Examples

Basic search:

# MCP
{"query": "AI developments", "limit": 5}

# REST
GET /search/get_web_search_summaries?query=AI%20developments&limit=5

Advanced filtering:

# MCP
{"query": "climate policy", "country": "FR", "language": "fr", "recency_days": 30, "source": "news"}

# REST
GET /search/get_web_search_summaries?query=climate%20policy&country=FR&language=fr&recency_days=30&source=news

Project Structure

mcp-mixsearch/
├── features/             # Feature implementations
│   └── web_search/       # Web search feature
│       ├── __init__.py
│       ├── models.py     # Pydantic models
│       ├── service.py    # Multi-engine search logic
│       ├── tool.py       # MCP tool registrations
│       ├── routes.py     # REST API routes
│       ├── instructions.md          # Full web search documentation
│       ├── instructions_summaries.md # Search summaries documentation
│       └── instructions_single_page.md # Single page extraction documentation
├── config.py             # Configuration management
├── server.py             # Main server entry point
├── pyproject.toml        # Project configuration
├── uv.lock              # Dependency lock file
├── README.md
└── LICENSE

Development

Testing

pytest

Building

uv build

Dependencies

• mcp-weather: Core MCP infrastructure
• fastmcp: MCP protocol implementation
• httpx: HTTP client for content extraction
• playwright: Browser automation for dynamic content
• beautifulsoup4: HTML parsing
• fake-useragent: Random user agents

License

See LICENSE file.