MCP SearXNG Enhanced Server

What is MCP SearXNG Enhanced Server?

A Model Context Protocol (MCP) server for category-aware web search, website scraping, and date/time tools. Designed for seamless integration with SearXNG and modern MCP clients.

How to use MCP SearXNG Enhanced Server?

Run via Docker (docker run -i --rm --network=host -e SEARXNG_ENGINE_API_BASE_URL="http://<your-searxng>:8080/search" overtlids/mcp-searxng-enhanced:latest) or natively using Python 3.9+ (pip install -r requirements.txt && python mcp_server.py). Configure SearXNG endpoint and other settings via environment variables. The server can be used in stdio mode (default) or HTTP mode (--http flag).

Key features of MCP SearXNG Enhanced Server

• SearXNG-powered web search with category support (general, images, videos, files, map, social media)
• Website content scraping with citation metadata and automatic Reddit URL conversion
• PDF reading support with conversion to Markdown using PyMuPDF4LLM
• In-memory caching with automatic freshness validation
• Domain-based rate limiting to prevent service abuse
• Timezone-aware date/time tool

Use cases of MCP SearXNG Enhanced Server

• Build AI assistants that perform category-specific web searches (e.g., images, videos, maps)
• Scrape and extract content from websites with proper citation metadata
• Read and convert PDF documents into Markdown for downstream processing
• Get current date/time in a specified timezone without external API calls
• Rate‑limit and cache web requests to protect resources and reduce latency

FAQ from MCP SearXNG Enhanced Server

What are the prerequisites to run this server?

You need a running SearXNG instance (self-hosted or accessible endpoint) and either Docker installed or Python 3.9+ (Python 3.11 recommended). For native runs, install dependencies with pip install -r requirements.txt.

How do I configure the server?

Configuration is done via environment variables. The most critical one is SEARXNG_ENGINE_API_BASE_URL. You can also use an ods_config.json file (environment variables take precedence). See the Environment Variables table in the README for all options.

What transport modes are supported?

The server supports stdio transport (default, for MCP clients that spawn a subprocess) and HTTP transport (via FastMCP, for clients connecting via HTTP). In HTTP mode, the server listens on 0.0.0.0:8000 by default and accepts requests at /mcp. CORS is fully open.

How does caching and rate limiting work?

The server includes in-memory caching with configurable max size (default 100 entries), TTL (default 5 minutes), and maximum age (default 30 minutes). Rate limiting is domain‑based, with defaults of 10 requests per minute and a 60‑second timeout.

Can I run the server without Docker?

Yes. Clone the repository, create a virtual environment, install dependencies, set environment variables, and run python mcp_server.py (or python mcp_server.py --http for HTTP mode). Python 3.9 or newer is required.