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 Firefox-Browserinstallation und kann nicht auf Cloud-Hosting-Diensten wie glama.ai ausgeführt werden. Verwenden Sie npx @mozilla/firefox-devtools-mcp@latest, um lokal zu arbeiten, oder verwenden Sie Docker mit dem bereitgestellten Dockerfile.

Sicherheit

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

• Verwenden Sie ein dediziertes Firefox-Profil. Führen Sie den Server niemals gegen Ihr reguläres 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 Tool-Module, die Sie benötigen. Das Standard-Preset basic enthält bereits evaluate_script; --tool-preset slim entfernt es. Höhere Presets wie --tool-preset developer (Debugging, Netzwerk, Konsole, Profiler) und --tool-preset mozilla (privilegierter Kontext) erweitern die Möglichkeiten des Agenten weiter.

Siehe SECURITY.md für eine vollständige Aufschlüsselung der Risiken und wie Sie Schwachstellen melden können.

Anforderungen

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

Installation und Verwendung mit Claude Code oder Codex (npx)

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

Option A – CLI

Claude Code

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

# Headless + Viewport über Argumente
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Oder über Umgebungsvariablen
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest \
  --env START_URL=https://example.com \
  --env FIREFOX_HEADLESS=true

Codex

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

# Headless + Viewport über Argumente
codex mcp add firefox-devtools -- \
  npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Oder über Umgebungsvariablen
codex mcp add firefox-devtools \
  --env START_URL=https://example.com \
  --env FIREFOX_HEADLESS=true \
  -- npx @mozilla/firefox-devtools-mcp@latest

Option B – Konfigurationsdatei bearbeiten

Claude Code

Fügen Sie zu Claude Codes mcp_settings.json hinzu:

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

Codex

Fügen Sie zu ~/.codex/config.toml hinzu:

[mcp_servers.firefox-devtools]
command = "npx"
args = ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"]

[mcp_servers.firefox-devtools.env]
START_URL = "about:blank"

Option C – Hilfsskript (lokaler Dev-Build)

npm run setup
# Claude Code wählen; das Skript speichert JSON am richtigen Pfad

Testen mit MCP Inspector

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

Rufen Sie dann Tools auf wie:

• list_pages, select_page, navigate_page
• take_snapshot dann click_by_uid / fill_by_uid
• list_network_requests (immer aktive Erfassung), get_network_request
• list_downloads (immer aktive Erfassung), 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 Benutzeroberfläche 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 – an einen bereits laufenden Firefox anhängen, statt einen neuen zu starten (CONNECT_EXISTING=true)
• --marionette-port – Marionette-Port für den connect-existing-Modus, Standard 2828 (MARIONETTE_PORT)
• --pref name=value – Firefox-Einstellung beim Start über moz:firefoxOptions setzen (wiederholbar)
• --tool-preset – auswählen, welche Tool-Module aktiviert werden: slim, basic (Standard), developer, mozilla oder all. Siehe Tool-Module und Presets. (TOOL_PRESET)
• --tools – explizite Liste der zu aktivierenden Tool-Module, überschreibt --tool-preset vollständig (z. B. --tools pages network script). Siehe Tool-Module und Presets.
• --enable-script – veraltet, verwenden Sie --tool-preset developer oder --tools ... script debugging. Wählt das Tool-Preset developer aus. (ENABLE_SCRIPT=true)
• --enable-privileged-context – veraltet, verwenden Sie --tool-preset mozilla oder --tools ... privileged prefs. Wählt das Tool-Preset mozilla aus. Erfordert MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device – Firefox für Android-Modus aktivieren; Wert ist die ADB-Geräteseriennummer (z. B. emulator-5554). Führen Sie adb devices aus, um verbundene Geräte aufzulisten. Lassen Sie den Wert weg oder verwenden Sie auto, um das einzelne verbundene Gerät automatisch auszuwählen.
• --android-wipe-app-data – bestätigen, dass der Android-Modus alle Daten der Ziel-App löscht. Erforderlich zusammen mit --android-device. (ANDROID_WIPE_APP_DATA=true)
• --android-package – Android-App-Paketname, Standard org.mozilla.firefox. Andere Pakete: org.mozilla.firefox_beta für Firefox Beta, org.mozilla.fenix für Firefox Nightly, org.mozilla.fenix.debug für Firefox Nightly Debug, org.mozilla.geckoview_example für geckoview (ANDROID_PACKAGE)
• --unrestricted-save-paths – dem saveTo-Parameter erlauben, überall auf der Festplatte zu schreiben, statt in den Standard-Root-Verzeichnissen. Siehe Umfangreiche Ausgabe auf der Festplatte speichern und den Sicherheitshinweis in SECURITY.md. (UNRESTRICTED_SAVE_PATHS=true)
• --log-file – MCP-Server-Logs in eine Datei statt nach stderr schreiben. Nützlich für Debugging-Sitzungen mit MCP-Clients, die die Serverausgabe verbergen. Setzen Sie DEBUG=*, um auch ausführliche Debug-Logs einzuschließen. Beispiel: --log-file /tmp/firefox-mcp.log

