Skip to main content

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 searxng Python 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 --embedded flag — starts searxng's MCP server in-process (background thread) and connects via HttpSearchAdapter on 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 src directory.

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

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
--version Print the package version and exit. The version is also included in -h/--help output.
--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: --embedded is 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:11888 achieves 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 server
  • uvicorn, starlette, sse-starlette, anyio - Streamable HTTP transport
  • flask, waitress - Web server for embedded mode
  • aiohttp, beautifulsoup4 - Web scraping for Tavily adapter
  • pydantic - Data validation
  • pyyaml, platformdirs - Configuration
  • mcp-utils, strif, queuelib - MCP and queue utilities

Install with:

pip install -r requirements.txt

MCP Tools

Performs a web search using SearXNG with customizable parameters.

Parameters:

  • query (required): Search query string
  • categories: 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.22.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for easy-searxng-mcp-server 2026.11.22.1
File Size Uploaded Provenance Actions
easy_searxng_mcp_server-2026.11.22.1.tar.gz 30.6 kB Without provenance Details for easy_searxng_mcp_server-2026.11.22.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for easy-searxng-mcp-server 2026.11.22.1
File Interpreter ABI Platform Actions
easy_searxng_mcp_server-2026.11.22.1-py3-none-any.whl Python 3 none any Details for easy_searxng_mcp_server-2026.11.22.1-py3-none-any.whl

Total release size: 60.5 kB

Release files / easy_searxng_mcp_server-2026.11.22.1.tar.gz

Download URL easy_searxng_mcp_server-2026.11.22.1.tar.gz
Size 30.6 kB
Tags Source
SHA-256 checksum
How to use checksums
806c4439ae2effe43a1844eeddaadb71f0a8deb63336b46aed20c28f7a4aea63
BLAKE2b-256 checksum
How to use checksums
1d846f9c5481ae295ca98bdd0832393135c9b3da40ee9b07e236782bca44fc27
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.22.1-py3-none-any.whl

Download URL easy_searxng_mcp_server-2026.11.22.1-py3-none-any.whl
Size 29.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
293c11d6666012e90ddedcdce6b94b2e9f9b53ae9b63d168590d4ac673bc1fd8
BLAKE2b-256 checksum
How to use checksums
e984136d70f5ec1b6120187241681430809f97a6a81c2e013963250a04903719
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.22.1

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page