OvertliDS/mcp-searxng-enhanced

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.
Features
- 🔍 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
- 📜 Intial PDF reading support with a conversion to Markdown using PyMuPDF/PyMuPDF4LLM
- 💾 In-memory caching with automatic freshness validation
- 🚦 Domain-based rate limiting to prevent service abuse
- 🕒 Timezone-aware date/time tool
- ⚠️ Robust error handling with custom exception types
- 🐳 Dockerized and configurable via environment variables
- ⚙️ Configuration persistence between container restarts
Quick Start
Prerequisites
- Docker installed on your system
- A running SearXNG instance (self-hosted or accessible endpoint)
Installation & Usage
**Build the Docker image:**
**Run with your SearXNG instance (Manual Docker Run):**
In this example, SEARXNG_ENGINE_API_BASE_URL is explicitly set. DESIRED_TIMEZONE is also explicitly set to America/New_York, which matches its default value. If an environment variable is not provided using an -e flag during the docker run command, the server will automatically use the default value defined in its Dockerfile (refer to the Environment Variables table below). Thus, if you intend to use the default for DESIRED_TIMEZONE, you could omit the -e DESIRED_TIMEZONE="America/New_York" flag. However, SEARXNG_ENGINE_API_BASE_URL is critical and usually needs to be set to match your specific SearXNG instance's address if the Dockerfile default (http://host.docker.internal:8080/search) is not appropriate.
**Note on Manual Docker Run:** This command runs the Docker container independently. If you are using an MCP client (like Cline in VS Code) to manage this server, the client will start its own instance of the container using the settings defined in *its own configuration*. For the MCP client to use specific environment variables, they **must** be configured within the client's settings for this server (see below).
**Configure your MCP client** (e.g., Cline in VS Code):
For your MCP client to correctly manage and run this server, you **must** define all necessary environment variables within the client's settings for the overtlids/mcp-searxng-enhanced server. The MCP client will use these settings to construct the docker run command.
The following is the **recommended default configuration** for this server within your MCP client's JSON settings (e.g., cline_mcp_settings.json). This example explicitly lists all environment variables set to their default values as defined in the Dockerfile. You can copy and paste this directly and then customize any values as needed.
**Key Points for MCP Client Configuration:**
- The example above provides a complete set of arguments to run the Docker container with all environment variables set to their default values.
- To customize any setting, simply modify the value for the corresponding -e "VARIABLE_NAME=value" line within the args array in your MCP client's configuration. For instance, to change SEARXNG_ENGINE_API_BASE_URL and DESIRED_TIMEZONE, you would adjust their respective lines.
- Refer to the "Environment Variables" table below for a detailed description of each variable and its default.
- The server's behavior is primarily controlled by these environment variables. While an ods_config.json file can also influence settings (see Configuration Management), environment variables passed by the MCP client take precedence.
HTTP Server Mode (FastMCP)
In addition to the default stdio transport, the server can expose an MCP endpoint over HTTP using FastMCP. This is useful for clients that connect via HTTP rather than spawning a subprocess.
Starting the HTTP Server
The server will start on 0.0.0.0:8000 by default and accept MCP requests at: