Skip to main content
Glama
geosp

MCP MixSearch

by geosp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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

Related MCP server: Serpex MCP

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

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.

Available Tools

3 tools
get_single_web_page_contentA

Extract and return the full content from a single web page URL.

Use this when you have a specific URL and need the full text content for analysis or reference.

Args: url: The URL of the web page to extract content from max_content_length: Maximum characters for the extracted content (0 = no limit)

Returns: Formatted text containing the extracted page content with word count

Parameter Usage Guidelines

url (required)

max_content_length (optional, default unlimited)

  • Limits the extracted content to specified character count

  • Common values: 10000 (summaries), 50000 (full pages), null (no limit)

Usage Examples

Basic content extraction:

{
  "url": "https://example.com/blog/ai-trends-2024"
}

Extract with content limit:

{
  "url": "https://docs.example.com/api-reference",
  "max_content_length": 20000
}

Extract documentation:

{
  "url": "https://github.com/project/docs/installation.md",
  "max_content_length": 10000
}

Extract complete article:

{
  "url": "https://techblog.com/comprehensive-guide"
}

Complete parameter example:

{
  "url": "https://docs.python.org/3/library/asyncio.html",
  "max_content_length": 50000
}

When to Choose This Tool

  • Choose this when you have a specific URL from search results or references

  • Choose this for extracting content from documentation, articles, or blog posts

  • Choose this when you need to analyze or reference specific webpage content

  • Choose this for following up on URLs found in search results

  • Choose this when extracting content from GitHub README files or documentation

Error Handling

  • If URL is inaccessible, an error message will be provided

  • Some sites may block automated access - try alternative URLs

  • Dynamic content may require multiple attempts

  • Large pages may timeout - use content length limits

Alternative Tools

  • Use full_web_search when you need to find relevant pages first

  • Use get_web_search_summaries for discovering URLs to extract

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
max_content_lengthNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (extracts content), what it returns (formatted text with word count), and includes important behavioral context like error handling (inaccessible URLs, blocked sites, timeouts) and practical constraints (dynamic content may require multiple attempts). The only minor gap is lack of explicit rate limit or authentication information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (description, args, returns, parameter guidelines, examples, when to choose, error handling, alternatives). While comprehensive, some sections like the multiple similar examples could be slightly condensed. However, every section adds value and the core purpose is front-loaded effectively.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (web content extraction with potential errors), no annotations, and an output schema present, the description provides complete context. It covers purpose, usage guidelines, parameter details, behavioral traits, error scenarios, and sibling tool differentiation. The presence of an output schema means the description doesn't need to detail return format, allowing it to focus on operational context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description provides comprehensive parameter documentation that fully compensates. It explains both parameters in detail: url requirements (valid HTTP/HTTPS, full URL with protocol, examples) and max_content_length behavior (optional, default unlimited, common values, practical use cases). The usage examples further clarify parameter semantics beyond what the bare schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verb ('extract and return') and resource ('full content from a single web page URL'). It distinguishes from sibling tools by focusing on content extraction from a specific URL rather than search functionality, with explicit differentiation in the 'Alternative Tools' section.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool ('when you have a specific URL and need the full text content for analysis or reference') and when not to use it (via the 'Alternative Tools' section that names specific sibling tools for different use cases). The 'When to Choose This Tool' section further elaborates with concrete scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_web_search_summariesA

Get lightweight web search results with only result summaries.

Use this when you need a quick overview of available sources without full content. This gets search result titles, URLs, and descriptions for quick research or when you only need an overview of available information.

Use this when you want to quickly understand what information is available on a topic before diving deeper with full content extraction.

Args: query: Search query string (1-200 characters) limit: Number of search result summaries to return (1-10, default 5) top_n: Alternative name for limit (for compatibility) recency_days: Days to look back for recent content (time filtering) source: Content type filter ("news", "images", "videos", etc.) language: Language filter (e.g., "en", "es", "fr", "de") country: Geographic filter (e.g., "US", "GB", "FR", "DE")

Returns: Formatted text containing search result summaries (title, URL, description)

Parameter Usage Guidelines

query (required)

  • Search query string (1-200 characters)

  • Use specific, descriptive search terms

limit (optional, default 5)

  • Range: 1-10 results

Usage Examples

Basic topic exploration:

{
  "query": "artificial intelligence ethics"
}

Quick source discovery:

{
  "query": "kubernetes security best practices",
  "limit": 3
}

Recent news exploration:

{
  "query": "AI developments",
  "source": "news",
  "recency_days": 7,
  "language": "en"
}

Geographic research:

{
  "query": "renewable energy policies",
  "country": "DE",
  "language": "en",
  "limit": 8
}

Content type discovery:

{
  "query": "machine learning tutorials",
  "source": "videos",
  "limit": 5
}

Complete parameter example:

{
  "query": "climate change adaptation strategies",
  "limit": 6,
  "recency_days": 30,
  "language": "en",
  "country": "US"
}

When to Choose This Tool

Primary Decision Criteria:

  • Choose this for initial research phase: Understand what sources are available

  • Choose this for topic exploration: Get an overview before deep diving

  • Choose this for source identification: Find relevant URLs for later extraction

  • Choose this for quick fact-checking: Verify if information sources exist

  • Choose this for research planning: Identify the scope of available information

