Konnek SearXNG MCP Server
This project implements an MCP (Model Context Protocol) server for SearXNG integration, providing web search functionality for AI agents.
Purpose
This server is developed to serve as a dedicated, open, and reliable metasearch solution for AI agents. Its goal is to provide a strong, high-quality search backend that can replace or supplement commercial search APIs like Tavily, Bing Search, and Brave Search.
Features
- MCP Compliance: Implements the MCP protocol for search operations.
- SearXNG Integration: Uses the
searxngPython library to interact with SearXNG instances. - Dual Search Methods:
search: Basic search via SearXNG client.web_search: Full-featured web search with categories, engines, language, time range, safe search, and result limits.
- Tavily-Compatible Adapter: Provides a Tavily-compatible interface
(
TavilyAdapter) that wraps SearXNG results in Tavily's response format. - Embedded SearXNG: Optional embedded local SearXNG MCP server via
--embeddedflag — starts searxng's MCP server in-process (background thread) and connects viaHttpSearchAdapteron localhost. No separate Flask server required. - Dual Transport Support:
- stdio: MCP over Standard Input/Output (default).
- streamable-http: MCP over Streamable HTTP (Starlette + uvicorn).
- PEP 8 compliant: Code follows Python's style guide.
- RealPython Project Layout: Source code is organised under the
srcdirectory.
Directory Structure
easy-searxng-mcp-server/
├── src/
│ ├── __init__.py
│ ├── main.py # Core server implementation
│ ├── common/
│ │ ├── __init__.py
│ │ └── config.py # Configuration and logging
│ ├── shared/
│ │ ├── __init__.py
│ │ └── types.py # Shared data types (TavilyResult, etc.)
│ ├── tavily/
│ │ ├── __init__.py
│ │ ├── adapter.py # Tavily-compatible adapter
│ │ └── settings/
│ │ ├── __init__.py
│ │ └── tavily_defaults.yml
│ ├── runner/
│ │ ├── __init__.py
│ │ ├── simplexng.py # Embedded SearXNG server
│ │ └── settings/
│ │ ├── __init__.py
│ │ └── settings_template.yml
│ └── mcp_server/
│ ├── __init__.py
│ └── server.py # MCP server with web_search tool
├── pyproject.toml # Project configuration and dependencies
├── server_entry.sh # Entry script
└── README.md # This file
Usage
Via uvx (recommended)
uvx --from easy-searxng-mcp-server easy-searxng-mcp-server [OPTIONS]
Direct execution from source
cd <path-to-source>
./server_entry.sh [OPTIONS]
Supported Options
| Flag | Description |
|---|---|
--transport |
MCP transport: stdio (default) or streamable-http. |
--embedded |
Start searxng MCP server in-process on localhost, then connect via HttpSearchAdapter. No separate Flask server required. |
--http |
Connect to a remote SearXNG instance via HTTP (requires --searxng-url or SEARXNG_URL env var). |
--searxng-url |
URL of the remote SearXNG instance (e.g., http://127.0.0.1:11888). |
--host |
Host to bind for streamable-http transport (default: 127.0.0.1). |
--port |
Port to bind for streamable-http transport (default: 8000). |
--sxng-port |
Port for embedded SearXNG server (default: 11888). |
--sxng-host |
Host for embedded SearXNG server (default: 127.0.0.1). |
--embeddings-url |
OpenAI-compatible embeddings endpoint URL for VectorRAG reranking. |
--embeddings-model |
Embedding model name (omit for llama-server to use loaded model). |
--embeddings-dim |
Embedding dimension (omit for llama-server to use model's n_embd). |
Note:
--embeddedis the recommended way to run locally. It starts the SearXNG MCP server in-process and connects automatically. Using--searxng-url=http://127.0.0.1:11888achieves the same result but requires you to start the SearXNG server separately.
VectorRAG (Optional)
When the EMBEDDINGS_URL environment variable is set, the server uses VectorRAG to rerank search results by semantic similarity using LanceDB + OpenAI-compatible embeddings.
| Env Var | Default | Description |
|---|---|---|
EMBEDDINGS_URL |
— | OpenAI-compatible embeddings endpoint URL (required for VectorRAG) |
EMBEDDINGS_MODEL |
— | Embedding model name (omit for llama-server to use loaded model) |
EMBEDDINGS_DIM |
— | Embedding dimension (omit for llama-server to use model's n_embd) |
RERANK_TOP_K |
5 |
Number of top results after reranking |
Example:
export EMBEDDINGS_URL=http://localhost:8080/v1
uvx --from easy-searxng-mcp-server easy-searxng-mcp-server --embedded
Examples
Embedded SearXNG with stdio transport (recommended for local use):
./server_entry.sh --embedded --transport stdio
Then enter MCP requests in JSON format:
{"method": "search", "query": "python programming"}
Embedded SearXNG with streamable-http transport:
./server_entry.sh --embedded --transport streamable-http --host 127.0.0.1 --port 8000
MCP endpoint: http://127.0.0.1:8000/mcp
Web Search with parameters:
{
"method": "web_search",
"query": "artificial intelligence",
"categories": ["general", "news"],
"engines": ["google", "bing", "duckduckgo"],
"language": "en",
"max_results": 10,
"time_range": "week",
"safe_search": 1
}
Remote Mode with streamable-http:
export SEARXNG_URL="http://your-searxng-instance:8080"
./server_entry.sh --transport streamable-http --host 0.0.0.0 --port 8000
Or with explicit URL:
./server_entry.sh --searxng-url "http://your-searxng-instance:8080" --transport streamable-http
Environment Variables
| Variable | Description |
|---|---|
SEARXNG_URL |
URL of the remote SearXNG instance. |
TAVILY_TIMEOUT |
Tavily adapter HTTP timeout (default: 10). |
TAVILY_USER_AGENT |
User agent for Tavily adapter. |
TAVILY_MAX_RESULTS |
Max results for Tavily adapter (default: 10). |
TAVILY_CONTENT_LENGTH |
Content length for Tavily adapter (default: 2500). |
Supported File Formats
The server uses markitdown for converting various file formats to text. When enabled, the following formats are supported:
| Format | Installation | Description |
|---|---|---|
[pptx] |
pip install 'easy-searxng-mcp-server[pptx]' |
PowerPoint files |
[docx] |
pip install 'easy-searxng-mcp-server[docx]' |
Word files |
[xlsx] |
pip install 'easy-searxng-mcp-server[xlsx]' |
Excel files (newer) |
[xls] |
pip install 'easy-searxng-mcp-server[xls]' |
Excel files (older) |
[pdf] |
pip install 'easy-searxng-mcp-server[pdf]' |
PDF files |
[outlook] |
pip install 'easy-searxng-mcp-server[outlook]' |
Outlook messages |
[audio-transcription] |
pip install 'easy-searxng-mcp-server[audio-transcription]' |
Audio transcription (wav, mp3) using FasterWhisper |
[youtube-transcription] |
pip install 'easy-searxng-mcp-server[youtube-transcription]' |
YouTube video transcription |
To install all optional dependencies:
pip install 'easy-searxng-mcp-server[all-formats]'
Or via uvx:
uvx --from 'easy-searxng-mcp-server[all-formats]' easy-searxng-mcp-server
Audio transcription uses FasterWhisper for high-performance speech recognition. The Whisper base model is bundled with the package, so no internet download is required. The model size can be configured via the WHISPER_MODEL environment variable (default: base, falls back to downloaded model if bundled not found).
Dependencies
- Python 3.8+
searxng- Core SearXNG client and MCP serveruvicorn,starlette,sse-starlette,anyio- Streamable HTTP transportflask,waitress- Web server for embedded modeaiohttp,beautifulsoup4- Web scraping for Tavily adapterpydantic- Data validationpyyaml,platformdirs- Configurationmcp-utils,strif,queuelib- MCP and queue utilities
Install with:
pip install -r requirements.txt
MCP Tools
web_search
Performs a web search using SearXNG with customizable parameters.
Parameters:
query(required): Search query stringcategories: Search categories (e.g.,["general", "news"])engines: Search engines (e.g.,["google", "bing", "duckduckgo"])language: Language code (default:"auto")max_results: Maximum results (default: 5, range: 1-50)time_range: Time filter (day,week,month,year,all)safe_search: Safe search level (0=normal, 1=moderate, 2=strict)
Development
The project follows PEP 8 guidelines and the RealPython project layout
with source code in the src directory.
Metadata
Release files for easy-searxng-mcp-server 2026.11.20
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| easy_searxng_mcp_server-2026.11.20.tar.gz | 24.6 kB | Without provenance | Details for easy_searxng_mcp_server-2026.11.20.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| easy_searxng_mcp_server-2026.11.20-py3-none-any.whl | Python 3 | none | any | Details for easy_searxng_mcp_server-2026.11.20-py3-none-any.whl |
Total release size: 54.3 kB
Release files / easy_searxng_mcp_server-2026.11.20.tar.gz
| Download URL | easy_searxng_mcp_server-2026.11.20.tar.gz |
|---|---|
| Size | 24.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8ca12b9324ffcc636678e74a450ad7700372977a460d2574c755427755718750
|
|
BLAKE2b-256 checksum How to use checksums |
f2d09b89cb6d7c4014d86cea7138b1adebec2e4e6ec70275bc72cb5673b78c94
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.22
|
Release files / easy_searxng_mcp_server-2026.11.20-py3-none-any.whl
| Download URL | easy_searxng_mcp_server-2026.11.20-py3-none-any.whl |
|---|---|
| Size | 29.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
321b1970ed29543ee501cbb47e6c714f923c6f9586fa236fdc555f9246dda1da
|
|
BLAKE2b-256 checksum How to use checksums |
b5d6ceba9c2303f1b40572de08bedc02411a984fc4b1d21ca9d34df79d57c3ae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.22
|
Security for easy-searxng-mcp-server 2026.11.20
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.