SearXNG MCP-Server

Ein Model Context Protocol (MCP) Server, der Web-Suchfunktionen durch die Integration mit einer SearXNG-Instanz bereitstellt.

Funktionen

• Websuche: Führen Sie leistungsstarke aggregierte Suchen über mehrere Suchmaschinen hinweg durch.

• Erkennung: Rufen Sie programmatisch verfügbare Kategorien und Suchmaschinen ab.

• Zustandsloses HTTP: Kompatibel mit jedem Standard-JSON-RPC-Client.

• Flexible Konfiguration: Unterstützt Umgebungsvariablen und Befehlszeilenargumente.

Beispiel einer compose.yml zum Ausführen von SearXNG mit MCP-Server

services:
  searxng:
    image: searxng/searxng:latest
    ports:
      - 8080:8080
    volumes:
      - ./searxng/etc/:/etc/searxng/
      - ./searxng/data/:/var/cache/searxng/
    restart: always

  searxng-mcp:
    image: ghcr.io/aicrafted/searxng-mcp:latest
    restart: unless-stopped
    depends_on:
      # Ensure SearXNG starts before the MCP server
      - searxng
    environment:
      SEARXNG_URL: http://searxng:8080
      MCP_HOST: 0.0.0.0
      MCP_PORT: 32123
      MCP_TRANSPORT: "http"
    ports:
      - "32123:32123"

MCP-Client-Konfiguration

HTTP-Transport (empfohlen)

{
  "mcpServers": {
    "searxng": {
      "type": "http",
      "url": "http://localhost:32123/mcp"
    }
  }
}

SSE-Transport

{
  "mcpServers": {
    "searxng": {
      "type": "sse",
      "url": "http://localhost:32123/sse"
    }
  }
}

Hinweis: Der SSE-Transport verwendet den /sse-Endpunkt, nicht /mcp. Der HTTP-Transport verwendet /mcp.

Voraussetzungen für den Betrieb aus den Quellen

• Python 3.10+

• Eine laufende SearXNG-Instanz.

Installation

1. Klonen Sie das Repository und navigieren Sie in das Verzeichnis.

2. Installieren Sie die Abhängigkeiten:

   pip install -r requirements.txt

3. Richten Sie Ihre .env-Datei ein (optional):

   SEARXNG_URL=http://your-searxng-instance:8080
   MCP_PORT=32123
   MCP_HOST=127.0.0.1

Verwendung

Starten Sie den Server mit uv oder Standard-Python:

python searxng_mcp.py --transport http --port 32123 --searxng http://searx.lan

Ausführen mit Docker

1. Image erstellen:

   docker build -t searxng-mcp .

2. Container ausführen:

   docker run -d \
     -p 32123:32123 \
     -e SEARXNG_URL=http://your-searxng-instance:8080 \
     --name searxng-mcp \
     searxng-mcp

Transportoptionen

• stdio: Standard-Eingabe/Ausgabe (Standard für einige MCP-Clients).

• http: Zustandsloses HTTP (streamable-http).

• sse: Server-Sent Events.

Leitfaden für Suchfunktionen

SearXNG aggregiert Ergebnisse aus verschiedenen Quellen. Dieser Leitfaden beschreibt die Funktionen, die über das web_search-Tool verfügbar sind.

Suchkategorien

Kategorien helfen dabei, Ihre Suche nach Inhaltstyp zu verfeinern. Verwenden Sie diese im Parameter categories (durch Kommas getrennt).

Unterstützte Suchmaschinen

SearXNG kann über 130 Suchmaschinen abfragen. Konfigurierte Suchmaschinen umfassen typischerweise:

• Web: Google, Brave, DuckDuckGo, Qwant, Startpage

• Wissen: Wikipedia, Wikidata

• Entwicklung: GitHub, StackOverflow, PyPI

• Sozial: Reddit, Twitter/X

Erweiterte Suchparameter

• categories: Nach bestimmten Typen filtern (z. B. news,it).

• engines: Bestimmte Suchmaschinen erzwingen (z. B. google,wikipedia).

• language: Suchsprache angeben (z. B. en, es, fr).

• pageno: Durch mehrere Ergebnisseiten navigieren.

• time_range: Nach Datum filtern (day, month, year).

• safesearch: Inhaltsfilterung steuern (0=Keine, 1=Moderat, 2=Strikt).

Programmatische Erkennung

Verwenden Sie das web_search_info-Tool, um die Liste der aktivierten Kategorien und Suchmaschinen dynamisch von Ihrer Instanz abzurufen.

Fehlerbehebung unter Windows

localhost nicht erreichbar, während der Docker-Container läuft

Symptom: http://localhost:<port>/ gibt "Verbindung verweigert" zurück oder erreicht den falschen Dienst, aber curl aus dem Container heraus funktioniert einwandfrei.

Ursache: WSL2 Port-Relay-Geist

WSL2 leitet Ports automatisch von der Linux-VM an den Windows-Host weiter, indem wslrelay.exe verwendet wird. Wenn ein Prozess innerhalb von WSL einen Port abhört, erstellt WSL ein Relay, das an [::1]:<port> (IPv6-Loopback) auf der Windows-Seite gebunden ist.

Wenn dieser WSL-Prozess stoppt, gibt wslrelay.exe den Port oft nicht frei. Der Relay-Eintrag bleibt als Zombie-Listener auf [::1]:<port> aktiv.

Wenn Docker später einen Container auf denselben Host-Port mappt, bindet er korrekt an 0.0.0.0:<port> — aber [::1]:<port> ist bereits durch das veraltete Relay belegt.

Unter Windows wird localhost zuerst zu ::1 (IPv6) aufgelöst. Daher treffen Browser- und Curl-Anfragen an localhost:<port> auf den toten wslrelay.exe-Eintrag anstatt auf den Docker-Container, was zu einem Verbindungsfehler oder einer unerwarteten Antwort führt.

Die Verbindung über die explizite IPv4-Adresse 127.0.0.1:<port> umgeht das Relay und erreicht Docker korrekt.

Diagnose:

# Check what is listening on the port
netstat -ano | findstr :<port>

# Identify the processes
Get-Process -Id <pid1>,<pid2> | Select-Object Id,Name

Wenn Sie zwei Einträge für denselben Port sehen — einen im Besitz von com.docker.backend und einen anderen von wslrelay — ist dies das Problem.

Workarounds:

Dauerhafte Lösung:

Starten Sie nach wsl --shutdown den Docker-Container neu. Das Relay existiert dann nicht mehr und localhost:<port> funktioniert normal, bis derselbe Port innerhalb von WSL erneut verwendet wird.

Prävention:

Wenn Sie regelmäßig Dienste auf demselben Port sowohl in WSL als auch in Docker ausführen, bevorzugen Sie eine der folgenden Optionen:

• Verwenden Sie für diesen Dienst immer Docker, niemals direkt WSL

• Verwenden Sie unterschiedliche Ports für WSL-Entwicklungs- und Docker-Produktionsinstanzen

• Fügen Sie eine explizite Bindung 127.0.0.1:<port>:<port> in der docker-compose.yml hinzu, um IPv4 zu erzwingen

Verwandtes

• WSL2 Netzwerkdokumentation

• WSL GitHub Issue-Tracker: Suche nach wslrelay port leak