Skip to main content
Glama
MCP MixSearch
by geosp

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: The official Brave Search API (with a key) and the DDGS metasearch library, with browser-scraping fallbacks

  • Advanced Filtering: Time-based, geographic, language, and content type filtering

  • Full Content Extraction: Main-content extraction with trafilatura, rendering JavaScript pages in a shared headless Firefox when needed

  • Safe Fetching: Only public http(s) URLs are fetched (see Security)

  • Two Transports: MCP over stdio or streamable HTTP, built on mcp-service-kit

  • Graceful Fallbacks: Browser-based search for reliability when APIs fail

Related MCP server: MCP Deep Search

Quick Start

Install and Run

# Install
uv sync

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

# Run in MCP HTTP mode (local use: no auth)
uv run mcp-mixsearch --mode http --no-auth

Configuration

Set environment variables in a .env file or export them. CLI flags take precedence over .env.

# Server Configuration (mcp-service-kit)
MCP_TRANSPORT=stdio     # or 'http'  (--mode)
MCP_HOST=0.0.0.0        # (--host)
MCP_PORT=3000           # (--port)
MCP_AUTH_ENABLED=false  # (--no-auth)

# Web Search Configuration
BRAVE_API_KEY=your_brave_api_key_here  # optional: enables the Brave Search API engine
MAX_CONTENT_LENGTH=500000              # default per-page content limit (characters)
MAX_CONCURRENT_REQUESTS=5              # concurrent page extractions
DDGS_BACKEND=auto                      # ddgs backend(s), e.g. auto or duckduckgo,bing
ALLOW_PRIVATE_URLS=false               # true allows private/loopback URLs (trusted networks only)

Running Modes

MCP Stdio Mode (Default)

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

MCP HTTP Mode

uv run mcp-mixsearch --mode http --port 3000 --no-auth
# Or via the environment
MCP_TRANSPORT=http MCP_AUTH_ENABLED=false uv run mcp-mixsearch

The server has no auth provider, so HTTP mode needs --no-auth (MCP_AUTH_ENABLED=false); without it the server refuses to start. Put an authenticating gateway in front of it if it is reachable by others.

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

  • MCP endpoint: http://localhost:3000/mcp

  • Health check: http://localhost:3000/health

Run uv run mcp-mixsearch --help for all options, including --log-level.

Available 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

Advanced Search Features

Multi-Engine Architecture

Engines are tried in order. The first result set whose titles and descriptions match the query well enough is used; if none does, the best one found is returned.

  1. Brave Search API: only when BRAVE_API_KEY is set (web and news)

  2. DDGS: metasearch library, backend from DDGS_BACKEND (auto by default)

  3. Brave (browser): scrapes search.brave.com in headless Firefox

  4. DuckDuckGo (HTML): scrapes the DuckDuckGo HTML results page

Page content is fetched over HTTP and extracted with trafilatura. Pages that need JavaScript or return a bot check are rendered in one shared headless Firefox, with a new browser context per page.

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"). Applied directly by the Brave Search API; for the other engines it refines country into a region such as ca-fr

  • Geographic filtering: country (e.g., "US", "GB", "FR", "DE")

Security

The extraction tools fetch URLs chosen by the model, so they only fetch public http(s) URLs. file:// and other schemes are rejected, and so are hosts that resolve to loopback, private, link-local (including cloud metadata such as 169.254.169.254) or other non-public addresses. The check runs before the fetch, on every HTTP redirect, and on every request the browser makes. Set ALLOW_PRIVATE_URLS=true only on trusted networks where fetching internal sites is intended.

Known limitation: DNS rebinding (a host that resolves to a public address when checked and a private one when connected) is not prevented.

Usage Examples

Basic search:

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

Advanced filtering:

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

Project Structure

mcp-mixsearch/
├── features/             # Feature implementations
│   └── web_search/       # Web search feature
│       ├── __init__.py
│       ├── service.py    # Orchestrates engines and content extraction
│       ├── engines.py    # Brave API, DDGS, Brave and DuckDuckGo scraping engines
│       ├── extraction.py # HTTP + trafilatura extraction with browser fallback
│       ├── browser.py    # Shared headless Firefox
│       ├── filters.py    # Normalized search filters and per-engine parameters
│       ├── url_safety.py # Public http(s) URL guard
│       ├── models.py     # SearchResult
│       ├── tool.py       # MCP tool registrations
│       ├── instructions.md          # Full web search documentation
│       ├── instructions_summaries.md # Search summaries documentation
│       └── instructions_single_page.md # Single page extraction documentation
├── tests/                # pytest suite (offline by default)
├── config.py             # Configuration management
├── server.py             # Main server entry point
├── pyproject.toml        # Project configuration
├── uv.lock              # Dependency lock file
├── README.md
└── LICENSE

Development

Testing

uv run pytest          # offline tests: network, DNS and the browser are faked
uv run pytest -m live  # live tests against real search engines and websites
uv run ruff check

Browser-based paths need Firefox for Playwright: uv run playwright install firefox. CI (.github/workflows/ci.yml) runs ruff and the offline tests on pull requests and pushes to main.

Building

uv build

Dependencies

  • mcp-service-kit: MCP server infrastructure (transports, CLI, config)

  • fastmcp: MCP protocol implementation

  • ddgs: Metasearch library

  • httpx: HTTP client for search APIs and content extraction

  • trafilatura: Main-content extraction

  • playwright: Browser automation for dynamic content (pinned to match the Docker image's Firefox)

  • 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

Inputs: url (required), max_content_length. Returns: object

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

Inputs: query (required), limit, top_n, recency_days, +3 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    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.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      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
      MIT
    • A
      license
      B
      quality
      C
      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
      45 npm
      9
      MIT
    • 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.
      16
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables comprehensive web searching and content extraction using multiple search engines (Bing, Brave, DuckDuckGo) without API keys. Provides tools for full web searches with content extraction, quick search summaries, and single webpage content retrieval.
      1,209
      MIT