firefox-devtools-mcp

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. Die Standard-Voreinstellung basic enthält bereits evaluate_script; --tool-preset slim entfernt es. Höhere Voreinstellungen 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 übergeben Sie --firefox-path)

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 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

Codex

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

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

# Or via environment variables
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 Claudes 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 Entwicklungs-Build)

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

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 und dann click_by_uid / fill_by_uid
• list_network_requests (Daueraufzeichnung), get_network_request
• list_downloads (Daueraufzeichnung), 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, anstatt einen neuen zu starten (CONNECT_EXISTING=true)
• --marionette-port – Marionette-Port für den Verbindungsmodus zu bestehender Instanz, 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 sollen: slim, basic (Standard), developer, mozilla oder all. Siehe Tool-Module und Voreinstellungen. (TOOL_PRESET)
• --tools – explizite Liste der zu aktivierenden Tool-Module, die --tool-preset vollständig überschreibt (z. B. --tools pages network script). Siehe Tool-Module und Voreinstellungen.
• --enable-script – veraltet, verwenden Sie --tool-preset developer oder --tools ... script debugging. Wählt die Tool-Voreinstellung developer. (ENABLE_SCRIPT=true)
• --enable-privileged-context – veraltet, verwenden Sie --tool-preset mozilla oder --tools ... privileged prefs. Wählt die Tool-Voreinstellung mozilla. 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 Parameter saveTo erlauben, überall auf der Festplatte zu schreiben, anstatt nur in den Standard-Wurzelverzeichnissen. Siehe Speichern umfangreicher Ausgaben auf der Festplatte und den Sicherheitshinweis in SECURITY.md. (UNRESTRICTED_SAVE_PATHS=true)
• --log-file – MCP-Server-Logs in eine Datei schreiben, anstatt nach stderr. Nützlich für Debugging-Sitzungen mit MCP-Clients, die die Serverausgabe ausblenden. Setzen Sie DEBUG=*, um auch ausführliche Debug-Logs einzuschließen. Beispiel: --log-file /tmp/firefox-mcp.log

Tool-Module und Voreinstellungen

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

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

Voreinstellungen (jede ist eine Obermenge der 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, die Standardeinstellung, script und daher 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.

# Use the developer preset (adds network, console, debugging and profiler 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, 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 Automatisierung läuft, wendet es RecommendedPreferences an, die das Browserverhalten für Tests ändern. Setzen Sie remote.prefs.recommended auf false, um diese zu überspringen und eine Konfiguration zu haben, die näher an einer regulären Firefox-Instanz liegt.
• remote.log.level=Trace. Aktivieren Sie ausführliche WebDriver-Protokoll-Logs in Firefox. Der MCP-Server übergibt automatisch die passende Log-Stufe 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, es 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 Automatisierung dediziert ist, anstatt den Browser zu automatisieren, den Sie verwenden. Bug 2064088 verfolgt das Hinzufügen einer Option zu geckodriver, um die vorhandenen App-Daten zu behalten.

# List connected devices
adb devices

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

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

# Use Firefox Nightly instead
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 verwaltet.

Mit bestehendem Firefox verbinden

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

# 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 das 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 optional saveTo)
• Snapshot/UID: take/resolve/clear (take unterstützt optional saveTo)
• Eingabe: click/hover/fill/drag/upload/Formular ausfüllen
• Netzwerk: list/get (ID-zuerst, Filter, Daueraufzeichnung; beide unterstützen optional saveTo)
• Downloads: list_downloads/clear_downloads (Daueraufzeichnung), set_download_behavior (allow/deny/default)
• Konsole: list/clear (list unterstützt optional saveTo)
• Screenshot: page/by uid (mit optionalem saveTo für CLI-Umgebungen)
• Skript: evaluate_script (optional sandbox für eine isolierte Realm; optional 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 (Voreinstellung 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, Verlauf zurück/vor, Viewport setzen

Speichern umfangreicher Ausgaben auf der Festplatte

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 Parameter saveTo, der das Ergebnis in eine Datei schreibt, anstatt 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 mit Zeitstempel versehene Datei wird darin generiert)
• true (eine mit Zeitstempel versehene Datei 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 relativ zum aktuellen 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 dem Read-Tool von Claude Code angezeigt 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 Details zur lokalen Entwicklung, zum Testen und zu 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 auf Ihrem Betriebssystem.
• Der erste Start ist langsam: Selenium richtet die BiDi-Sitzung ein; nachfolgende Starts sind schneller.
• Veraltete UIDs: Eine UID bleibt gültig, bis ihr Element entfernt wird oder die Seite navigiert; machen Sie einen neuen Schnappschuss (take_snapshot), wenn ein UID-Tool meldet, dass eine nicht mehr vorhanden ist.
• Windows 10: Fehler bei der Erkennung für den MCP-Server 'firefox-devtools': MCP-Fehler -32000: Verbindung geschlossen

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

    "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 — passend zu Ihrer Einrichtung):

    "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 Hinweise 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.