MCP SearXNG verbessert

MCP SearXNG Enhanced Server

Ein Model Context Protocol (MCP)-Server für kategoriebasierte Websuche, Website-Scraping und Datums-/Zeit-Tools. Entwickelt für die nahtlose Integration mit SearXNG und modernen MCP-Clients.

Merkmale

🔍 SearXNG-gestützte Websuche mit Kategorieunterstützung (Allgemein, Bilder, Videos, Dateien, Karte, soziale Medien)
📄 Scraping von Website-Inhalten mit Zitat-Metadaten und automatischer Reddit-URL-Konvertierung
💾 In-Memory-Caching mit automatischer Aktualitätsvalidierung
🚦 Domänenbasierte Ratenbegrenzung zur Verhinderung von Dienstmissbrauch
🕒 Zeitzonenbewusstes Datums-/Uhrzeittool
⚠️ Robuste Fehlerbehandlung mit benutzerdefinierten Ausnahmetypen
🐳 Dockerisiert und über Umgebungsvariablen konfigurierbar
⚙️ Konfigurationspersistenz zwischen Containerneustarts

Schnellstart

Voraussetzungen

Docker auf Ihrem System installiert
Eine laufende SearXNG-Instanz (selbst gehostet oder zugänglicher Endpunkt)

Installation und Verwendung

Erstellen Sie das Docker-Image:

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

Führen Sie es mit Ihrer SearXNG-Instanz aus (manueller Docker-Ausführung):

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 diesem Beispiel ist SEARXNG_ENGINE_API_BASE_URL explizit festgelegt. DESIRED_TIMEZONE ist ebenfalls explizit auf America/New_York festgelegt, was seinem Standardwert entspricht. Wenn während des docker run -Befehls keine Umgebungsvariable mit dem Flag -e angegeben wird, verwendet der Server automatisch den in seinem Dockerfile definierten Standardwert (siehe Tabelle „Umgebungsvariablen“ unten). Wenn Sie also den Standardwert für DESIRED_TIMEZONE verwenden möchten, können Sie das Flag -e DESIRED_TIMEZONE="America/New_York" weglassen. SEARXNG_ENGINE_API_BASE_URL ist jedoch entscheidend und muss normalerweise so festgelegt werden, dass es mit der Adresse Ihrer spezifischen SearXNG-Instanz übereinstimmt, wenn der Standardwert des Dockerfiles ( http://host.docker.internal:8080/search ) nicht geeignet ist.

Hinweis zum manuellen Docker-Ausführen: Dieser Befehl führt den Docker-Container unabhängig aus. Wenn Sie einen MCP-Client (z. B. Cline in VS Code) zur Verwaltung dieses Servers verwenden, startet der Client eine eigene Instanz des Containers mit den in seiner Konfiguration definierten Einstellungen. Damit der MCP-Client bestimmte Umgebungsvariablen verwenden kann, müssen diese in den Client-Einstellungen für diesen Server konfiguriert werden (siehe unten).

Konfigurieren Sie Ihren MCP-Client (z. B. Cline in VS Code):

Damit Ihr MCP-Client diesen Server korrekt verwalten und ausführen kann, müssen Sie alle erforderlichen Umgebungsvariablen in den Clienteinstellungen für den Server overtlids/mcp-searxng-enhanced definieren. Der MCP-Client verwendet diese Einstellungen zum Erstellen des Befehls docker run .

Nachfolgend finden Sie die empfohlene Standardkonfiguration für diesen Server in den JSON-Einstellungen Ihres MCP-Clients (z. B. cline_mcp_settings.json ). Dieses Beispiel listet explizit alle Umgebungsvariablen auf, die auf ihre im Dockerfile definierten Standardwerte gesetzt sind. Sie können diese direkt kopieren und einfügen und anschließend die Werte nach Bedarf anpassen.

{
  "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=10",
        "-e", "MAX_FILE_RESULTS=5",
        "-e", "MAX_MAP_RESULTS=5",
        "-e", "MAX_SOCIAL_RESULTS=5",
        "-e", "TRAFILATURA_TIMEOUT=15",
        "-e", "SCRAPING_TIMEOUT=20",
        "-e", "CACHE_MAXSIZE=100",
        "-e", "CACHE_TTL_MINUTES=5",
        "-e", "CACHE_MAX_AGE_MINUTES=30",
        "-e", "RATE_LIMIT_REQUESTS_PER_MINUTE=10",
        "-e", "RATE_LIMIT_TIMEOUT_SECONDS=60",
        "-e", "IGNORED_WEBSITES=",
        "overtlids/mcp-searxng-enhanced:latest"
      ],
      "timeout": 60
    }
  }
}

