firefox-devtools-mcp

Firefox DevTools MCP

Model Context Protocol-Server zur Automatisierung von Firefox über WebDriver BiDi (mittels 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-Browser-Installation und kann nicht auf Cloud-Hosting-Diensten wie glama.ai ausgeführt werden. Verwenden Sie npx @mozilla/firefox-devtools-mcp@latest, um ihn lokal auszuführen, oder nutzen Sie Docker mit der 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 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 Seiten Sie besuchen. Seiten können Inhalte zurückgeben, die darauf ausgelegt sind, den Agenten zu manipulieren (Prompt Injection). Bleiben Sie bei Seiten, die Sie kontrollieren oder denen Sie vertrauen.
• Vermeiden Sie das Aktivieren zusätzlicher Flags, sofern nicht erforderlich. --enable-script und --enable-privileged-context erweitern erheblich, was der Agent tun kann.

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

Voraussetzungen

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

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 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-Einstellungs-JSON bearbeiten

Fügen Sie 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 Entwicklungs-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 Werkzeuge 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
• screenshot_page, list_console_messages

CLI-Optionen

Sie können Flags oder Umgebungsvariablen übergeben (Namen rechts):

• --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 „Mit bestehendem verbinden“, Standard 2828 (MARIONETTE_PORT)
• --pref name=value – Firefox-Einstellung beim Start über moz:firefoxOptions setzen (wiederholbar)
• --enable-script – das evaluate_script-Werkzeug aktivieren (führt beliebiges JavaScript im Seitenkontext aus) und Debugging-Werkzeuge (Skripte auflisten, Quelltext inspizieren, Logpoints setzen). Debugging-Werkzeuge erfordern Firefox 153+. (ENABLE_SCRIPT=true)
• --enable-privileged-context – privilegierte Kontextwerkzeuge aktivieren: privilegierte Kontexte auflisten/auswählen, privilegierte Skripte auswerten, Firefox-Einstellungen abrufen/setzen und Erweiterungen auflisten. 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 einzige verbundene Gerät automatisch auszuwählen.
• --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)
• --log-file – MCP-Server-Protokolle in eine Datei schreiben anstatt nach stderr. Nützlich zum Debuggen von Sitzungen mit MCP-Clients, die die Serverausgabe verbergen. Setzen Sie DEBUG=*, um auch ausführliche Debug-Protokolle einzuschließen. Beispiel: --log-file /tmp/firefox-mcp.log

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 ä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-Protokollprotokolle in Firefox. Der MCP-Server übergibt automatisch den passenden Protokollierungsgrad 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 auch 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 und geckodriver, der 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.

Mit bestehendem Firefox verbinden

Verwenden Sie --connect-existing, um Ihre echte Browsersitzung zu automatisieren – mit intakten Cookies, Logins und offenen Tabs:

# Start Firefox with Marionette enabled
firefox --marionette

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

Oder setzen Sie marionette.enabled auf true in about:config (oder user.js), um Marionette bei jedem Start zu aktivieren.

BiDi-abhängige Funktionen (Konsolenereignisse, Netzwerkereignisse) sind im Modus „Mit bestehendem verbinden“ nicht verfügbar; alle anderen Funktionen funktionieren normal.

Warnung: Lassen Sie Marionette während des normalen Surfens nicht aktiviert. Es setzt navigator.webdriver = true und ändert andere Browser-Fingerabdrucksignale, was die Bot-Erkennung auf Seiten 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.

Werkzeugübersicht

• Seiten: auflisten/neu/navigieren/auswählen/schließen
• Snapshot/UID: aufnehmen/auflösen/löschen
• Eingabe: klicken/hovern/ausfüllen/ziehen/hochladen/Formular ausfüllen
• Netzwerk: auflisten/abrufen (ID-zuerst, Filter, immer aktive Erfassung)
• Konsole: auflisten/löschen
• Screenshot: Seite/nach UID (mit optionalem saveTo für CLI-Umgebungen)
• Skript: evaluate_script
• Privilegierter Kontext: 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-Verwaltung: get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs
• Profiler: profiler_is_active, profiler_start (Voreinstellung oder explizite Konfiguration), profiler_stop (speichert Profil im Download-Verzeichnis)
• Dienstprogramme: Dialog akzeptieren/ablehnen, Verlauf zurück/vorwärts, Viewport setzen

Screenshot-Optimierung für Claude Code

Bei der Verwendung von Screenshots in der Claude Code CLI können die base64-Bilddaten erheblichen Kontext verbrauchen. Verwenden Sie den Parameter saveTo, um Screenshots stattdessen auf der Festplatte zu speichern:

screenshot_page({ saveTo: "/tmp/page.png" })
screenshot_by_uid({ uid: "abc123", saveTo: "/tmp/element.png" })

Die Datei kann dann mit Claude Codes Read-Werkzeug betrachtet 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

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

Fehlerbehebung

• Firefox nicht gefunden: Übergeben Sie --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) oder den korrekten Pfad auf Ihrem Betriebssystem.
• Der erste Lauf ist langsam: Selenium richtet die BiDi-Sitzung ein; nachfolgende Läufe sind schneller.
• Veraltete UIDs nach der Navigation: Nehmen Sie einen frischen Snapshot (take_snapshot) auf, bevor Sie UID-Werkzeuge verwenden.
• Windows 10: Fehler bei der Erkennung des MCP-Servers '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 – entsprechend 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 Informationen, wie Sie Probleme melden, Tests ausführen und lokal am Projekt arbeiten können.

Autor

Betreut von Mozilla.

Lizenz

Lizenziert wahlweise unter MIT oder Apache 2.0.