Web Scrapper Service (MCP Stdin/Stdout & HTTP)

Ein Python-basierter MCP-Server für robustes, Headless-Web-Scraping – extrahiert den Haupttextinhalt von Webseiten und gibt Markdown, Text oder HTML für eine nahtlose KI- und Automatisierungsintegration aus.

Hauptfunktionen

• Headless-Browser-Scraping (Playwright, BeautifulSoup, Markdownify)

• Ausgabe als Markdown, Text oder HTML

• Entwickelt für MCP (Model Context Protocol) stdio/JSON-RPC-Integration

• Dualer Transport: stdio (Standard) und Streamable HTTP für den Shared-Service-Modus

• Persistenter Browser-Pool: Chromium bleibt über Anfragen hinweg aktiv für schnelles Scraping

• Intelligentes DOM-Warten: Inhaltsstabilisierung basierend auf MutationObserver anstelle von festen Wartezeiten

• Dockerisiert, mit vorgefertigten Images

• Konfigurierbar über Umgebungsvariablen

• Robuste Fehlerbehandlung (Timeouts, HTTP-Fehler, Cloudflare usw.)

• Domänenspezifisches Rate-Limiting

• Einfache Integration mit KI-Tools und IDEs (Cursor, Claude Desktop, Continue, JetBrains, Zed usw.)

• Ein-Klick-Installation für Cursor, interaktiver Installer für Claude

Related MCP server: Fetcher MCP

Schnellstart

Ausführung mit Docker (stdio-Modus — ein Container pro Client)

docker run -i --rm ghcr.io/justazul/web-scrapper-stdio

Ausführung als Shared HTTP Service (ein Container, mehrere Clients)

docker run -d --name web-scraper \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HTTP_PORT=8080 \
  -e BROWSER_POOL_SIZE=3 \
  -p 8080:8080 \
  --shm-size=3gb \
  ghcr.io/justazul/web-scrapper-stdio

Oder mit Docker Compose:

docker compose --profile service up -d

Ein-Klick-Installation (Cursor IDE)

Transportmodi

stdio (Standard)

Jeder MCP-Client startet seinen eigenen Container via docker run -i. Einfach, keine Konfiguration erforderlich, funktioniert mit jedem MCP-Client.

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/justazul/web-scrapper-stdio"]
    }
  }
}

Streamable HTTP (Shared Service)

Starten Sie einen persistenten Container, der mehrere MCP-Clients über HTTP bedient. Spart Ressourcen beim Ausführen mehrerer KI-Tool-Instanzen (z. B. mehrere Claude Code-Sitzungen).

Starten des Dienstes:

docker run -d --name web-scraper \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HTTP_PORT=8080 \
  -p 8080:8080 \
  --shm-size=3gb \
  ghcr.io/justazul/web-scrapper-stdio

Verbindung von Ihrem MCP-Client:

{
  "mcpServers": {
    "web-scrapper": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Integration mit KI-Tools & IDEs

Dieser Dienst unterstützt die Integration mit einer Vielzahl von KI-Tools und IDEs, die das Model Context Protocol (MCP) implementieren. Nachfolgend finden Sie gebrauchsfertige Konfigurationsbeispiele für die gängigsten Umgebungen. Ersetzen Sie das Image/Tag bei Bedarf für benutzerdefinierte Builds.

Cursor IDE

Fügen Sie dies zu Ihrer .cursor/mcp.json (auf Projektebene) oder ~/.cursor/mcp.json (global) hinzu:

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

Claude Desktop

Fügen Sie dies zu Ihrer Claude Desktop MCP-Konfiguration hinzu (normalerweise claude_desktop_config.json):

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

Claude Code

Fügen Sie dies zu Ihrer .mcp.json oder globalen ~/.claude.json hinzu:

stdio-Modus (ein Container pro Sitzung):

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/justazul/web-scrapper-stdio"]
    }
  }
}

HTTP-Modus (Shared Service — starten Sie zuerst den Dienst):

