webscout-mcp

Websuch- und Abruf-Tools für KI-Agenten als MCP-Server. Durchsuchen, abrufen, crawlen und extrahieren Sie strukturierte Daten aus dem Web – keine API-Schlüssel, keine Abrechnung pro Anfrage, alles bleibt auf Ihrem Rechner.

Installation

pip install webscout-mcp

Erfordert Python 3.10+.

Related MCP server: Crawl4AI RAG MCP Server

Schnellstart

Fügen Sie Folgendes zu Ihrer MCP-Client-Konfiguration hinzu (Claude Code, Cursor, Codex usw.):

{
  "mcpServers": {
    "webscout": {
      "command": "webscout-mcp",
      "args": []
    }
  }
}

Das war's. Ihr Agent erhält sechs Werkzeuge:

• web_search – Suche über Bing mit automatischem DuckDuckGo-HTML-Fallback, kein Schlüssel erforderlich

• web_fetch – eine Seite abrufen und den Hauptartikel extrahieren (Markdown/Text/HTML)

• web_crawl – gleichzeitiger BFS-Crawl mit Tiefen-/Seitenlimits, respektiert robots.txt

• web_extract – strukturierte Daten mit CSS-Selektoren, Attributen und Regex extrahieren

• cache_stats – den lokalen Cache inspizieren

• cache_clear – den Cache leeren

CLI-Nutzung

Zusätzlich zum Betrieb als MCP-Server können Sie webscout-mcp direkt über die Befehlszeile verwenden:

# Search the web (outputs JSON)
webscout-mcp search "python async libraries" --max-results 5

# Fetch a page (raw content)
webscout-mcp fetch https://example.com --extract --format markdown --raw

# Crawl a site
webscout-mcp crawl https://example.com --depth 2 --pages 10

# Start MCP server (default if no command given)
webscout-mcp serve --transport stdio

Verwendungsbeispiele

Suche

web_search(query="best python async libraries", max_results=5)

Gibt strukturierte Ergebnisse mit Titel, URL, Ausschnitt und dem Backend zurück, das die Anfrage bedient hat (bing oder duckduckgo). Wenn Bing fehlschlägt oder sein Markup ändert, fällt die Engine automatisch auf die HTML-Version von DuckDuckGo zurück – keine Konfiguration erforderlich.

Eine Seite abrufen

web_fetch(url="https://example.com", extract=true, output_format="markdown")

extract=true führt trafilatura aus (mit readability-lxml als Fallback), um Navigation, Werbung und Seitenleisten zu entfernen – Sie erhalten sauberen Artikelinhalt, nicht rohes HTML.

Strukturierte Daten extrahieren

web_extract(
  url="https://example.com/products",
  rules='[
    {"name": "titles", "selector": ".product h2", "multiple": true},
    {"name": "prices", "selector": ".price", "regex": "\\$([\\d.]+)", "multiple": true},
    {"name": "links", "selector": "a.product", "attribute": "href", "multiple": true}
  ]'
)

Jede Regel unterstützt selector, attribute, multiple, regex und default.

Eine Website crawlen

web_crawl(seed_url="https://example.com", max_depth=2, max_pages=10, concurrency=5)

Seiten auf jeder Tiefenebene werden gleichzeitig abgerufen (gesteuert durch concurrency, Standard 5). Der Crawler respektiert standardmäßig robots.txt – nicht erlaubte URLs werden übersprungen und in skipped_robots gezählt. Die Einschränkung auf dieselbe Domain ist standardmäßig aktiviert.

Verwendung als Python-Bibliothek

import asyncio
from webscout_mcp import Config, Fetcher, SearchEngine

async def main():
    config = Config.from_env()
    config.ensure_dirs()

    fetcher = Fetcher(config)
    result = await fetcher.fetch("https://example.com", extract=True)
    print(result.title)
    print(result.content[:500])
    await fetcher.close()

    search = SearchEngine(config)
    results = await search.search("python async", max_results=5)
    for r in results:
        print(f"{r.position}. {r.title} - {r.url} ({r.backend})")
    await search.close()

asyncio.run(main())

So funktioniert es

• Suche versucht zuerst Bing, dann DuckDuckGo HTML – beide über direktes HTTP-Scraping, kein API-Schlüssel. Ergebnisse werden nach Abfrage zwischengespeichert.

• Abrufen verwendet httpx mit exponentiellen Backoff-Wiederholungen (alle httpx-Fehler + HTTP 5xx), Token-Bucket-Ratenbegrenzung pro Domain und einem Inhaltslimit von 5 MB.

