🔍 SearXNG MCP Server

Datenschutzorientierte Websuche für KI-Assistenten – nutzen Sie eine betreiberseitig kontrollierte oder vertrauenswürdige SearXNG-Instanz mit Claude, Cursor und mehr.

Ein MCP-Server, der die SearXNG-API integriert und KI-Assistenten Websuchfunktionen bietet.

✨ Vorgestellt im GitHub MCP Registry.

Schnellstart

Fügen Sie dies zu Ihrer MCP-Client-Konfiguration hinzu (z. B. claude_desktop_config.json):

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Ersetzen Sie YOUR_SEARXNG_INSTANCE_URL durch die URL Ihrer SearXNG-Instanz (z. B. https://searxng.example.com). Sie können auch austauschbare Replikate als durch Semikolons getrennte Liste angeben, z. B. https://one.example.com;https://two.example.com.

Für verifizierte Rezepte für Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code, Windsurf, Cline und OpenCode siehe das Kochbuch für MCP-Client-Konfigurationen.

Für eine begrenzte, clientneutrale Methode zum Suchen, Prüfen von Quellen, Quervergleichen von Behauptungen und Zitieren von Belegen siehe den evidenzbasierten Forschungs-Workflow.

Für gemessene CPU- und Speicher-Ausgangspunkte des MCP-Prozesses siehe gemessene Bereitstellungsprofile.

Related MCP server: SearXNG MCP Server

Funktionen

• Websuche: Allgemeine, Nachrichten- und Artikelabfragen mit Paginierung, Zeitraum-/Sprach-/Safesearch-Filtern, Relevanzfilterung (min_score) und formatierter Text- oder Roh-JSON-Ausgabe, die pro Aufruf (response_format) oder mit der Betreiber-Standardeinstellung (SEARXNG_DEFAULT_RESPONSE_FORMAT) ausgewählt wird.

• Instanz-Failover und Fan-out: Konfigurieren Sie austauschbare SearXNG-Replikate in SEARXNG_URL; Suchanfragen schalten standardmäßig der Reihe nach um, oder fragen Sie mit SEARXNG_FANOUT alle gesunden Replikate parallel ab und führen die Ergebnisse zusammen.

• Direkte Antworten und Metadaten: Textergebnisse zeigen SearXNG-Antworten, Korrekturen, Vorschläge und Infoboxen vor der Ergebnisliste an.

• Suchvorschläge: Autovervollständigung über den /autocompleter-Endpunkt von SearXNG.

• Erkennung von Instanzfunktionen: Untersuchen Sie konfigurierte Kategorien, Engines, Standardwerte, Gebietsschemata und Plugins aus /config.

• URL-Inhaltslesen: Inhaltstypbewusste Markdown-Konvertierung, einschließlich begrenzter PDF-Textextraktion, mit Paginierung, Abschnittsfilterung, Absatzbereichen und Überschriftenextraktion.

• Browser-Solver-Unterstützung: Für jede nicht zwischengespeicherte URL, die die statische URL-Validierung und die HEAD-Größen-Vorprüfung besteht, kann optional eine Browser-Sitzung von FlareSolverr, Byparr oder beiden erworben werden. Anschließend werden der zurückgegebene User-Agent und die begrenzten Cookies über den begrenzten URL-Reader wiedergegeben. Im Dual-Provider-Modus ist FlareSolverr immer primär, und Byparr wird nur nach einem ausgelasteten oder vorübergehend nicht verfügbaren primären Anbieter versucht. FlareSolverr 3.5.0 und Byparr 2.1.0 wurden am 30.07.2026 verifiziert.

• Intelligentes Caching: Sowohl Suchergebnisse als auch URL-Inhalte werden im Speicher mit konfigurierbarer TTL und LFU-Verdrängung (am wenigsten häufig verwendet) zwischengespeichert, wodurch redundante Anfragen reduziert werden.

• SSRF-Schutz: web_url_read blockiert standardmäßig private/interne URLs und Weiterleitungen in allen Transportmodi.

• HTTP-Transport: Optionaler MCP-SDK-v2-Streamable-HTTP-Modus mit optionaler Härtung, Ratenbegrenzung und begrenzter zustandsloser Kompatibilität für serverlose oder horizontal skalierte Bereitstellungen. Moderne Anfragen vom 28.07.2026 und beibehaltene Legacy-Clients teilen sich dieselbe Tool- und Ressourcenoberfläche.

• HTML-Fallback: Optionales Parsen von Ergebnissen aus der HTML-Seite für öffentliche Instanzen, die format=json ablehnen.

• Lite-Tools-Modus: Minimale Tool-Schemas für lokale Modelle mit kleinen Kontextfenstern.

• Proxy-Unterstützung: Globale oder pro-Tool-HTTP/HTTPS-Proxys für Such- und URL-Reader-Datenverkehr.

Die verifizierten linux/amd64-Images stammen aus Multi-Architektur-Manifesten ghcr.io/flaresolverr/flaresolverr:v3.5.0@sha256:139dfee1c6f89249c8d665d1333a42e8ec74ec0a86bc6bb1c8461e10d3a66a47 und ghcr.io/thephaseless/byparr:2.1.0@sha256:01a46a2865d9a6db5eb8ead04ec0dd33b8fbe233e8565ae70b50d4cc0af4cfb0. Die Client-Abbruch stoppt lokale Arbeiten umgehend, aber ein entfernter Browser kann bis zu seinem konfigurierten Provider-Timeout weiterlaufen, nachdem der HTTP-Client die Verbindung getrennt hat. Siehe Browser-Solver-Verifizierung.

Warum mcp-searxng?

Stand 29.07.2026 spiegelt der folgende Fähigkeitsvergleich die offiziellen Brave MCP-, Exa MCP- und Firecrawl MCP-Projekte wider. „Paginierung“ bedeutet eine offengelegte Seiten- oder Offset-Steuerung. „Selbst gehostet“ bedeutet, dass der Suchdienst unter Ihrer Kontrolle laufen kann. „Kostenlos / Kein API-Schlüssel“ bedeutet, dass dieser MCP-Server keinen kostenpflichtigen Suchanbieter-API-Schlüssel erfordert; Sie betreiben oder wählen weiterhin die zugrunde liegende SearXNG-Instanz.

Der Datenschutz hängt von der SearXNG-Bereitstellung ab. Eine betreiberseitig kontrollierte Instanz kann vermeiden, einem Drittanbieter-Suchbetreiber zu vertrauen, während eine öffentliche Instanz die Abfrage empfängt und möglicherweise protokolliert. SearXNG und diese MCP-Integration bieten für sich genommen keine Anonymität.

So funktioniert es

mcp-searxng ist ein eigenständiger MCP-Server – ein separater Node.js-Prozess, mit dem sich Ihr KI-Assistent für die Websuche verbindet. Er fragt eine SearXNG-Instanz oder eine durch Semikolons getrennte Liste austauschbarer SearXNG-Replikate über die HTTP-JSON-API ab.

Kein SearXNG-Plugin: Dieses Projekt kann nicht als natives SearXNG-Plugin installiert werden. Richten Sie es auf eine beliebige vorhandene SearXNG-Instanz oder eine austauschbare Replikatliste aus, indem Sie SEARXNG_URL festlegen.

AI Assistant (e.g. Claude)
        │  MCP protocol
        ▼
  mcp-searxng  (this project — Node.js process)
        │  HTTP JSON API  (SEARXNG_URL)
        ▼
  SearXNG instance(s)

Für SearXNG-Bereitstellung, -Konfiguration und -Fehlerbehebung siehe Betreiben von selbst gehostetem SearXNG mit mcp-searxng.

Werkzeuge

• searxng_web_search

  • Websuche mit Paginierung ausführen

  • Eingaben:

    • query (string): Die Suchanfrage. Diese Zeichenkette wird an externe Suchdienste übergeben.

    • pageno (number, optional): Suchseitennummer, beginnt bei 1 (Standard: 1)

    • time_range (string, optional): Ergebnisse nach Zeitraum filtern – einer von: "day", "week", "month", "year" (Standard: keine)

    • language (string, optional): Sprachcode für Ergebnisse (z. B. "en", "fr", "de") oder "all" (Standard: "all")

    • safesearch (string enum, optional): Filterstufe für die sichere Suche, eine von "0" (Keine), "1" (Moderat) oder "2" (Streng). Legacy-Zahlenwerte 0, 1 und 2 werden aus Gründen der Abwärtskompatibilität weiterhin akzeptiert. (Standard: Instanzeinstellung)

    • min_score (number, optional): Mindestrelevanzwert von 0,0 bis 1,0. Ergebnisse unter diesem Wert werden herausgefiltert.

    • num_results (number, optional): Maximale Anzahl zurückzugebender Ergebnisse, von 1 bis 20. SEARXNG_MAX_RESULTS gilt als Obergrenze für den Operator.

    • categories (string, optional): Kommagetrennte SearXNG-Kategorien (z. B. "news", "it,science"). Live-/config-Fähigkeiten werden über erreichbare Instanzen aggregiert; bevorzugen Sie searxng_instance_info categories.common für konsistente Multi-Instanz-Ergebnisse. Bekannte Werte werden getrimmt und case-insensitiv normalisiert; unbekannte Werte werden getrimmt weitergeleitet, sodass SearXNG sie ignorieren oder berücksichtigen kann. Wenn /config nicht verfügbar ist, werden Werte mit einer Warnung unverändert weitergeleitet. Wenn nicht angegeben, verwendet jede Instanz ihre serverseitige Standardeinstellung.

    • engines (string, optional): Kommagetrennte SearXNG-Engine-Namen (z. B. "google,bing,ddg", "semantic scholar"). Live-/config-Fähigkeiten werden über erreichbare Instanzen aggregiert; bevorzugen Sie searxng_instance_info engines.common.enabled für konsistente Multi-Instanz-Ergebnisse. Bekannte Werte werden getrimmt und case-insensitiv normalisiert, einschließlich standardmäßig deaktivierter Engines; unbekannte Werte werden getrimmt weitergeleitet, sodass SearXNG sie ignorieren oder berücksichtigen kann. Wenn /config nicht verfügbar ist, werden Werte mit einer Warnung unverändert weitergeleitet. Wenn nicht angegeben, verwendet jede Instanz ihre serverseitige Standardeinstellung.

    • response_format (string, optional): Antwortformat, entweder "text" für formatierte, agentenlesbare Ausgabe oder "json" für rohes SearXNG-JSON mit gefilterten/geschnittenen results. Wenn nicht angegeben, gilt SEARXNG_DEFAULT_RESPONSE_FORMAT; wenn nicht gesetzt oder ungültig, wird text verwendet. Ein explizites response_format hat immer Vorrang.

    • result_detail (string, optional): "full" (die Standardeinstellung) bewahrt SearXNG-Metadaten, Warnungen, Herkunft, Antworten, Infoboxen, Korrekturen und Vorschläge. "compact" gibt nur Titel, URL und den Beschreibungs-/Inhaltsausschnitt für jedes Ergebnis zurück; kompaktes JSON verwendet genau die Schlüssel title, url und content. Verwenden Sie "full", wenn diese Recherchesignale wichtig sind.

    • Clients, die explizit response_format=text senden oder automatisch injizieren, überschreiben weiterhin die Operator-Standardeinstellung. Wenn ausgelassene Aufrufe nach der JSON-Konfiguration weiterhin Text zurückgeben, prüfen Sie die vom MCP-Client ausgegebenen Argumente.

  Migration: Kompakter Text hat genau drei Zeilen pro Ergebnis und keine Cache-Anmerkung oder Präambel. Aktualisieren Sie Zeilenparser, die Relevanzwerte oder Suchmetadaten erwarten, um result_detail="full" anzufordern (oder akzeptieren Sie die dreizeiligen Datensätze von "compact").

  Kompakt unterdrückt bewusst Warnungen, Herkunft und jedes andere Suchsignal. Volltext kann gültige optionale Zeilen in fester Reihenfolge hinzufügen: Punktzahl, Engines, Kategorie, Veröffentlichungsdatum, Vorschaubild, Bildquelle; ungültige optionale Metadaten werden weggelassen. Textfelder werden auf einzelne Zeilen normalisiert. SEARXNG_MAX_RESULT_CHARS kürzt Ergebnisinhalte in kompakten und vollständigen Text-/JSON-Antworten, einschließlich vollständigem JSON für bestehende Benutzer, die die Variable bereits gesetzt haben; kompakter Text normalisiert Zeilentrenner vor der Anwendung der Obergrenze, während JSON den ursprünglichen Zeichenfolgenwert begrenzt.

  Mit SEARXNG_LITE_TOOLS=true bleibt das Lite-Schema nur abfragebasiert, aber explizit angegebene optionale Überschreibungen wie response_format und result_detail werden weiterhin validiert und berücksichtigt.

• searxng_search_suggestions

  • Autovervollständigungsvorschläge zur Verfeinerung von Suchanfragen abrufen

  • Eingaben:

    • query (string): Teilweise oder vollständige Abfrage zur Autovervollständigung.

    • language (string, optional): Sprachcode für Vorschläge (z. B. "en", "fr", "de") oder "all" (Standard: "all")

• searxng_instance_info

  • Kategorien entdecken, die aus erreichbaren konfigurierten SearXNG-Instanzen aggregiert werden, optional Engine-Namen einschließen und Standardwerte, Gebietsschemata und Plugins aus der primären erreichbaren Instanz prüfen. Kategorien – und Engines, wenn angefordert – melden common-Werte, die auf jeder erreichbaren Instanz vorhanden sind, und available-Werte, die auf mindestens einer erreichbaren Instanz vorhanden sind.

  • Eingaben:

    • includeEngines (boolean, optional): Aktivierte Engine-Namen in die Antwort aufnehmen. (Standard: false)

    • includeDisabled (boolean, optional): Deaktivierte Engine-Namen aufnehmen, wenn includeEngines true ist. (Standard: false)

    • category (string, optional): Kategorien und Engines auf einen einzelnen Kategorienamen filtern.

    • refresh (boolean, optional): Den Prozesscache umgehen und frische /config-Daten abrufen. (Standard: false)

• web_url_read

  • URL-Inhalt als Markdown mit content-type-bewusster Verarbeitung und erweiterten Extraktionsoptionen lesen

  • Unterstützte lesbare Inhalte:

    • HTML (text/html, application/xhtml+xml) wird in Markdown konvertiert

    • JSON (application/json, *+json) wird in einem umschlossenen Block hübsch formatiert

    • Klartext, YAML, TOML, XML und andere sichere explizite text/*-Antworten werden als lesbarer umschlossener Text zurückgegeben

    • PDF (application/pdf)-Text wird in einem ressourcenbegrenzten Worker für Dokumente bis zu 500 Seiten extrahiert

    • Fehlende oder generische Inhaltstypen werden unter der bestehenden Größenbegrenzung gelesen; nicht-binäre Körper durchlaufen weiterhin den HTML-zu-Markdown-Pfad für Kompatibilität

  • PDF-Eingabe und extrahierter Text sind jeweils auf den niedrigeren Wert von URL_READ_MAX_CONTENT_LENGTH_BYTES und 16 MiB begrenzt. OCR wird nicht unterstützt, und gescannte/nur-Bild- oder passwortgeschützte PDFs geben eine kurze Erklärung zurück.

  • Eine als PDF deklarierte Antwort muss mit der Signatur %PDF- beginnen; eine Abweichung deutet normalerweise auf eine Zwischen- oder Fehlerseite hin, die mit dem falschen Inhaltstyp ausgeliefert wird.

  • Die PDF-Analyse hat ein separates 30-Sekunden-Worker-Budget nach dem Herunterladen des Antwortkörpers. Auf dem direkten Pfad dauern Netzwerkabruf und Analyse höchstens das konfigurierte Abrufbudget plus 30 Sekunden; konfigurierte Browser-Solver-Vorabprüfung und -Erfassungszeit kommen hinzu.

  • Es laufen höchstens zwei PDF-Extraktionen gleichzeitig pro MCP-Prozess. Es gibt keine Warteschlange; zusätzliche gleichzeitige Lesevorgänge geben eine Auslastungsmeldung zurück und können erneut versucht werden.

  • Andere Binär-, Medien-, Archiv- und Octet-Stream-Downloads werden absichtlich mit einem kurzen Hinweis abgelehnt, anstatt rohe Bytes zurückzugeben

  • Wenn FLARESOLVERR_URL oder BYPARR_URL konfiguriert ist, wird eine nicht zwischengespeicherte URL validiert und durch die HEAD-Größen-Vorabprüfung geprüft, bevor mcp-searxng die Browser-Sitzungserfassung versucht. Wenn beide gesetzt sind, wird zuerst FlareSolverr versucht und Byparr nur nach einem belegten Slot, Netzwerk-/Timeout-Fehler, HTTP 408/429/5xx oder einer fehlerhaften/überdimensionierten Antwort. Anhaltende Provider-4xx, Abbruch, Validierungsfehler des Lösungs-Hosts und gelöster Nicht-2xx-Zielstatus stoppen die Kette. Wenn jeder konfigurierte Provider belegt oder nicht verfügbar ist, wird ein nicht zwischengespeicherter direkter Abruf ausgeführt. Jeder versuchte Provider erhält die ursprüngliche Ziel-URL; der Erfolg der Herausforderung ist nicht garantiert.

  • Bei Standardlimits hat der Dual-Provider-Modus ein additives Maximum von 150 Sekunden über die anfängliche HEAD-Vorabprüfung, beide Solver-Versuche (einschließlich Antwortfrist) und den endgültigen direkten Abruf.

  • Eingaben:

    • url (string): Die abzurufende und zu verarbeitende URL

    • startChar (number, optional): Startzeichenposition für die Inhaltsextraktion (Standard: 0)

    • maxLength (number, optional): Maximale Anzahl zurückzugebender Zeichen

    • section (string, optional): Inhalt unter einer bestimmten Überschrift extrahieren (sucht nach Überschriftentext)

    • paragraphRange (string, optional): Bestimmte Absatzbereiche zurückgeben (z. B. '1-5', '3', '10-')

    • readHeadings (boolean, optional): Nur eine Liste von Überschriften statt des vollständigen Inhalts zurückgeben

Installation

Node.js 22 oder höher ist erforderlich.

npm install -g mcp-searxng

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Vorgefertigtes Image:

docker pull isokoliuk/mcp-searxng:latest

Image-Signaturen können mit Cosign verifiziert werden – siehe SECURITY.md für Anweisungen.

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARXNG_URL",
        "isokoliuk/mcp-searxng:latest"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Um zusätzliche Umgebungsvariablen zu übergeben, fügen Sie -e VAR_NAME zu args und die Variable zu env hinzu. Für die Browser-Solver-Integration übergeben Sie FLARESOLVERR_URL, BYPARR_URL oder beide und stellen Sie sicher, dass die konfigurierten Dienste aus diesem Container erreichbar sind. Der Dual-Modus hat eine feste FlareSolverr-zuerst-Reihenfolge und kein automatisches Reverse-Failover. Siehe URL Reader Controls für das vollständige Verhalten und ein Docker-Compose-Beispiel.

Lokal erstellen:

docker build -t mcp-searxng:latest -f Dockerfile .

Verwenden Sie dieselbe Konfiguration wie oben, ersetzen Sie isokoliuk/mcp-searxng:latest durch mcp-searxng:latest.

docker-compose.yml:

services:
  mcp-searxng:
    image: isokoliuk/mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=${SEARXNG_URL:?Set SEARXNG_URL in the environment}
      # Add optional variables as needed — see CONFIGURATION.md

Die verfolgte Compose-Datei ist absichtlich nur STDIO und veröffentlicht keine Netzwerkports; MCP-Clients starten sie mit einem absoluten Compose-Dateipfad und docker compose run --rm -T, nicht docker compose up. Das -T-Flag verhindert die Zuweisung eines Pseudo-TTY, sodass MCP-JSON-RPC auf roher Standardeingabe und -ausgabe bleibt. Compose schlägt vor dem Start fehl, es sei denn, der MCP-Client liefert SEARXNG_URL.

MCP-Client-Konfiguration:

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/absolute/path/to/docker-compose.yml",
        "run", "--rm", "-T", "mcp-searxng"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Wenn Sie die verfolgte Datei zuvor als HTTP-Dienst auf Port 8080 verwendet haben, legen Sie die HTTP-Einstellungen in eine nicht verfolgte docker-compose.override.yml:

services:
  mcp-searxng:
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - MCP_HTTP_PORT=8080
      - MCP_HTTP_HOST=0.0.0.0

Hier ist 0.0.0.0 die container-seitige Bind-Adresse; der Host-seitige Port bleibt nur auf Loopback beschränkt. Diese Überschreibung hat keine Authentifizierung und ist nur ein temporärer Migrationspfad für einen einzelnen Host. Bevor Sie ko-lokalisierte Container hinzufügen oder den Dienst über die lokale Maschine hinaus verfügbar machen, befolgen Sie die gehärteten Bereitstellungsempfehlungen.

Standardmäßig verwendet der Server STDIO, das von Ihrem MCP-Client gestartet wird. Um stattdessen HTTP zu verwenden, führen Sie mcp-searxng als eigenständigen Prozess mit gesetztem MCP_HTTP_PORT aus. In diesem Modus bedient er das MCP-Protokoll über HTTP und spricht kein STDIO, sodass Ihr Client sich per URL verbindet, anstatt ihn zu starten.

Server starten:

MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng

Oder mit Docker (an alle Schnittstellen binden, damit der Port vom Host aus erreichbar ist):

docker run --rm -p 3000:3000 \
  --add-host=host.docker.internal:host-gateway \
  -e MCP_HTTP_PORT=3000 -e MCP_HTTP_HOST=0.0.0.0 \
  -e SEARXNG_URL=http://host.docker.internal:8080 \
  isokoliuk/mcp-searxng:latest

Die --add-host-Zuordnung ermöglicht es dem Container, eine SearXNG-Instanz auf dem Host über host.docker.internal zu erreichen; sie wird auf Docker Desktop automatisch aufgelöst, benötigt dieses Flag jedoch auf nativem Linux. Weisen Sie SEARXNG_URL auf Ihre tatsächliche Instanz, wenn sie woanders läuft.

Einen HTTP-fähigen MCP-Client über URL mit dem /mcp-Endpunkt verbinden:

{
  "mcpServers": {
    "searxng-http": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Protokollunterstützung: HTTP und STDIO bedienen modernes MCP 2026-07-28 und die beibehaltenen Legacy-Revisionen 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 und 2024-10-07. Modernes HTTP ist zustandsloses POST /mcp; Legacy-HTTP bleibt standardmäßig zustandsbehaftet (POST/GET/DELETE /mcp) oder verwendet den bestehenden Nur-POST-zustandslosen Modus.

Endpunkte: modernes POST /mcp; Legacy POST/GET/DELETE /mcp im zustandsbehafteten Standard oder Legacy POST /mcp nur mit zustandslosem Modus; GET /health.

Für Legacy-HTTP-Clients bleiben zustandsbehaftete Sitzungen der Standard. Setzen Sie MCP_HTTP_STATELESS=true, wenn eine Bereitstellung In-Memory-Legacy-Sitzungen zwischen Anfragen nicht beibehalten kann. Modernes HTTP bleibt unabhängig von dieser Einstellung zustandslos. Jeder zustandslose POST erstellt einen neuen MCP-Server und Transport, ignoriert jede eingehende Sitzungs-ID und gibt innerhalb desselben POST ausgehandeltes JSON oder einen SSE-Stream zurück. Der zustandslose Modus ist Nur-POST: GET /mcp und DELETE /mcp geben HTTP 405 mit Allow: POST zurück, und es werden keine anfrageübergreifenden Abonnements, Fortsetzbarkeit oder Server-zu-Client-Benachrichtigungen beibehalten.

Zustandslose Anfragen sind durch globale und pro-Client-IP geltende In-Flight-Limits sowie eine Anforderungslebensdauer begrenzt. Siehe CONFIGURATION.md für Standardwerte, Überlast- und Timeout-Antworten, Proxy-bewusste Fairness und den vollständigen Kompatibilitätsvertrag.

Ursprungsvalidierung und Upgrade-Hinweis: Jeder vorhandene Origin auf /mcp wird in allen Modi validiert; ein fehlender Origin bleibt für Nicht-Browser-Clients gültig. Im nicht gehärteten Modus entspricht ein nicht gesetztes MCP_HTTP_ALLOWED_ORIGINS standardmäßig den exakten HTTP/HTTPS-Loopback-Ursprüngen http://127.0.0.1, https://127.0.0.1, http://localhost, https://localhost, http://[::1] und https://[::1], sowohl ohne Port als auch mit dem konfigurierten MCP_HTTP_PORT. Ein nicht leeres MCP_HTTP_ALLOWED_ORIGINS ersetzt diese Standardwerte. Einträge werden getrimmt, sind aber ansonsten wörtlich; der Abgleich erfolgt exakt, Groß-/Kleinschreibung beachtend, einschließlich Schema und Port. Fehlerhafte, schemalose, pfadbehaftete Werte, Werte mit abschließendem Schrägstrich oder anders geschriebene Werte stimmen stillschweigend nicht überein und müssen korrigiert werden. Der gehärtete Modus erfordert weiterhin eine explizite Zulassungsliste und fügt Authentifizierung sowie Host-Durchsetzung hinzu. Ein ungültiger vorhandener Origin auf /mcp erhält eine feste, nicht reflektierende 403-Antwort, bevor Parser, Authentifizierung, Ratenbegrenzung oder Transportkonstruktion erfolgen. /health liegt außerhalb der MCP-403-Grenze, verwendet aber die verengte globale CORS-Zulassungsliste. Vor einem Upgrade müssen bestehende nicht gehärtete Browser-Bereitstellungen, die Nicht-Loopback-Ursprünge verwenden, MCP_HTTP_ALLOWED_ORIGINS setzen oder eine feste 403-Antwort erhalten.

Testen Sie es:

curl http://localhost:3000/health

Der Server bindet standardmäßig an 127.0.0.1; setzen Sie MCP_HTTP_HOST=0.0.0.0 für entfernte oder containerisierte Bereitstellungen. Bevor Sie ihn in einem Netzwerk verfügbar machen, aktivieren Sie den gehärteten Modus (MCP_HTTP_HARDEN) und lesen Sie CONFIGURATION.md für MCP_HTTP_TRUST_PROXY, damit Ratenbegrenzung und Protokolle die korrekte Client-IP verwenden.

Konfiguration

SEARXNG_URL ist die einzige erforderliche Variable – setzen Sie sie auf die URL Ihrer SearXNG-Instanz (oder eine durch Semikolons getrennte Liste austauschbarer Replikate). Alles andere ist optional.

Verwenden Sie SEARXNG_DEFAULT_RESPONSE_FORMAT, um text oder json auszuwählen, wenn Suchaufrufe response_format weglassen; explizite Werte pro Aufruf haben weiterhin Vorrang.

Siehe CONFIGURATION.md für die vollständige Referenz der Umgebungsvariablen, einschließlich Authentifizierung, Failover/Fan-out, Caching, Timeouts, Proxys, TLS, HTTP-Transport und Härtung.

Fehlerbehebung

Für die selbst gehostete SearXNG-Konfiguration, direkte Überprüfung und Fehlerbehebung siehe Betrieb von selbst gehostetem SearXNG mit mcp-searxng. Wenn Sie die Instanz nicht kontrollieren, verwenden Sie stattdessen die separate Anleitung für öffentliche SearXNG-Instanzen.

Wenn HTTPS-Anfragen hinter einem TLS-prüfenden Unternehmensproxy mit Zertifikatsfehlern fehlschlagen, siehe TLS / Unternehmens-CA.

403 Forbidden von SearXNG

Ihre SearXNG-Instanz hat wahrscheinlich das JSON-Format deaktiviert. Bearbeiten Sie settings.yml (normalerweise /etc/searxng/settings.yml):

search:
  formats:
    - html
    - json

Starten Sie SearXNG neu (docker restart searxng) und überprüfen Sie dann:

curl 'http://localhost:8080/search?q=test&format=json'

Sie sollten eine JSON-Antwort erhalten. Wenn nicht, bestätigen Sie, dass die Datei korrekt eingebunden ist und die YAML-Einrückung gültig ist.

Siehe auch: SearXNG-Einstellungsdokumentation · Diskussion

JSON nicht aktivierbar? (HTML-Fallback)

Wenn Sie eine öffentliche Instanz verwenden müssen, die Sie nicht kontrollieren, und diese format=json ablehnt (die 403 oben), setzen Sie stattdessen das Opt-in-Flag, anstatt den Server zu bearbeiten:

Bevor Sie es aktivieren, prüfen Sie die Richtlinie des öffentlichen Betreibers und die Nutzungsanleitung für öffentliche Instanzen.

{
  "SEARXNG_HTML_FALLBACK": "true"
}

Eine Suche, die eine 403/404- oder eine Nicht-JSON-Antwort erhält, wird dann automatisch ohne format=json erneut versucht und aus der regulären HTML-Ergebnisseite geparst.

• Bei Erfolg: Sie erhalten normale Ergebnisse (Titel, URL, Ausschnitt). Sie sind im JSON-Modus als sourceFormat: "html" gekennzeichnet, und der Textmodus fügt die Zeile "Hinweis: Ergebnisse aus dem SearXNG-HTML-Fallback geparst; Metadaten sind begrenzt." hinzu. Relevanzwerte und Engine-Namen sind aus HTML nicht verfügbar.

• Bei Fehlschlag: Das Parsen ist eine Best-Effort-Leistung und variiert je nach Theme/Version der Instanz, sodass einige Ergebnisse fehlen oder spärlich sein können. Wenn die HTML-Seite selbst ebenfalls fehlschlägt – weiterhin blockiert, ratenbegrenzt (429), Auth (401) oder 5xx – wird der Fehler des Fallback-Versuchs angezeigt, sodass die Suche niemals stillschweigend leere Ergebnisse zurückgibt. Der Fallback wird nur bei 403/404/Nicht-JSON ausgelöst, niemals bei Auth- oder Netzwerkfehlern.

Das Aktivieren von JSON auf einer Instanz, die Sie kontrollieren (oben), bleibt die empfohlene Einrichtung – der Fallback ist eine Kompatibilitätshilfe, kein Ersatz.

Mitwirken

Siehe CONTRIBUTING.md

Lizenz

MIT – siehe LICENSE für Details.