Firefox DevTools MCP

Model Context Protocol-Server zur Automatisierung von Firefox über WebDriver BiDi (über Selenium WebDriver). Funktioniert mit Claude Code, Claude Desktop, Cursor, Cline und anderen MCP-Clients.

Repository: https://github.com/mozilla/firefox-devtools-mcp

Hinweis: Dieser MCP-Server erfordert eine lokale Installation des Firefox-Browsers und kann nicht auf Cloud-Hosting-Diensten wie glama.ai ausgeführt werden. Verwenden Sie npx @mozilla/firefox-devtools-mcp@latest, um lokal zu starten, oder verwenden Sie Docker mit dem mitgelieferten Dockerfile.

Sicherheit

Browser-MCP-Server bergen inhärente Risiken. Einige wichtige Vorgehensweisen:

• Verwenden Sie ein dediziertes Firefox-Profil. Führen Sie den Server niemals mit Ihrem regulären Profil aus – der Agent hat Zugriff auf alles, was der Browser erreichen kann, einschließlich Cookies und gespeicherter Sitzungen.
• Seien Sie vorsichtig, welche Websites Sie besuchen. Seiten können Inhalte zurückgeben, die darauf ausgelegt sind, den Agenten zu manipulieren (Prompt-Injection). Bleiben Sie bei Websites, die Sie kontrollieren oder denen Sie vertrauen.
• Aktivieren Sie nur die benötigten Tool-Module. Höhere Presets wie --tool-preset developer (script, debugging) und --tool-preset mozilla (privileged context) erweitern die Möglichkeiten des Agenten erheblich.

Siehe SECURITY.md für eine vollständige Aufschlüsselung der Risiken und Anweisungen zum Melden von Schwachstellen.

Voraussetzungen

• Node.js ≥ 20.19.0
• Firefox 100+ installiert (automatisch erkannt, oder --firefox-path angeben)

Installation und Verwendung mit Claude Code (npx)

Empfohlen: Verwenden Sie npx, damit Sie immer die neueste veröffentlichte Version von npm ausführen.

Option A – Claude Code CLI

claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest

Übergeben Sie Optionen entweder als Argumente oder als Umgebungsvariablen. Beispiele:

# Headless + viewport via args
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Or via environment variables
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest \
  --env START_URL=https://example.com \
  --env FIREFOX_HEADLESS=true

Option B – Claude Code-Einstellungen JSON bearbeiten

Fügen Sie Folgendes zu Ihrer Claude-Code-Konfigurationsdatei hinzu:

• macOS: ~/Library/Application Support/Claude/Code/mcp_settings.json
• Linux: ~/.config/claude/code/mcp_settings.json
• Windows: %APPDATA%\Claude\Code\mcp_settings.json

{
  "mcpServers": {
    "firefox-devtools": {
      "command": "npx",
      "args": ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "env": {
        "START_URL": "about:blank"
      }
    }
  }
}

Option C – Hilfsskript (lokaler Dev-Build)

npm run setup
# Choose Claude Code; the script saves JSON to the right path

Ausprobieren mit MCP Inspector

npx @modelcontextprotocol/inspector npx @mozilla/firefox-devtools-mcp@latest --start-url https://example.com --headless

Rufen Sie dann Tools wie diese auf:

• list_pages, select_page, navigate_page
• take_snapshot, dann click_by_uid / fill_by_uid
• list_network_requests (ständige Aufzeichnung), get_network_request
• list_downloads (ständige Aufzeichnung), set_download_behavior
• screenshot_page, list_console_messages

CLI-Optionen

Sie können Flags oder Umgebungsvariablen übergeben (Namen auf der rechten Seite):

• --firefox-path — absoluter Pfad zur Firefox-Binärdatei
• --headless — ohne UI ausführen (FIREFOX_HEADLESS=true)
• --viewport 1280x720 — anfängliche Fenstergröße
• --profile-path — ein bestimmtes Firefox-Profil verwenden
• --firefox-arg — zusätzliche Firefox-Argumente (wiederholbar)
• --start-url — diese URL beim Start öffnen (START_URL)
• --accept-insecure-certs — TLS-Fehler ignorieren (ACCEPT_INSECURE_CERTS=true)
• --connect-existing — sich mit einem bereits laufenden Firefox verbinden, anstatt einen neuen zu starten (CONNECT_EXISTING=true)
• --marionette-port — Marionette-Port für den Modus connect-existing, Standard 2828 ()

Tool-Module und Presets

Tools sind in Module gruppiert. Sie wählen aus, welche Module verfügbar sein sollen, entweder mit einem benannten Preset (--tool-preset) oder mit einer expliziten Liste (--tools). Wenn beide angegeben sind, gewinnt --tools und das Preset wird ignoriert.

