MCP MixSearch
MCP MixSearch is an MCP server for multi-engine web search, result summarization, and web page content extraction.
Search the web using Brave API, DDGS metasearch, and browser-scraping fallbacks.
Apply time, language, country, and content-type filters (news, images, videos, web).
Extract full page content with trafilatura and headless Firefox for JavaScript-heavy pages.
Get lightweight search summaries with titles, URLs, and descriptions.
Extract content from a specific URL with optional length limits.
Run over MCP stdio or streamable HTTP.
Safely fetch only public HTTP(S) URLs by default, rejecting private/loopback/link-local addresses.
Provides web search capabilities using Brave's search API as one of the supported search engine backends for multi-engine search functionality.
Enables web search through DuckDuckGo's search engine with support for advanced filtering including time-based, geographic, language, and content type parameters.
Offers web search functionality through Google's search engine as part of the multi-engine search architecture with intelligent backend selection.
Uses Pydantic models for data validation and serialization in the web search feature implementation.
Provides testing framework for the MCP server development and quality assurance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP MixSearch find recent AI breakthroughs in the last month from news sources"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-authConfiguration
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-mixsearchMCP 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-mixsearchThe 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/mcpHealth check:
http://localhost:3000/health
Run uv run mcp-mixsearch --help for all options, including --log-level.
Available Tools
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
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
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.
Brave Search API: only when
BRAVE_API_KEYis set (web and news)DDGS: metasearch library,
backendfromDDGS_BACKEND(autoby default)Brave (browser): scrapes search.brave.com in headless Firefox
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_lengthTime 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 refinescountryinto a region such asca-frGeographic 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
└── LICENSEDevelopment
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 checkBrowser-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 buildDependencies
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 toolsfull_web_searchA
Get comprehensive web search results with full page content extraction.
Use this when you need detailed content from web sources for comprehensive research and analysis. This searches the web and extracts the full content from each result page.
Use this for comprehensive research or detailed information from web sources.
Args: query: Search query string (1-200 characters) limit: Number of results to return with full content (1-10, default 5) include_content: Whether to extract full page content (default true) max_content_length: Maximum characters per result content (0 = no limit) 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 results with full extracted content
Parameter Usage Guidelines
query (required)
Search query string (1-200 characters)
Use specific, descriptive search terms
limit (optional, default 5)
Range: 1-10 results
Higher limits take longer due to content extraction
include_content (optional, default true)
Set to
truefor full content extraction (default)Set to
falseto get only titles, URLs, and descriptions
max_content_length (optional, default unlimited)
Limits characters per result to manage response size
Common values:
10000(focused content),50000(detailed research),null(no limit)
top_n (optional, compatibility parameter)
Alternative name for
limitparameterRange: 1-10 results
recency_days (optional, time filtering)
Filters results to recent content only
Common values:
1(past day),7(past week),30(past month),365(past year)Use
-1ornullfor no time filter
source (optional, content type filtering)
Filters by content type
Supported values:
"news": News articles and current events"images": Image search results"videos": Video content"web"or null: Regular web search (default)
language (optional, language filtering)
Filters results by language
Supported values: Language codes like
"en","es","fr","de","zh"
country (optional, geographic filtering)
Filters results by geographic region/country
Supported values: Country codes like
"US","GB","FR","DE","CA"
Usage Examples
Basic search with default settings:
{
"query": "sustainable energy solutions 2024"
}Quick overview (smaller limit):
{
"query": "latest AI developments",
"limit": 3
}Recent news search with time filtering:
{
"query": "AI technology breakthroughs",
"source": "news",
"recency_days": 7,
"language": "en"
}Geographic and language filtering:
{
"query": "climate change policy",
"country": "FR",
"language": "fr",
"limit": 5
}Comprehensive research with all parameters:
{
"query": "machine learning frameworks comparison",
"limit": 8,
"include_content": true,
"max_content_length": 25000,
"recency_days": 30,
"language": "en"
}Content type specific search:
{
"query": "python tutorial",
"source": "videos",
"limit": 5,
"include_content": false
}Source identification only:
{
"query": "quantum computing breakthroughs",
"limit": 5,
"include_content": false
}When to Use This
Use when you need detailed content from multiple sources
Use for comprehensive research on complex topics
Use when analyzing and comparing information across sources
Use for gathering supporting evidence or documentation
Use when you need the full context from web pages
Related Functionality
For quick topic exploration without content, use the search summaries functionality
When you have a specific URL to extract, use the single page content extraction functionality
Inputs: query (required), limit, include_content, max_content_length, +5 more. Returns: object
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)
Must be a valid HTTP or HTTPS URL
Include the full URL with protocol (http:// or https://)
Examples:
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_searchwhen you need to find relevant pages firstUse
get_web_search_summariesfor 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:
Use
get_web_search_summariesto identify sourcesUse
get_single_web_page_contenton promising URLsOr use
full_web_searchwith focused query
Topic mapping:
Use
get_web_search_summarieswith broad termsAnalyze result diversity and topics
Use
full_web_searchfor detailed investigation
Source validation:
Use
get_web_search_summariesto check if sources existEvaluate source quality and relevance
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
Scored across 3 tools
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.
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.
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.
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
Multi-engine web and platform search, news, Google Maps places, page reading, sitemaps, and trends.
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
Web search, URL content extraction to Markdown, site mapping, and recursive web crawler.
Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables web search across multiple search engines (DuckDuckGo, Bing, Startpage) with parallel execution and result deduplication. Also provides web page content extraction capabilities.2MIT
- AlicenseBqualityCmaintenanceEnables 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.245 npm9MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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.16MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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,209MIT