Local Web Search MCP Server

Offline-first MCP-Server für Websuche und Inhaltsabruf. Er benötigt keine externen API-Schlüssel und verwendet lokale Modelle für Intent-Klassifikation, optionale sprachübergreifende Suche, semantisches Re-Ranking und extraktive Deep-Search-Antworten.

Funktionen

• Browser-Kontext-Pooling mit einer persistenten Playwright-Browser-Instanz.

• Websuche über konfigurierbare Anbieter mit Health-Tracking und geordnetem Fallback.

• Optionale föderierte Suche über alle konfigurierten Anbieter mit URL-Normalisierung, anbieterübergreifender Deduplizierung und Reciprocal Rank Fusion (RRF).

• Optionale intentsensitive Suchweiterleitung mit konservativen Heuristiken, lokalem Klassifikator-Fallback und versionierten Anbieterprofilen.

• Domänengefilterte Websuche für gezielte Site-Abfragen.

• HTTP-first Seitenabruf mit GitHub-Raw- und RSS-Schnellpfaden sowie Playwright-Fallback für gerenderte Seiten.

• SSRF-Schutz für fetch_content durch Blockieren von localhost- und privaten Netzwerkzielen.

• Token-Bucket-Rate-Limiting für Such- und Abruf-Tools.

• Semantischer Cache mit SQLite und sqlite-vec.

• Optionale sprachübergreifende Query-Expansion mit lokalen Transformers.js-Modellen.

• Saubere Markdown-Extraktion durch Readability, JSDOM und Turndown.

Related MCP server: searxng-mcp

Anforderungen

• Node.js 20.9.0 oder neuer.

• npm.

• Netzwerkzugriff während der Installation für npm-Pakete, Playwright Chromium und den ersten Download von Modellen.

Installation

npm install
npm run build

Das postinstall-Skript lädt Playwright Chromium herunter. Bei der ersten Verwendung modellgestützter Funktionen lädt Transformers.js die erforderlichen Modelldateien in den lokalen Hugging-Face-Cache. Die erste Anfrage, die ein Modell lädt, kann langsam sein; spätere Anfragen nutzen den lokalen Cache erneut. Behalte ENABLE_CROSSLINGUAL=false für den leichtesten ersten Lauf. Offensichtliche strategy=auto-Intents werden durch Heuristiken aufgelöst, ohne den Intent-Klassifikator zu laden; mehrdeutige Auto-Abfragen können einen Erstlauf-Download des Klassifikators auslösen.

MCP-Client-Konfiguration

Füge den gebauten Server zu deiner MCP-Client-Konfiguration hinzu:

{
  "mcpServers": {
    "websearch": {
      "command": "node",
      "args": ["path/to/local-websearch-mcp/build/index.js"],
      "env": {
        "RATE_LIMIT_SEARCH_PER_MIN": "10",
        "RATE_LIMIT_FETCH_PER_MIN": "20",
        "SEARCH_PROVIDERS": "duckduckgo,bing",
        "ENABLE_CROSSLINGUAL": "false",
        "CACHE_DB_PATH": "websearch_cache.db"
      }
    }
  }
}

Wenn das Paket global oder über einen Paket-Runner installiert ist, verwende den Binär-Einstiegspunkt:

{
  "mcpServers": {
    "websearch": {
      "command": "local-websearch-mcp",
      "args": [],
      "env": {
        "SEARCH_PROVIDERS": "duckduckgo,bing",
        "ENABLE_CROSSLINGUAL": "false"
      }
    }
  }
}

Für paket-runner-basierte Clients kann der Befehl npx sein, mit args gesetzt auf ["-y", "local-websearch-mcp"], sobald das Paket aus der konfigurierten npm-Registry verfügbar ist.

Tools

Suchstrategien

auto ist bewusst opt-in; das Weglassen von strategy verwendet weiterhin fallback für Abwärtskompatibilität. Der semantische Query-Cache wird für aggregate und auto umgangen, da Query-Cache-Schlüssel noch nicht nach Ausführungsstrategie/Anbieterplan namespaced sind. Deep-Search-Seiteninhalte verwenden weiterhin den normalen Inhalts-Cache.

SEARCH_PROVIDERS ist sowohl eine Allowlist als auch die konfigurierte Anbietermenge. Auto-Routing aktiviert niemals einen Anbieter, der in SEARCH_PROVIDERS fehlt; das Routing-Profil ändert nur die Reihenfolge und wie viele konfigurierte Anbieter als primäre Kandidaten ausgewählt werden.

Für Aggregate-Auto-Profile werden sekundäre konfigurierte Anbieter nur kontaktiert, wenn alle ausgewählten primären Anbieter kein brauchbares Ergebnis liefern. Ein teilweiser primärer Erfolg wird akzeptiert, anstatt die Anfrage nur zur Erhöhung der Ergebnisanzahl zu erweitern. Dies begrenzt die Scraping-Last und reduziert unnötige Blockierung/CAPTCHA-Exposition.