Module: pages, snapshot, input, network, console, screenshot, utilities, management, webextension, profiler, screencast, script, debugging, prefs, privileged.

Presets (jedes ist eine Obermenge des vorherigen):

• slim — pages, snapshot, input, network, console
• basic (Standard) — slim plus screenshot, utilities, management, webextension, profiler, screencast
• developer — basic plus ,

# Use the developer preset (adds script and debugging tools)
npx @mozilla/firefox-devtools-mcp --tool-preset developer

# Enable only the modules you need
npx @mozilla/firefox-devtools-mcp --tools pages network console

Die Module prefs und privileged erfordern MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 und sind nur im Mozilla-internen Build verfügbar; das öffentliche Paket überspringt sie stillschweigend, selbst wenn sie angefordert werden.

Nützliche Voreinstellungen (--pref)

• remote.prefs.recommended=false. Wenn Firefox unter Automatisierung läuft, wendet es RecommendedPreferences an, die das Browserverhalten für Tests verändern. Setzen Sie remote.prefs.recommended auf false, um diese zu überspringen und eine Konfiguration zu erhalten, die einer regulären Firefox-Instanz näher kommt.
• remote.log.level=Trace. Aktiviert ausführliche WebDriver-Protokolle in Firefox. Der MCP-Server übergibt die passende Protokollstufe automatisch an geckodriver, sodass beide Seiten mit derselben Ausführlichkeit protokollieren.
• app.update.disabledForTesting=false. Erlaubt Firefox, Updates automatisch herunterzuladen und anzuwenden. Beachten Sie, dass Updates Ihre Sitzung unterbrechen können. Erfordert außerdem das Setzen von remote.prefs.recommended=false.

Firefox für Android

Verwenden Sie --android-device, um Firefox auf einem Android-Gerät zu automatisieren. Erfordert adb in Ihrem PATH sowie geckodriver, das automatisch verwaltet wird.

# List connected devices
adb devices

# Launch Firefox for Android on the single connected device
npx @mozilla/firefox-devtools-mcp --android-device auto

# Target a specific device
npx @mozilla/firefox-devtools-mcp --android-device <serial>

# Use Firefox Nightly instead
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix

Die Portweiterleitung zwischen Host und Gerät wird automatisch von geckodriver übernommen.

Verbindung zu einem vorhandenen Firefox herstellen

Verwenden Sie --connect-existing, um Ihre echte Browsersitzung zu automatisieren, mit Cookies, Anmeldungen und geöffneten Tabs:

# Start Firefox with Marionette and the Remote Agent (BiDi)
firefox --marionette --remote-debugging-port

# Run the MCP server
npx @mozilla/firefox-devtools-mcp --connect-existing --marionette-port 2828

Beide Flags sind erforderlich, da der MCP sowohl WebDriver Classic (--marionette) als auch WebDriver BiDi (--remote-debugging-port) verwendet. Wenn Firefox nur mit --marionette gestartet wird, kann der MCP-Server keine Verbindung herstellen und fordert Sie auf, Firefox mit beiden Flags neu zu starten.

Warnung: Lassen Sie Marionette während des normalen Browsens nicht aktiviert. Es setzt navigator.webdriver = true und verändert andere Browser-Fingerprint-Signale, was Bot-Erkennung auf Websites auslösen kann, die durch Cloudflare, Akamai usw. geschützt sind. Aktivieren Sie Marionette nur, wenn Sie MCP-Automatisierung benötigen, und starten Sie Firefox danach normal neu.

Tool-Übersicht

• Pages: auflisten/neu/navigieren/auswählen/schließen
• Snapshot/UID: aufnehmen/auflösen/löschen (take unterstützt optionales saveTo)
• Input: klicken/hovern/ausfüllen/ziehen/hochladen/Formular ausfüllen <<<<<<< HEAD
• Network: list/get (ID-zuerst, Filter, ständige Aufzeichnung; beide unterstützen optionales saveTo)
• Console: list/clear (list unterstützt optionales saveTo) =======
• Network: list/get (ID-zuerst, Filter, ständige Aufzeichnung)
• Downloads: list_downloads/clear_downloads (ständige Aufzeichnung), set_download_behavior (erlauben/verweigern/Standard)
• Console: list/clear

6873767 (Bug 2055949 - [firefox-devtools-mcp] expose download events to firefox devtools mcp)

