webshot-mcp

Geben Sie Ihrem Agenten Augen – ohne ihm einen Browser oder Ihr Netzwerk zu geben. Ein MCP-Server mit zwei Tools, screenshot und page_text, der eine Verbindung zu einem bereits laufenden Chrome (über CDP) herstellt und vollständige Seiten oder einzelne Elemente erfasst. Es wird nie ein Browser gestartet oder heruntergeladen; Ziele im privaten Netzwerk werden durch eine SSRF-bewusste URL-Richtlinie blockiert.

Warum es das gibt

Zwei Erkenntnisse aus dem Durchlaufen von visuellen Prüf- und Korrekturschleifen mit Codierungsagenten:

1. Einen Browser pro Screenshot zu starten, ist der langsame, fehleranfällige Weg. Ein persistenter kopfloser Chromium (Docker-Sidecar, CI-Dienst, Ihr Desktop-Chrome mit --remote-debugging-port) ist warm, gemeinsam genutzt und zuverlässig. Das fehlende Stück ist ein disziplinierter Client: Verbindung über CDP herstellen, einen neuen Kontext pro Aufnahme öffnen, nur das schließen, was geöffnet wurde, den gemeinsam genutzten Browser niemals beenden. Diese Disziplin ist dieses Repository.

2. Ein Screenshot-Tool in Ihrem Netzwerk ist ein SSRF-Proxy mit einer Kamera. Ein Agent, der dazu überredet werden kann, "Screenshot http://169.254.169.254/…" oder http://redis.internal:6379/ zu machen, wird bereitwillig Ihren Cloud-Metadaten-Endpunkt fotografieren. Daher blockiert die URL-Richtlinie Loopback, RFC-1918, Link-Local, CGNAT und v6-lokale Ziele – einschließlich Hostnamen, die darauf aufgelöst werden –, es sei denn, Sie setzen den Hostnamen explizit auf die Whitelist. Lokale Entwicklungsserver sind die legitime Ausnahme, und Sie benennen sie einzeln.

Schnellstart

npm install
npm test        # URL-policy test suite — no browser needed
npm run demo    # policy walkthrough + a real screenshot if a CDP Chrome is reachable

Holen Sie sich einen CDP-fähigen Chrome (einen von):

# your installed Chrome, headless
chrome --headless --remote-debugging-port=9222 --remote-debugging-address=127.0.0.1 about:blank

# or a Docker sidecar you keep running
docker run -d -p 127.0.0.1:9222:9222 chromedp/headless-shell

Binden Sie ihn in Claude Code ein:

claude mcp add webshot \
  -e WEBSHOT_CDP_URL=http://127.0.0.1:9222 \
  -e WEBSHOT_ALLOW_HOSTS=localhost,127.0.0.1 \
  -- npx tsx src/server.ts

Bitten Sie den Agenten dann um Dinge wie "mache einen Screenshot des Hero-Bereichs von localhost:5173 – nur .hero – und sag mir, was nicht stimmt": selector beschneidet auf ein Element, was die Aufmerksamkeit des Agenten (und Ihre Tokens) auf den diskutierten Teil lenkt, anstatt auf eine 4.000 Pixel hohe Seite.

Tools

Designhinweise

• Frischer Kontext pro Aufnahme, gemeinsam genutzter Browser für die Lebensdauer. Kontexte sind billig und isoliert (Cookies, Cache, Viewport); der Browser ist teuer und wird gemeinsam genutzt. browser.close() auf einer CDP-Verbindung trennt die Verbindung, ohne den entfernten Browser zu beenden – der Server kann den ganzen Tag neu starten, ohne Chrome zu berühren.

• DNS wird geprüft, Rebindung wird dokumentiert. Nicht-IP-Hostnamen werden aufgelöst und jede zurückgegebene Adresse erneut gegen die privaten Bereiche verifiziert. Ein bösartiger DNS-Server, der bei der zweiten Auflösung des Browsers selbst anders antwortet (klassisches Rebinding), liegt außerhalb des Rahmens eines Screenshot-Tools – hier vermerkt, nicht übergangen.

• deviceScaleFactor: 2 – Retina-Erfassungen, weil Agenten (und Menschen) unscharfen Text in Screenshots öfter falsch lesen, als man denkt.

• Die Richtlinie ist fail-closed und testbar. evaluateUrl ist eine reine Funktion mit der gesamten Bedrohungstabelle in ihrer Testdatei; der Server ruft den Browser nie auf, bevor die Richtlinie zustimmt.

Stack

TypeScript · @modelcontextprotocol/sdk (stdio) · playwright-core (nur CDP-Client – keine gebündelten Browser) · zod · vitest.

Lizenz

MIT © Brandon Ta