Decision Matrix: When to Use Each Tool

Use get_web_search_summaries when:

  • ✅ You need to explore what's available on a topic

  • ✅ You want to identify relevant sources quickly

  • ✅ You're doing preliminary research

  • ✅ You need to validate if sources exist

  • ✅ You want to see search result diversity

  • ✅ Speed is more important than content depth

Use full_web_search when:

  • ✅ You need actual content from sources

  • ✅ You're doing detailed research or analysis

  • ✅ You need to cite or reference specific information

  • ✅ You want to compare information across sources

  • ✅ Content depth is more important than speed

Use get_single_web_page_content when:

  • ✅ You have specific URLs to extract

  • ✅ You found relevant URLs from summaries

  • ✅ You need to extract from known sources

Workflow Patterns

Two-stage research:

  1. Use get_web_search_summaries to identify sources

  2. Use get_single_web_page_content on promising URLs

  3. Or use full_web_search with focused query

Topic mapping:

  1. Use get_web_search_summaries with broad terms

  2. Analyze result diversity and topics

  3. Use full_web_search for detailed investigation

Source validation:

  1. Use get_web_search_summaries to check if sources exist

  2. Evaluate source quality and relevance

  3. Proceed with content extraction if validated

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
limitNo
top_nNo
recency_daysNo
sourceNo
languageNo
countryNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does well by explaining the tool returns 'lightweight' results with 'only result summaries' for 'quick overview', specifying the output format as 'Formatted text containing search result summaries (title, URL, description)', and providing usage examples. It doesn't mention rate limits or authentication needs, but covers the core behavior thoroughly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is comprehensive but lengthy with multiple sections (Args, Returns, Parameter Usage Guidelines, Usage Examples, When to Choose This Tool, Decision Matrix, Workflow Patterns). While well-structured and front-loaded with the core purpose, it could be more concise by integrating some sections. Every sentence adds value, but the overall length is substantial.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 7-parameter complexity, 0% schema coverage, no annotations, but with an output schema, the description is exceptionally complete. It covers purpose, usage guidelines, parameter semantics, behavioral context, sibling tool comparisons, and workflow patterns. The output schema handles return values, so the description appropriately focuses on usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates well by listing all 7 parameters with brief explanations in the Args section, providing a 'Parameter Usage Guidelines' section for the two most important parameters, and showing 6 detailed usage examples that demonstrate how parameters work together. It adds significant meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'Get lightweight web search results with only result summaries' and distinguishes it from siblings by specifying it's for 'quick overview of available sources without full content'. It explicitly contrasts with 'full_web_search' which provides actual content, making the distinction clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides extensive guidance including a 'When to Choose This Tool' section, a detailed decision matrix comparing it to sibling tools, workflow patterns, and explicit criteria like 'Choose this for initial research phase' and 'Speed is more important than content depth'. It clearly states when to use this tool versus 'full_web_search' and 'get_single_web_page_content'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updates
    • First observedfull_web_search
    • First observedget_single_web_page_content
    • First observedget_web_search_summaries
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.7/5.0

Scored across 3 tools

Disambiguation5/5

The three tools have clearly distinct purposes with no overlap: full_web_search for comprehensive search with content extraction, get_web_search_summaries for lightweight result overviews, and get_single_web_page_content for extracting content from specific URLs. The descriptions explicitly differentiate their use cases, and the decision matrix helps agents choose appropriately.

Naming Consistency5/5

All tool names follow a consistent snake_case pattern with clear verb_noun structure: full_web_search, get_web_search_summaries, and get_single_web_page_content. The naming is predictable and readable, with 'get' and 'full' prefixes appropriately indicating scope differences.

Tool Count5/5

Three tools is well-scoped for a web search and content extraction server. Each tool earns its place by covering distinct workflow stages: discovery (summaries), comprehensive search (full), and targeted extraction (single page). This minimal set effectively covers the domain without bloat.

Completeness5/5

The tool set provides complete coverage for web search and content extraction workflows. It supports discovery (summaries), in-depth research (full search with extraction), and follow-up on specific URLs (single page). The descriptions explicitly outline complementary use cases, leaving no obvious gaps for agents.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Web Search MCP Server

    vishalkg
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables web search across multiple search engines (DuckDuckGo, Bing, Startpage) with parallel execution and result deduplication. Also provides web page content extraction capabilities.
    2
    -

  • Serpex MCP

    divyeshradadiya
    A
    license
    B
    quality
    C
    maintenance
    Enables multi-engine web search capabilities across Google, Bing, DuckDuckGo, Brave, Yahoo, and Yandex through the Serpex API. Features automatic engine routing, time filtering, and structured JSON results for reliable web search integration.
    1
    17 npm
    MIT

  • MCP Deep Search

    just-every
    A
    license
    B
    quality
    B
    maintenance
    Enables deep web search across multiple providers including Google, Bing, Brave, DuckDuckGo, and Perplexity, with support for comprehensive AI-powered research using intelligent multi-engine queries.
    2
    221 npm
    9
    MIT

  • Web Search MCP

    pranavms13
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables web searching through Google, DuckDuckGo, and Bing using a headless Chrome browser, returning structured results with titles, URLs, and snippets. Also supports fetching and extracting text content from any webpage.
    14
    MIT

Appeared in Searches