• Screenshot: Seite/nach UID (mit optionalem saveTo für CLI-Umgebungen)
• Script: evaluate_script (mit optionalem saveTo für umfangreiche Ergebnisse)
• Privileged Context: privilegierte („chrome“) Kontexte auflisten/auswählen, evaluate_privileged_script (erfordert MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• WebExtension: install_extension, uninstall_extension, list_extensions (list erfordert MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Firefox Management: get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs
• Profiler: profiler_is_active, profiler_start (Preset oder explizite Konfiguration), profiler_stop (speichert das Profil im Download-Verzeichnis)
• Screencast: screencast_start (zeichnet den Seiten-Viewport in einer Videodatei im Download-Verzeichnis auf), screencast_stop (erfordert Firefox 154+)
• Utilities: Dialog akzeptieren/verwerfen, Verlauf zurück/vor, Viewport setzen

Umfangreiche Ausgabe auf der Festplatte speichern

Große Tool-Ausgaben können in CLI-Clients wie Claude Code erheblichen Kontext verbrauchen. Die Tools screenshot_page, screenshot_by_uid, take_snapshot, list_console_messages, list_network_requests, get_network_request, evaluate_script und evaluate_privileged_script akzeptieren einen optionalen Parameter saveTo, der das Ergebnis in eine Datei schreibt, anstatt es inline zurückzugeben. saveTo hat eine von drei Formen:

• ein Dateipfad (relativ zum aktuellen Arbeitsverzeichnis oder absolut innerhalb von ~/.firefox-devtools-mcp; übergeordnete Verzeichnisse werden erstellt)
• ein vorhandenes Verzeichnis (darin wird eine mit Zeitstempel versehene Datei erzeugt)
• true (eine mit Zeitstempel versehene Datei wird unter ~/.firefox-devtools-mcp/output/ erzeugt)

Die Antwort gibt den Pfad und die Bytegröße zurück. Die gespeicherte Datei enthält immer die vollständigen, ungekürzten Daten: Die Inline-Größenbegrenzungen (Konsolenmeldungs-Obergrenzen, Kürzung von Netzwerk-Headern, Snapshot-Zeilenobergrenzen) gelten für sie nie.

Die textproduzierenden Tools (alles außer den Screenshots) akzeptieren außerdem preview, eine Anzahl von Zeichen der gespeicherten Ausgabe, die inline als kurzer Auszug zurückgegeben wird. Screenshots haben keine Vorschau.

screenshot_page({ saveTo: "page.png" })
take_snapshot({ saveTo: true })
list_network_requests({ urlContains: "api", saveTo: "network.json" })
evaluate_script({ function: "() => performance.getEntries()", saveTo: true, preview: 2000 })

Standardmäßig sind Speicherpfade eingeschränkt: Relative Pfade werden relativ zum aktuellen Arbeitsverzeichnis aufgelöst, und absolute Pfade sind nur innerhalb von ~/.firefox-devtools-mcp zulässig. Pfade, die diese Orte verlassen, werden abgelehnt. Starten Sie den Server mit --unrestricted-save-paths, um an beliebige Orte zu schreiben, einschließlich absoluter Pfade außerhalb dieses Verzeichnisses.

Gespeicherte Dateien können dann mit dem Read-Tool von Claude Code angesehen werden, ohne die Kontextgröße zu beeinträchtigen.

Lokale Entwicklung

npm install
npm run build

# Run with Inspector against local build
npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720

# Or run in dev with hot reload
npm run inspector:dev

Weitere Einzelheiten zu lokaler Entwicklung, Tests und CI finden Sie in CONTRIBUTING.md.

Fehlerbehebung

• Firefox nicht gefunden: Übergeben Sie --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) oder den korrekten Pfad für Ihr Betriebssystem.
• Der erste Start ist langsam: Selenium richtet die BiDi-Sitzung ein; spätere Starts sind schneller.
• Veraltete UIDs nach der Navigation: Machen Sie einen neuen Snapshot (take_snapshot), bevor Sie UID-Tools verwenden.
• Windows 10: Fehler bei der Erkennung für MCP-Server 'firefox-devtools': MCP-Fehler -32000: Verbindung geschlossen

  • Lösung 1 Mit cmd /c umschließen (Details):

    root@kitploit:~

    "mcpServers": {
      "firefox-devtools": {
        "command": "cmd",
        "args": ["/c", "npx", "-y", "@mozilla/firefox-devtools-mcp@latest"]
      }
    }
    

  • Lösung 2 Verwenden Sie den absoluten Pfad zu npx (passen Sie die Erweiterung an – .cmd, .bat, .exe oder .ps1 – entsprechend Ihrer Einrichtung):

    root@kitploit:~

Versionierung

• Pre-1.0-API: Versionen beginnen bei 0.x. Verwenden Sie @latest mit npx für die neueste Version.

Mitwirken

Informationen dazu, wie Sie Issues melden, Tests ausführen und lokal am Projekt arbeiten, finden Sie in CONTRIBUTING.md.

Autor

Gepflegt von Mozilla.

Lizenz

Lizenziert unter wahlweise MIT oder Apache 2.0.