Tool-Module und Presets

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

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

Presets (jedes ist eine Obermenge des vorherigen):

• slim – pages, snapshot, input, screenshot
• basic (Standard) – slim plus downloads, script, utilities, management, webextension, screencast
• developer – basic plus debugging, network, console, profiler
• mozilla – developer plus prefs, privileged
• all – jedes Modul

Beachten Sie, dass basic, das Standard-Preset, script und damit das Tool evaluate_script enthält. Siehe SECURITY.md für die Bedeutung für die Angriffsfläche, und verwenden Sie --tool-preset slim oder eine explizite --tools-Liste, um es zu entfernen.

# Das Developer-Preset verwenden (fügt Netzwerk-, Konsolen-, Debugging- und Profiler-Tools hinzu)
npx @mozilla/firefox-devtools-mcp --tool-preset developer

# Nur die benötigten Module aktivieren
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, selbst wenn sie angefordert werden, und protokolliert eine Warnung, die die entfernten Module benennt.

Nützliche Einstellungen (--pref)

• remote.prefs.recommended=false. Wenn Firefox in der Automatisierung läuft, wendet es RecommendedPreferences an, die das Browserverhalten für Tests modifizieren. 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. Aktivieren Sie ausführliche WebDriver-Protokoll-Logs in Firefox. Der MCP-Server übergibt automatisch die passende Log-Ebene an geckodriver, sodass beide Seiten mit derselben Ausführlichkeit protokollieren.
• app.update.disabledForTesting=false. Erlauben Sie 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 zu automatisieren, das auf einem Android-Gerät läuft. Erfordert adb in Ihrem PATH und geckodriver, das automatisch verwaltet wird.

Warnung: Der Android-Modus löscht alle Daten der Ziel-App vor jeder Sitzung. Tabs, Verlauf, Lesezeichen, Passwörter, Cookies und Einstellungen gehen alle verloren. geckodriver führt adb shell pm clear <package> beim Erstellen der Sitzung aus und bietet keine Möglichkeit, dies zu überspringen, und führt die Sitzung dann in einem eigenen temporären Profil aus, das danach gelöscht wird. Aus diesem Grund erfordert --android-device --android-wipe-app-data, und Sie sollten einen Build installieren, der für die Automatisierung bestimmt ist, statt den Browser zu automatisieren, den Sie verwenden. Bug 2064088 verfolgt das Hinzufügen einer Option zu geckodriver, um die vorhandenen App-Daten zu behalten.

# Verbundene Geräte auflisten
adb devices

# Firefox für Android auf dem einzelnen verbundenen Gerät starten
npx @mozilla/firefox-devtools-mcp --android-device auto --android-wipe-app-data

# Ein bestimmtes Gerät ansprechen
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-wipe-app-data

# Stattdessen Firefox Nightly verwenden
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix --android-wipe-app-data

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

Mit vorhandenem Firefox verbinden

Verwenden Sie --connect-existing, um Ihre echte Browsing-Sitzung zu automatisieren, mit Cookies, Anmeldungen und offenen Tabs:

# Firefox mit Marionette und dem Remote Agent (BiDi) starten
firefox --marionette --remote-debugging-port

# Den MCP-Server ausführen
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 ä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

Siehe docs/tools.md für die vollständige Liste der Tools nach Modul, mit Beschreibungen und Parametern (aus dem Quellcode generiert).

