SearXNG MCP Bridge Server

Release

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

Schnellstart (Verwendung über npm)

Einrichten einer SearXNG-Instanz:

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

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

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

SearXNG MCP Bridge