• Inhaltsextraktion verwendet trafilatura primär, readability-lxml als automatischen Fallback – dieselben Bibliotheken, die vielen Read-it-Later-Diensten zugrunde liegen.

• Zwischenspeicherung erfolgt über SQLite mit TTL und Größenlimit; alte Einträge werden automatisch entfernt. Wiederholte Abrufe und Suchen kosten nichts.

• Crawling ist gleichzeitiges BFS mit konfigurierbarer Tiefe, Seitenanzahl, Parallelität, Einschränkung auf dieselbe Domain und robots.txt-Konformität. Verwendet rohes HTML aus dem ersten Abruf, um ein doppeltes Abrufen jeder Seite zu vermeiden.

• Proxy-Unterstützung leitet alle HTTP/HTTPS-Anfragen über einen Proxy, per Konfiguration oder Umgebungsvariablen.

• Protokollierung ist strukturiert und konfigurierbar über WEBSCOUT_LOG_LEVEL (DEBUG/INFO/WARNING/ERROR) und WEBSCOUT_LOG_JSON=1 für JSON-Ausgabe.

Alles läuft lokal. Keine Daten verlassen Ihren Rechner.

Konfiguration

Alle Einstellungen haben sinnvolle Standardwerte. Überschreiben Sie sie über Umgebungsvariablen (WEBSCOUT_-Präfix), eine TOML-Konfigurationsdatei oder CLI-Flags.

Konfigurationsdatei

Erstellen Sie ~/.config/webscout/config.toml (oder $XDG_CONFIG_HOME/webscout/config.toml):

[cache]
ttl = 7200
max_size_mb = 512

[fetch]
timeout = 15.0
max_retries = 3

[proxy]
http = "http://proxy:8080"
https = "http://proxy:8080"

[search]
max_results = 10
backends = ["bing", "duckduckgo"]

[crawler]
max_depth = 2
max_pages = 20
concurrency = 5
respect_robots = true

[logging]
level = "WARNING"
json = false

Umgebungsvariablen überschreiben Werte aus der Konfigurationsdatei.

Umgebungsvariablen

CLI-Flags überschreiben Umgebungsvariablen:

webscout-mcp --cache-ttl 3600 --cache-dir /tmp/webscout serve

Transporte

# stdio (default - works with Claude Code, Cursor, etc.)
webscout-mcp

# SSE (for remote or browser-based clients)
webscout-mcp serve --transport sse --host 0.0.0.0 --port 8000

Änderungsprotokoll

0.3.0

• TOML-Konfigurationsdatei-Unterstützung: Konfiguration über ~/.config/webscout/config.toml zusätzlich zu Umgebungsvariablen

• HTTP/HTTPS-Proxy-Unterstützung: alle Anfragen über einen Proxy leiten

• Doppelte Inhaltsextraktion: trafilatura primär, readability-lxml automatischer Fallback

• Deduplizierung von Suchergebnissen: doppelte URLs entfernt, Positionen neu nummeriert

• Regionenbewusste Suche: region-Parameter wird jetzt tatsächlich an Bing und DuckDuckGo übergeben

• Crawler-Leistung: doppeltes Abrufen pro Seite eliminiert – ~2x schnellere Crawls

• Bessere Wiederholungslogik: Wiederholungen bei allen httpx-Fehlern und HTTP 5xx

• Korrigierte Content-Type-Erkennung: korrekte HTML/XML-Erkennung

0.2.0

• Multi-Backend-Suche: Bing + DuckDuckGo HTML mit automatischem Failover

• Gleichzeitiger Crawler mit konfigurierbarer Parallelität

• robots.txt-Konformität (konfigurierbar, standardmäßig aktiviert)

• CLI-Unterbefehle: search, fetch, crawl, serve

• Strukturierte Protokollierung mit Konsolen- und JSON-Formatierern

• Benutzerdefinierte Ausnahmehierarchie für bessere Fehlerbehandlung

• Neue Konfiguration: WEBSCOUT_SEARCH_BACKENDS, WEBSCOUT_CRAWLER_CONCURRENCY, WEBSCOUT_RESPECT_ROBOTS

0.1.0

• Erste Veröffentlichung: web_search, web_fetch, web_crawl, web_extract, cache_stats, cache_clear

• SQLite-Cache mit TTL und größenbasierter Entfernung

• Token-Bucket-Ratenbegrenzung pro Domain

• Exponentielle Backoff-Wiederholungen

• trafilatura-Inhaltsextraktion

Entwicklung

git clone https://github.com/wxs-lang/webscout-mcp.git
cd webscout-mcp
pip install -e ".[dev]"
pytest

Lizenz

MIT