• Seiten: list/new/navigate/select/close/get_page_text (get_page_text unterstützt optionales saveTo)
• Snapshot/UID: take/resolve/clear (take unterstützt optionales saveTo)
• Eingabe: click/hover/fill/drag/upload/form fill/press_key/type_text
• Netzwerk: list/get (ID-zuerst, Filter, immer aktive Erfassung; beide unterstützen optionales saveTo)
• Downloads: list_downloads/clear_downloads (immer aktive Erfassung), set_download_behavior (allow/deny/default)
• Konsole: list/clear (list unterstützt optionales saveTo)
• Screenshot: page/by uid (mit optionalem saveTo für CLI-Umgebungen)
• Skript: evaluate_script (optionales sandbox für eine isolierte Realm; optionales saveTo für umfangreiche Ergebnisse)
• Privilegierter Kontext: list/select privilegierte ("chrome") Kontexte, 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-Verwaltung: get_firefox_info, get_firefox_output, restart_firefox
• Firefox-Einstellungen: get_firefox_prefs, set_firefox_prefs (erfordert MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Profiler: profiler_is_active, profiler_start (Preset oder explizite Konfiguration), profiler_stop (speichert Profil im Download-Verzeichnis)
• Screencast: screencast_start (zeichnet den Seiten-Viewport in eine Videodatei im Download-Verzeichnis auf), screencast_stop (erfordert Firefox 154+)
• Dienstprogramme: accept/dismiss Dialog, history back/forward, 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, get_page_text, evaluate_script und evaluate_privileged_script akzeptieren einen optionalen saveTo-Parameter, der das Ergebnis in eine Datei schreibt, statt es inline zurückzugeben. saveTo nimmt eine von drei Formen an:

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

Die Antwort gibt den Pfad und die Bytegröße zurück. Die gespeicherte Datei enthält immer die vollständigen, nicht abgeschnittenen Daten: Die Inline-Größen-Sicherheitsvorkehrungen (Konsolenmeldungs-Obergrenzen, Netzwerk-Header- Kürzung, Snapshot-Zeilen-Obergrenzen) gelten niemals dafür.

Die Text erzeugenden Tools (alles außer den Screenshots) akzeptieren auch preview, eine Anzahl von Zeichen der gespeicherten Ausgabe, die inline als kurzer Auszug zurückgegeben werden. 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 gegen das aktuelle Arbeitsverzeichnis aufgelöst, und absolute Pfade sind nur innerhalb von ~/.firefox-devtools-mcp erlaubt. 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 beispielsweise mit Claude Codes Read-Tool angezeigt werden, ohne die Kontextgröße zu beeinträchtigen.

Lokale Entwicklung

npm install
npm run build

# Mit Inspector gegen lokalen Build ausführen
npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720

# Oder in Dev mit Hot Reload ausführen
npm run inspector:dev

Siehe CONTRIBUTING.md für weitere Details zur lokalen Entwicklung, zum Testen und zu CI.

Fehlerbehebung

• Firefox nicht gefunden: --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) oder den korrekten Pfad auf Ihrem Betriebssystem übergeben.
• Erster Lauf ist langsam: Selenium richtet die BiDi-Sitzung ein; nachfolgende Läufe sind schneller.
• Veraltete UIDs: Eine UID bleibt gültig, bis ihr Element entfernt wird oder die Seite navigiert; nehmen Sie einen frischen Snapshot (take_snapshot), wenn ein UID-Tool meldet, dass eine nicht mehr vorhanden ist.
• 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 Den absoluten Pfad zu npx verwenden (Erweiterung anpassen – .cmd, .bat, .exe oder .ps1 – passend zu Ihrer Einrichtung):

    root@kitploit:~

    "mcpServers": {
      "firefox-devtools": {
        "command": "C:\\nvm4w\\nodejs\\npx.ps1",
        "args": ["-y", "@mozilla/firefox-devtools-mcp@latest"]
      }
    }
    

Versionierung

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

Mitwirken

Siehe CONTRIBUTING.md für Informationen zum Melden von Problemen, Ausführen von Tests und Arbeiten am Projekt lokal.

Autor

Gepflegt von Mozilla.

Lizenz

Lizenziert unter entweder MIT oder Apache 2.0 nach Ihrer Wahl.