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.

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:

docker build -t overtlids/mcp-searxng-enhanced:latest .

Run with your SearXNG instance (Manual Docker Run):

docker run -i --rm --network=host \
  -e SEARXNG_ENGINE_API_BASE_URL="http://127.0.0.1:8080/search" \
  -e DESIRED_TIMEZONE="America/New_York" \
  overtlids/mcp-searxng-enhanced:latest

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.

{
  "mcpServers": {
    "overtlids/mcp-searxng-enhanced": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network=host",
        "-e", "SEARXNG_ENGINE_API_BASE_URL=http://host.docker.internal:8080/search",
        "-e", "DESIRED_TIMEZONE=America/New_York",
        "-e", "ODS_CONFIG_PATH=/config/ods_config.json",
        "-e", "RETURNED_SCRAPPED_PAGES_NO=3",
        "-e", "SCRAPPED_PAGES_NO=5",
        "-e", "PAGE_CONTENT_WORDS_LIMIT=5000",
        "-e", "CITATION_LINKS=True",
        "-e", "MAX_IMAGE_RESULTS=10",
        "-e", "MAX_VIDEO_RESULTS=

... [View full README on GitHub](https://github.com/OvertliDS/mcp-searxng-enhanced#readme)