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.

Related MCP server: WET - Web Extended Toolkit

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

Via uvx (recommended)

uvx --from easy-searxng-mcp-server easy-searxng-mcp-server [OPTIONS]

Direct execution from source

cd /resources/Projects/easy-searxng-mcp-server
./server_entry.sh [OPTIONS]

Supported Options

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.

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

Supported File Formats

The server uses markitdown for converting various file formats to text. When enabled, the following formats are supported:

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 model size can be configured via the WHISPER_MODEL environment variable (default: tiny).

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

web_search

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.