SearXNG MCP Bridge Server

Dies ist ein Model Context Protocol (MCP) Server, der als Brücke zu einer SearXNG-Instanz fungiert. Er ermöglicht kompatiblen Clients, Suchen über MCP-Tools mit einer konfigurierten SearXNG-Instanz durchzuführen.

Anforderungen

• Node.js 25.x

• npm 11.x oder neuer

Related MCP server: searxng-mcp

Schnellstart (Verwendung über npm)

1. Einrichten einer SearXNG-Instanz:

   # Using Docker
   docker run -d -p 8888:8080 --name searxng searxng/searxng

2. Installieren und Ausführen der MCP-Brücke

   Standard (STDIO, unverändert):

   # Run directly with npx (default - stdio transport)
   npx -y @nitish-raj/searxng-mcp-bridge

   Optional: Als HTTP-Server ausführen (neu, optional)

    # Using env variables (recommended)
     TRANSPORT=http PORT=3002 HOST=127.0.0.1 SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge
   
   
   
   # Or run the built bundle
   TRANSPORT=http node build/index.js

3. Konfiguration in Ihrer MCP-Einstellungsdatei (stdio / Legacy-Clients) Fügen Sie dies Ihrer MCP-Einstellungsdatei hinzu (z. B. ~/.vscode-server/.../mcp_settings.json):

   {
     "mcpServers": {
       "searxng-bridge": {
         "command": "npx",
         "args": [
          "-y",
          "@nitish-raj/searxng-mcp-bridge"
          ],
          "env": {
            "SEARXNG_INSTANCE_URL": "http://localhost:8080"
          },
         "disabled": false
       }
     }
   }

HTTP-Konfiguration: Setzen Sie TRANSPORT=http, um die Brücke über HTTP anstelle von stdio auszuführen. Der Transportmodus kann über Umgebungsvariablen konfiguriert werden.

Funktionen

• Such-Tool: Führen Sie Websuchen mit SearXNG mit konfigurierbaren Parametern durch

• Gesundheitsprüfung: Überwachen Sie die Konnektivität und Leistung der SearXNG-Instanz

• Dualer Transport: Unterstützt sowohl STDIO (Standard) als auch HTTP-Transporte

• Sitzungsverwaltung: Der HTTP-Transport beinhaltet sitzungsbasierte Verbindungen

• CORS-Unterstützung: Korrekte Cross-Origin-Header für die Integration von Web-Clients

• Ratenbegrenzung: Integrierter Schutz gegen übermäßige Anfragen (HTTP-Modus)

Konfiguration

• SEARXNG_INSTANCE_URL — ERFORDERLICH. Die vollständige URL der SearXNG-Instanz (z. B. http://localhost:8080).

• TRANSPORT — Transportprotokoll: stdio (Standard) oder http

• PORT — HTTP-Server-Port. Standard: 3000 (verwenden Sie 3002 für die Entwicklung)

• HOST — Server-Bind-Adresse. Standard: 127.0.0.1 (verwenden Sie 0.0.0.0 für Container)

• CORS_ORIGIN — Durch Kommas getrennte Liste erlaubter Ursprünge für CORS. Standard: localhost:3002 (Entwicklung) oder * (Produktion)

• MCP_HTTP_BEARER — Optionales Bearer-Token für die HTTP-Authentifizierung HTTP-Transport-Funktionen:

• Sitzungsverwaltung mit mcp-session-id-Headern

• Sicheres CORS mit Whitelist-Validierung der Ursprünge

• Ratenbegrenzung (100 Anfragen/Minute pro IP)

• Optionale Bearer-Authentifizierung über MCP_HTTP_BEARER

• Schutz vor DNS-Rebinding

Sicherheitshinweise:

• CORS verwendet in der Entwicklung eine sichere Whitelist (nur localhost:3002)

• Die Produktion spiegelt spezifische Ursprünge für authentifizierte Anfragen wider (CORS-konform)

• Setzen Sie CORS_ORIGIN, um erlaubte Ursprünge für Ihren Anwendungsfall anzupassen

• Setzen Sie TRANSPORT=stdio, um zum stdio-Modus zurückzukehren

HTTP-Transport

Der HTTP-Transport implementiert die MCP Streamable HTTP-Spezifikation (2025-03-26) mit den folgenden Endpunkten:

MCP-Endpunkte:

• POST /mcp - Senden von MCP-Anfragen

• GET /mcp - Server-Sent Events für Benachrichtigungen

• DELETE /mcp - Sitzungen beenden

• OPTIONS /mcp - CORS-Preflight-Anfragen

System-Endpunkte:

• GET /healthz - Gesundheitsprüfung und Status

Test-HTTP-Endpunkt:

curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Dies gibt eine JSON-RPC-Antwort mit der Liste der verfügbaren Tools (search und health_check) zurück.

Docker

Das Dockerfile stellt Port 8081 für den HTTP-Transport bereit. Um den Container auszuführen und HTTP-Zugriff zu ermöglichen:

# Build (example)
docker build -t searxng-mcp-bridge .

# Run mapping port 8081
 docker run -d -p 8081:8081 --env SEARXNG_INSTANCE_URL=http://localhost:8080 --name searxng-mcp-bridge searxng-mcp-bridge

# To run HTTP transport inside container:
 docker run -d -p 8081:8081 -e TRANSPORT=http -e PORT=8081 -e SEARXNG_INSTANCE_URL=http://localhost:8080 searxng-mcp-bridge

Hinweis: Setzen Sie bei Containerisierung HOST=0.0.0.0 oder verlassen Sie sich auf das standardmäßig bereitgestellte Port-Mapping.

Verwendung

STDIO-Clients: Verwenden Sie das Tool unverändert - es sind keine Konfigurationsänderungen erforderlich.

HTTP-Clients: Verbinden Sie sich mit http://localhost:3002/mcp (Entwicklungs-Port) und senden Sie MCP JSON-RPC-Anfragen.

Entwicklung

• npm install: Abhängigkeiten installieren.

• npm run build: TypeScript in JavaScript kompilieren.

• npm run watch: Auf Änderungen achten und automatisch neu kompilieren.

• npm run inspector: Den MCP-Inspektor ausführen, um den Server zu testen.

• npm run start:http: Server im HTTP-Streaming-Modus auf localhost:3002 starten.

Migration & Kompatibilität

Abwärtskompatibilität:

• STDIO bleibt der Standardtransport - bestehende Benutzer benötigen keine Änderungen

• Alle Tool-Namen, Parameter und Antworten bleiben unverändert

• Die Konfiguration erfolgt optional über Umgebungsvariablen

Migration zu HTTP:

• Setzen Sie TRANSPORT=http, um den HTTP-Transport zu aktivieren

• Konfigurieren Sie PORT und HOST nach Bedarf

• Aktualisieren Sie den Client, um den HTTP-Endpunkt anstelle von stdio zu verwenden

Rollback:

• Setzen Sie TRANSPORT=stdio oder lassen Sie die Variable weg, um zu stdio zurückzukehren