{
  "mcpServers": {
    "web-scrapper": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Continue (VSCode/JetBrains Plugin)

Fügen Sie dies zu Ihrer continue.config.json oder über die MCP-Einstellungen des Continue-Plugins hinzu:

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

IntelliJ IDEA (JetBrains AI Assistant)

Gehen Sie zu Settings > Tools > AI Assistant > Model Context Protocol (MCP) und fügen Sie einen neuen Server hinzu. Verwenden Sie:

{
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "ghcr.io/justazul/web-scrapper-stdio"
  ]
}

Zed Editor

Fügen Sie dies zu Ihrer Zed MCP-Konfiguration hinzu (siehe Zed-Dokumentation für den genauen Pfad):

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

Verwendung

MCP-Server (Tool/Prompt)

Dieser Web-Scrapper wird als MCP-Tool (Model Context Protocol) verwendet, wodurch er direkt von KI-Modellen oder anderen Automatisierungen genutzt werden kann.

Tool: scrape_web

Parameter:

• url (String, erforderlich): Die zu scrapende URL

• max_length (Integer, optional): Maximale Länge des zurückgegebenen Inhalts (Standard: unbegrenzt)

• timeout_seconds (Integer, optional): Timeout in Sekunden für das Laden der Seite (Standard: 30)

• user_agent (String, optional): Benutzerdefinierter User-Agent-String, der direkt an den Browser übergeben wird (Standard ist ein zufälliger Agent)

• wait_for_network_idle (Boolean, optional): Warten, bis die Netzwerkaktivität abgeklungen ist, bevor gescrapt wird (Standard: true)

• custom_elements_to_remove (Liste von Strings, optional): Zusätzliche HTML-Elemente (CSS-Selektoren), die vor der Extraktion entfernt werden sollen

• grace_period_seconds (Float, optional): Zeit, die nach der Navigation auf das JS-Rendering gewartet werden soll. Verwendet MutationObserver für eine intelligente Erkennung. Auf 0 setzen, um dies komplett zu überspringen. (Standard: 0.5)

• output_format (String, optional): markdown, text oder html (Standard: markdown)

• click_selector (String, optional): Falls angegeben, wird das Element, das diesem Selektor entspricht, nach der Navigation und vor der Extraktion angeklickt

Rückgabewerte:

• Markdown-formatierter Inhalt, der von der Webseite extrahiert wurde, als String

• Fehler werden als Strings gemeldet, die mit [ERROR] ... beginnen

Beispiel: Verwendung von click_selector und custom_elements_to_remove

{
  "url": "http://uitestingplayground.com/clientdelay",
  "click_selector": "#ajaxButton",
  "grace_period_seconds": 10,
  "custom_elements_to_remove": [".ads-banner", "#popup"],
  "output_format": "markdown"
}

Prompt: scrape

Parameter:

• url (String, erforderlich): Die zu scrapende URL

• output_format (String, optional): markdown, text oder html (Standard: markdown)

Rückgabewerte:

• Inhalt, der von der Webseite im gewählten Format extrahiert wurde

Hinweis:

• Markdown wird standardmäßig zurückgegeben, aber Text oder HTML können über output_format angefordert werden.

• Der Scrapper prüft nicht die robots.txt und versucht, jede bereitgestellte URL abzurufen.

• Es ist kein REST-API- oder CLI-Tool enthalten; dies ist ein reines MCP stdio/JSON-RPC-Tool.

• Der Scrapper extrahiert immer den vollständigen <body>-Inhalt von Webseiten und wendet nur eine grundlegende Rauschunterdrückung an (Entfernen von script, style, nav, footer, aside, header und ähnlichen Nicht-Inhalts-Tags). Der Scrapper erkennt und behandelt Cloudflare-Challenge-Bildschirme und gibt einen spezifischen Fehler-String zurück.

Konfiguration

Sie können die meisten Konfigurationsoptionen über Umgebungsvariablen überschreiben:

Kerneinstellungen

• DEFAULT_TIMEOUT_SECONDS: Timeout für das Laden von Seiten und Navigation (Standard: 30)

• DEFAULT_MIN_CONTENT_LENGTH: Minimale Inhaltslänge für extrahierten Text (Standard: 100)

• DEFAULT_MIN_CONTENT_LENGTH_SEARCH_APP: Minimale Inhaltslänge für search.app-Domänen (Standard: 30)

• DEFAULT_MIN_SECONDS_BETWEEN_REQUESTS: Minimale Verzögerung zwischen Anfragen an dieselbe Domäne (Standard: 2)

• DEFAULT_GRACE_PERIOD_SECONDS: Standard-Wartezeit für JS-Rendering (Standard: 0.5)

• DEBUG_LOGS_ENABLED: Auf true setzen, um Debug-Logs zu aktivieren (Standard: false)

Browser-Pool

• BROWSER_POOL_ENABLED: Aktiviert den persistenten Browser-Pool (Standard: true). Auf false setzen für das Starten des Browsers pro Anfrage (ursprüngliches Verhalten).

• BROWSER_POOL_SIZE: Anzahl der Chromium-Instanzen, die aktiv gehalten werden sollen (Standard: 2). Jede Instanz verbraucht ca. 100-200 MB RAM.

Transport

• MCP_TRANSPORT: Transportmodus — stdio oder streamable-http (Standard: stdio)

• MCP_HTTP_PORT: HTTP-Server-Port bei Verwendung des streamable-http-Transports (Standard: 8080)

• MCP_HTTP_HOST: Bind-Adresse des HTTP-Servers (Standard: 0.0.0.0)

Cloudflare-Umgehung

• CAPTCHA_API_KEY: API-Schlüssel für den Captcha-Lösungsdienst. Wenn gesetzt, werden Cloudflare Turnstile-Challenges automatisch gelöst. Wenn leer (Standard), geben CF-geschützte Seiten einen Fehler zurück.

• CAPTCHA_PROVIDER: Anbieter für die Captcha-Lösung — 2captcha, capsolver oder capmonster (Standard: 2captcha)

• CAPTCHA_BASE_URL: Benutzerdefinierter API-Endpunkt für den Löser (Standard: verwendet die offizielle URL des Anbieters)

• CAPTCHA_TIMEOUT: Timeout in Sekunden für die Captcha-Lösung (Standard: 120)

Testeinstellungen

• DEFAULT_TEST_REQUEST_TIMEOUT: Timeout für Testanfragen (Standard: 10)

• DEFAULT_TEST_NO_DELAY_THRESHOLD: Schwellenwert zum Überspringen künstlicher Verzögerungen in Tests (Standard: 0.5)

Fehlerbehandlung & Einschränkungen

• Der Scrapper erkennt und meldet Fehler bei Navigationsfehlern, Timeouts, HTTP-Fehlern (einschließlich 404) und Cloudflare-Anti-Bot-Challenges.

• Rate-Limiting wird pro Domäne durchgesetzt (Standard: 2 Sekunden zwischen Anfragen).

• Cloudflare-Umgehung: Verwendet Patchright (Anti-Erkennung auf CDP-Ebene) für passive Umgehung. Die meisten CF-geschützten Seiten werden ohne Auslösen einer Challenge gescrapt. Wenn eine Turnstile-Challenge ausgelöst wird und CAPTCHA_API_KEY gesetzt ist, wird diese automatisch über eine Drittanbieter-API gelöst.

• Einschränkungen:

  • Keine REST-API oder CLI-Tools (nur MCP stdio/JSON-RPC)

  • Keine Unterstützung für Nicht-HTML-Inhalte (PDF, Bilder usw.)

  • Keine Authentifizierung oder Sitzungsverwaltung für geschützte Seiten

  • Nicht für Scraping in großem Maßstab oder zur Verletzung von Nutzungsbedingungen von Webseiten gedacht

Entwicklung & Testen

Ausführen von Tests (Docker Compose)

Alle Tests müssen mit Docker Compose ausgeführt werden. Führen Sie Tests nicht außerhalb von Docker aus.

• Alle Tests:

docker compose up --build --abort-on-container-exit test

• Nur MCP-Server-Tests:

docker compose up --build --abort-on-container-exit test_mcp

• Nur Scrapper-Tests:

docker compose up --build --abort-on-container-exit test_scrapper

Ausführen von Benchmarks

docker compose run --rm benchmark

Die Ergebnisse werden in benchmarks/RESULTS.md gespeichert.

Mitwirken

Beiträge sind willkommen! Bitte öffnen Sie Issues oder Pull Requests für Fehlerbehebungen, Funktionen oder Verbesserungen. Wenn Sie größere Änderungen planen, eröffnen Sie bitte zuerst ein Issue, um Ihren Vorschlag zu diskutieren.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.