Wichtige Punkte zur MCP-Client-Konfiguration:

Das obige Beispiel bietet einen vollständigen Satz von Argumenten zum Ausführen des Docker-Containers, wobei alle Umgebungsvariablen auf ihre Standardwerte gesetzt sind.
Um eine Einstellung anzupassen, ändern Sie einfach den Wert der entsprechenden Zeile -e "VARIABLE_NAME=value" im Array args in der Konfiguration Ihres MCP-Clients. Um beispielsweise SEARXNG_ENGINE_API_BASE_URL und DESIRED_TIMEZONE zu ändern, passen Sie die entsprechenden Zeilen an.
Eine detaillierte Beschreibung der einzelnen Variablen und ihrer Standardwerte finden Sie in der Tabelle „Umgebungsvariablen“ weiter unten.
Das Verhalten des Servers wird primär durch diese Umgebungsvariablen gesteuert. Obwohl eine ods_config.json Datei ebenfalls Einstellungen beeinflussen kann (siehe Konfigurationsverwaltung), haben die vom MCP-Client übergebenen Umgebungsvariablen Vorrang.

Native Ausführung (ohne Docker)

Wenn Sie den Server lieber direkt mit Python ohne Docker ausführen möchten, führen Sie die folgenden Schritte aus:

1. Python-Installation:

Dieser Server erfordert Python 3.9 oder neuer . Python 3.11 (wie im Docker-Image verwendet) wird empfohlen.
Sie können Python von python.org herunterladen.

2. Klonen Sie das Repository:

Holen Sie sich den Code von GitHub:
git clone https://github.com/OvertliDS/mcp-searxng-enhanced.git cd mcp-searxng-enhanced

3. Erstellen und Aktivieren einer virtuellen Umgebung (empfohlen):

Die Verwendung einer virtuellen Umgebung hilft bei der Verwaltung von Abhängigkeiten und der Vermeidung von Konflikten mit anderen Python-Projekten.
# For Linux/macOS python3 -m venv .venv source .venv/bin/activate # For Windows (Command Prompt) python -m venv .venv .\.venv\Scripts\activate.bat # For Windows (PowerShell) python -m venv .venv .\.venv\Scripts\Activate.ps1

4. Abhängigkeiten installieren:

Installieren Sie die erforderlichen Python-Pakete:
pip install -r requirements.txt
Zu den wichtigsten Abhängigkeiten zählen httpx , BeautifulSoup4 , pydantic , trafilatura , python-dateutil , cachetools und zoneinfo .

5. Stellen Sie sicher, dass SearXNG zugänglich ist:

Sie benötigen weiterhin eine laufende SearXNG-Instanz. Stellen Sie sicher, dass Sie die API-Basis-URL haben (z. B. http://127.0.0.1:8080/search ).

6. Umgebungsvariablen festlegen:

Der Server wird über Umgebungsvariablen konfiguriert. Mindestens müssen Sie wahrscheinlich SEARXNG_ENGINE_API_BASE_URL festlegen.
Linux/macOS (bash/zsh):
export SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search" export DESIRED_TIMEZONE="America/Los_Angeles"
Windows (Eingabeaufforderung):
set SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search" set DESIRED_TIMEZONE="America/Los_Angeles"
Windows (PowerShell):
$env:SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search" $env:DESIRED_TIMEZONE="America/Los_Angeles"
Alle verfügbaren Optionen finden Sie in der Tabelle „Umgebungsvariablen“ weiter unten. Wenn keine Einstellungen vorgenommen werden, werden die Standardwerte aus dem Skript oder einer ods_config.json -Datei (sofern im Stammverzeichnis oder unter ODS_CONFIG_PATH vorhanden) verwendet.

7. Starten Sie den Server:

Führen Sie das Python-Skript aus:
python mcp_server.py
Der Server wird gestartet und wartet über stdin/stdout auf MCP-Clientverbindungen.

8. Konfigurationsdatei ( ods_config.json ):

Alternativ oder in Kombination mit Umgebungsvariablen können Sie eine Datei ods_config.json im Stammverzeichnis des Projekts (oder im durch die Umgebungsvariable ODS_CONFIG_PATH angegebenen Pfad) erstellen. Umgebungsvariablen haben immer Vorrang vor den Werten in dieser Datei. Beispiel: json { "searxng_engine_api_base_url": "http://127.0.0.1:8080/search", "desired_timezone": "America/New_York" }

Umgebungsvariablen

Die folgenden Umgebungsvariablen steuern das Verhalten des Servers. Sie können sie in der Konfiguration Ihres MCP-Clients (empfohlen für clientverwaltete Server) oder beim manuellen Ausführen von Docker festlegen.

Variable	Beschreibung	Standard (aus Dockerfile)	Hinweise
`SEARXNG_ENGINE_API_BASE_URL`	SearXNG-Suchendpunkt	`http://host.docker.internal:8080/search`	Entscheidend für den Serverbetrieb
`DESIRED_TIMEZONE`	Zeitzone für Datums-/Uhrzeittool	`America/New_York`	Z. B. `America/Los_Angeles` . Liste der Zeitzonen der tz-Datenbank: https://en.wikipedia.org/wiki/List\_of\_tz\_database\_time\_zones
`ODS_CONFIG_PATH`	Pfad zur persistenten Konfigurationsdatei	`/config/ods_config.json`	Wird normalerweise als Standard im Container belassen.
`RETURNED_SCRAPPED_PAGES_NO`	Maximale Anzahl der pro Suche zurückgegebenen Seiten	`3`
`SCRAPPED_PAGES_NO`	Maximale Anzahl der Seiten, für die ein Scraping versucht werden soll	`5`
`PAGE_CONTENT_WORDS_LIMIT`	Maximale Wörter pro Scraped-Seite	`5000`
`CITATION_LINKS`	Zitationsereignisse aktivieren/deaktivieren	`True`	`True` oder `False`
`MAX_IMAGE_RESULTS`	Maximale zurückzugebende Bildergebnisse	`10`
`MAX_VIDEO_RESULTS`	Maximale zurückzugebende Videoergebnisse	`10`
`MAX_FILE_RESULTS`	Maximale zurückzugebende Dateiergebnisse	`5`
`MAX_MAP_RESULTS`	Maximale zurückzugebende Kartenergebnisse	`5`
`MAX_SOCIAL_RESULTS`	Maximale Social Media-Ergebnisse für die Rückkehr	`5`
`TRAFILATURA_TIMEOUT`	Zeitüberschreitung bei der Inhaltsextraktion (Sekunden)	`15`
`SCRAPING_TIMEOUT`	HTTP-Anforderungstimeout (Sekunden)	`20`
`CACHE_MAXSIZE`	Maximale Anzahl zwischengespeicherter Websites	`100`
`CACHE_TTL_MINUTES`	Cache-Lebensdauer (Minuten)	`5`
`CACHE_MAX_AGE_MINUTES`	Maximales Alter für zwischengespeicherte Inhalte (Minuten)	`30`
`RATE_LIMIT_REQUESTS_PER_MINUTE`	Maximale Anfragen pro Domäne pro Minute	`10`
`RATE_LIMIT_TIMEOUT_SECONDS`	Ratenbegrenzungs-Trackingfenster (Sekunden)	`60`
`IGNORED_WEBSITES`	Durch Kommas getrennte Liste der zu ignorierenden Sites	`""` (leer)	Z. `"example.com,another.org"`

Konfigurationsmanagement

Der Server verwendet einen dreistufigen Konfigurationsansatz:

Skript-Standardwerte (in Python fest codiert)
Konfigurationsdatei (geladen aus ODS_CONFIG_PATH , standardmäßig /config/ods_config.json )
Umgebungsvariablen (höchste Priorität)

Die Konfigurationsdatei wird nur aktualisiert, wenn:

Die Datei existiert noch nicht (erste Initialisierung)
Umgebungsvariablen werden explizit für den aktuellen Lauf bereitgestellt

Dadurch wird sichergestellt, dass Benutzerkonfigurationen zwischen Containerneustarts erhalten bleiben, wenn keine neuen Umgebungsvariablen festgelegt werden.

Tools und Aliase

Werkzeugname	Zweck	Aliase
`search_web`	Websuche über SearXNG	`search` , `web_search` , `find` , `lookup_web` , `search_online` , `access_internet` , `lookup` *
`get_website`	Scrapen von Website-Inhalten	`fetch_url` , `scrape_page` , `get` , `load_website` , `lookup` *
`get_current_datetime`	Aktuelles Datum/Uhrzeit	`current_time` , `get_time` , `current_date`

* lookup ist kontextsensitiv:

Wenn es mit einem url Argument aufgerufen wird, wird es auf get_website abgebildet.
Andernfalls wird es auf search_web abgebildet.

Beispiel: Tools aufrufen

Websuche

{ "name": "search_web", "arguments": { "query": "open source ai" } }

oder mit einem Alias:

{ "name": "search", "arguments": { "query": "open source ai" } }

Kategoriespezifische Suche

{ "name": "search_web", "arguments": { "query": "landscapes", "category": "images" } }

Website Scraping

{ "name": "get_website", "arguments": { "url": "example.com" } }

oder mit einem Alias:

{ "name": "lookup", "arguments": { "url": "example.com" } }

Aktuelles Datum/Uhrzeit

{ "name": "get_current_datetime", "arguments": {} }

oder:

{ "name": "current_time", "arguments": {} }

Erweiterte Funktionen

Kategoriespezifische Suche

Das Tool search_web unterstützt verschiedene Kategorien mit maßgeschneiderten Ausgaben:

Bilder : Gibt Bild-URLs, Titel und Quellseiten mit optionaler Markdown-Einbettung zurück
Videos : Gibt Videoinformationen zurück, einschließlich Titel, Quelle und eingebettete URLs
Dateien : Gibt herunterladbare Dateiinformationen zurück, einschließlich Format und Größe
Karte : Gibt Standortdaten einschließlich Koordinaten und Adressen zurück
Soziale Medien : Gibt Beiträge und Profile von sozialen Plattformen zurück
Allgemein : Standardkategorie, die den gesamten Webseiteninhalt durchsucht und zurückgibt

Reddit-URL-Konvertierung

Beim Scraping von Reddit-Inhalten werden URLs automatisch konvertiert, um die Domäne old.reddit.com zur besseren Inhaltsextraktion zu verwenden.

Ratenbegrenzung

Die domänenbasierte Ratenbegrenzung verhindert übermäßige Anfragen an dieselbe Domäne innerhalb eines Zeitfensters. Dies verhindert eine Überlastung der Zielwebsites und eine mögliche IP-Blockierung.

Cache-Validierung

Zwischengespeicherte Website-Inhalte werden automatisch anhand ihres Alters auf Aktualität geprüft. Veraltete Inhalte werden automatisch aktualisiert, während gültige zwischengespeicherte Inhalte schnell bereitgestellt werden.

Fehlerbehandlung

Der Server implementiert ein robustes Fehlerbehandlungssystem mit diesen Ausnahmetypen:

MCPServerError : Basis-Ausnahmeklasse für alle Serverfehler
ConfigurationError : Wird ausgelöst, wenn die Konfigurationseinstellungen ungültig sind
SearXNGConnectionError : Wird ausgelöst, wenn die Verbindung zu SearXNG fehlschlägt
WebScrapingError : Wird ausgelöst, wenn das Web Scraping fehlschlägt
RateLimitExceededError : Wird ausgelöst, wenn die Ratenbegrenzung für eine Domäne überschritten wird

Fehler werden ordnungsgemäß mit informativen Meldungen an den Client weitergegeben.

Fehlerbehebung

Verbindung zu SearXNG kann nicht hergestellt werden : Stellen Sie sicher, dass Ihre SearXNG-Instanz ausgeführt wird und die Umgebungsvariable SEARXNG_ENGINE_API_BASE_URL auf den richtigen Endpunkt verweist.
Ratenbegrenzungsfehler : Passen Sie RATE_LIMIT_REQUESTS_PER_MINUTE an, wenn zu viele Ratenbegrenzungsfehler auftreten.
Langsame Inhaltsextraktion : Erhöhen Sie TRAFILATURA_TIMEOUT , um mehr Zeit für die Inhaltsverarbeitung auf komplexen Seiten zu haben.
Docker-Netzwerkprobleme : Bei Verwendung von Docker Desktop unter Windows/Mac sollte host.docker.internal auf den Hostcomputer aufgelöst werden. Unter Linux müssen Sie möglicherweise stattdessen die IP-Adresse des Hosts verwenden.

Danksagung

Inspiriert von:

SearXNG – Datenschutzfreundliche Metasuchmaschine
Trafilatura – Web Scraping Tool zur Textextraktion
ihor-sokoliuk/mcp-searxng – Original-MCP-Server für SearXNG
nnaoycurt ( Besseres Websuchtool )
@bwoodruff2021 ( GetTimeDate-Tool )

MCP SearXNG Enhanced

Integrations