Aktuelles Routing-Profil: v1.

Diese Anbieterpräferenzen sind anfängliche Hypothesen, keine dauerhaften Qualitätsaussagen. Sie sind versioniert, sodass spätere Releases sie anhand deterministischer und Live-Evaluationsnachweise anpassen können, ohne Routing-Bedingungen im Server zu verstreuen.

Beispiel für intentsensitive Suchargumente:

{
  "query": "PostgreSQL connection pooling best practices",
  "strategy": "auto",
  "max_results": 5
}

Verwende domain für gezielte Suchen wie react.dev oder github.com. Die Intent-Erkennung erhält immer die ursprüngliche Abfrage; site:<domain> wird erst danach für die Anbieterausführung angehängt.

{
  "query": "server components reference",
  "domain": "react.dev",
  "strategy": "auto",
  "max_results": 5
}

Verwende deep=true nur, wenn der Client benötigt, dass der Server Top-Seiten abruft und eine wahrscheinliche Antwort aus dem Seitentext extrahiert. Die MCP-Client-LLM bleibt für die endgültige Argumentation und Zusammenfassung verantwortlich.

Such-Snippets mit alten erkannten Daten enthalten eine kurze Frischewarnung, damit Clients veraltete Quellen vorsichtig behandeln können.

Beispiel für föderierte Suchargumente:

{
  "query": "postgres connection pooling strategies",
  "strategy": "aggregate",
  "max_results": 5
}

fetch_content verwendet schnelle quellenspezifische Pfade, bevor ein Browser geöffnet wird:

• GitHub-Repository-, Blob-, Tree- und Raw-URLs werden, wenn möglich, von raw.githubusercontent.com gelesen.

• RSS- oder Atom-Feed-URLs sowie häufige Blog-/News-Feed-Pfade werden in eine Markdown-Liste aktueller Einträge umgewandelt.

• Normale HTML-Seiten verwenden weiterhin HTTP-first Readability-Parsing mit Playwright-Fallback.

Konfiguration

Docker

npm run docker:build
npm run docker:up

Docker Compose speichert den SQLite-Cache in einem benannten Volume, das unter /app/data gemountet ist, und speichert Hugging-Face-Modelle in einem separaten benannten Volume. Der Container setzt CACHE_DB_PATH=/app/data/websearch_cache.db.

Entwicklung

npm run build
npm run typecheck
npm test
npm run smoke:mcp
npm audit --audit-level=moderate
npm pack --dry-run --json

npm run smoke:mcp startet den kompilierten Server über stdio, verifiziert die drei web_search-Strategiewerte (fallback, aggregate, auto), prüft Routing-Diagnosen von server_status und bestätigt, dass fetch_content localhost blockiert. Es führt keine Live-Anbietersuche durch, wodurch CI unabhängig von Suchmaschinen-HTML/Netzwerkverfügbarkeit bleibt.

Deterministische TR/EN-Routing-Fixtures befinden sich in evals/search-routing/queries.jsonl und werden von der normalen Vitest-Suite ausgeführt. Sie validieren Intent-Abdeckung, konservatives Heuristikverhalten, Mehrdeutigkeits-Defer-Fälle und die Durchsetzung der Anbieter-Allowlist, ohne den echten Klassifikator zu laden oder Anbieter zu kontaktieren.

Fehlerbehebung

• Wenn der Start nach der Installation fehlschlägt, führen Sie npx playwright install chromium aus.

• Wenn die erste modellgestützte Anfrage langsam ist, lassen Sie den Download des Transformers.js-Modells abschließen und versuchen Sie es erneut.

• Wenn die Suche keine Ergebnisse liefert, ändern Sie die Reihenfolge/den Satz von SEARCH_PROVIDERS oder versuchen Sie eine direkte fetch_content-URL.

• Wenn der Aggregatmodus zu langsam ist oder eine Blockierung durch den Anbieter auslöst, verwenden Sie die Standardstrategie fallback.

• Wenn auto für Ihren Anwendungsfall einen zu breiten Suchplan wählt, verwenden Sie explizit fallback oder aggregate; explizite Strategien umgehen den Auto-Planer.

• Wenn Docker Chromium nicht finden kann, erstellen Sie das Image mit npm run docker:build neu.

• Wenn Cache-Dateien im Projektstammverzeichnis erscheinen, setzen Sie CACHE_DB_PATH auf ein dediziertes Datenverzeichnis.

npm-Paketierung

Das npm-Paket enthält nur build/, README.md, LICENSE und SECURITY.md. npm pack führt npm run build über prepack aus, sodass das Paket kompiliertes JavaScript anstelle von lokalen Planungsdateien, Tests, Caches oder reinen Quellartefakten enthält.

Sicherheit

Siehe SECURITY.md für Anweisungen zur Meldung und aktuelle Hinweise zur Abhängigkeitsprüfung.

Lizenz

ISC