firefox-devtools-mcp

Firefox DevTools MCP

Model Context Protocol-Server, der es KI-Agenten ermöglicht, Firefox zu verwenden. Es gibt zwei Hauptanwendungsfälle:

• Agentisches Browsen: Der Agent verwendet den Browser für reguläre Aufgaben, wie das Lesen von Seiten, das Ausfüllen von Formularen und das Durchlaufen mehrstufiger Abläufe auf Websites.
• Agent-unterstützte Webentwicklung: Der Agent lädt die Seite, an der Sie arbeiten, und untersucht sie mit Entwicklerwerkzeugen wie Konsole, Netzwerkanfragen, Debugger und Profiler.

Er steuert Firefox über WebDriver BiDi (über Selenium WebDriver) und 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 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 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 über --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 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 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 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 Werkzeuge auf wie:

• list_pages, select_page, navigate_page
• take_snapshot und 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 läuft in einem firefox_devtools_mcp_profile-Unterordner dieses Pfads, gekennzeichnet durch eine .firefox-devtools-mcp-Datei; das Verweisen von --profile-path auf ein markiertes Profil verwendet es direkt wieder
• --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 Verbinden-mit-bestehendem-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 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 developer-Tool-Voreinstellung. (ENABLE_SCRIPT=true)
• --enable-privileged-context – veraltet, verwenden Sie --tool-preset mozilla oder --tools ... privileged prefs. Wählt die mozilla-Tool-Voreinstellung. 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, anstatt in den Standard-Wurzelverzeichnissen. Siehe Speichern umfangreicher Ausgaben auf der Festplatte und den Sicherheitshinweis in SECURITY.md. (UNRESTRICTED_SAVE_PATHS=true)
• --log-file – MCP-Serverprotokolle in eine Datei schreiben, anstatt nach stderr. Nützlich für Debugging-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

Tool-Module und Voreinstellungen

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

Voreinstellungen (jede ist eine Obermenge der vorherigen):

• slim – das Minimum zum Browsen und Interagieren mit Seiten
• basic (Standard) – fügt Werkzeuge für reguläres Browsen hinzu
• developer – fügt Werkzeuge für Webentwickler hinzu
• mozilla – fügt Werkzeuge für Firefox-Entwickler hinzu
• all – jedes Modul

Siehe docs/tools.md für die Liste der Module und die Module in jeder Voreinstellung.

Beachten Sie, dass basic, die Standardeinstellung, script und daher das evaluate_script-Werkzeug 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 Modul launch erfordert ebenfalls den Mozilla-internen Build: Es startet Firefox unter einer vom Aufrufer gewählten Binärdatei, Profil, Umgebung und Satz von Einstellungen neu, was eine Konfigurationsänderung ist, die der Betreiber besitzen sollte. Verwenden Sie --pref, --firefox-path und die anderen Befehlszeilenoptionen stattdessen. Das Modul bidi erfordert ebenfalls den Mozilla-internen Build: Es sendet jeden WebDriver-BiDi-Befehl, sodass es Zugriff auf das bietet, was die anderen Module verfügbar machen. Das öffentliche Paket überspringt diese Module, selbst wenn sie angefordert werden, und protokolliert eine Warnung, die die Module nennt, die es entfernt hat.

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-Protokolle in Firefox. Der MCP-Server übergibt automatisch die passende Protokollebene 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 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, 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 der Automatisierung gewidmet 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 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-Fingerabdruck-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.

Werkzeugübersicht

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

Speichern umfangreicher Ausgaben auf der Festplatte

Große Werkzeugausgaben können erheblichen Kontext in CLI-Clients wie Claude Code verbrauchen. Mehrere Werkzeuge akzeptieren einen optionalen saveTo-Parameter, der das Ergebnis in eine Datei schreibt, anstatt es inline zurückzugeben. Siehe docs/tools.md für die Liste. saveTo nimmt eine von drei Formen an:

• einen Dateipfad (relativ zum aktuellen Arbeitsverzeichnis oder absolut innerhalb von ~/.firefox-devtools-mcp/output; übergeordnete Verzeichnisse werden erstellt). Pfade, die ein Firefox-Profil erreichen, oder die Dateien, die dieser Server zurückliest, werden abgelehnt
• ein vorhandenes Verzeichnis (eine mit Zeitstempel versehene Datei wird darin 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, nicht abgeschnittenen Daten: Die Inline-Größenbegrenzungen (Konsolenmeldungs-Obergrenzen, Netzwerkheader- Abschneidung, Snapshot-Zeilenbegrenzungen) gelten niemals dafür.

Die Text erzeugenden Werkzeuge akzeptieren auch preview, eine Anzahl von Zeichen der gespeicherten Ausgabe, die inline als kurzer Auszug zurückgegeben werden soll. Die Liste in docs/tools.md zeigt, welche Werkzeuge dies unterstützen.

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

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

Fehlerbehebung

• Firefox nicht gefunden: Übergeben Sie --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) oder den korrekten Pfad auf Ihrem Betriebssystem.
• 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 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 Umgeben Sie mit cmd /c (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"]
      }
    }
    

Versionsverwaltung

• 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, wie Sie Probleme melden, Tests ausführen und lokal am Projekt arbeiten können.

Autor

Gepflegt von Mozilla.

Lizenz

Lizenziert unter MIT oder Apache 2.0 nach Ihrer Wahl.