Firefox DevTools MCP

Model Context Protocol-Server zur Automatisierung von Firefox via WebDriver BiDi (durch 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 firefox-devtools-mcp@latest, um ihn lokal auszuführen, oder nutzen Sie Docker mit dem bereitgestellten Dockerfile.

Anforderungen

• Node.js ≥ 20.19.0

• Firefox 100+ installiert (wird automatisch erkannt oder über --firefox-path übergeben)

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 firefox-devtools-mcp@latest

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

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

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

Option B — Claude Code-Einstellungen (JSON) bearbeiten

Fügen Sie dies 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", "firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "env": {
        "START_URL": "about:home"
      }
    }
  }
}

Option C — Hilfsskript (lokaler Entwicklungs-Build)

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

Ausprobieren mit dem MCP Inspector

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

Anschließend können Sie Tools aufrufen 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

• screenshot_page, list_console_messages

CLI-Optionen

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

• --firefox-path — absoluter Pfad zur Firefox-Binärdatei

• --headless — Ausführung ohne UI (FIREFOX_HEADLESS=true)

• --viewport 1280x720 — anfängliche Fenstergröße

• --profile-path — Verwendung eines bestimmten Firefox-Profils

• --firefox-arg — zusätzliche Firefox-Argumente (wiederholbar)

• --start-url — öffnet diese URL beim Start (START_URL)

• --accept-insecure-certs — ignoriert TLS-Fehler (ACCEPT_INSECURE_CERTS=true)

• --connect-existing — verbindet sich mit einem bereits laufenden Firefox, anstatt einen neuen zu starten (CONNECT_EXISTING=true)

• --marionette-port — Marionette-Port für den Modus "connect-existing", Standard 2828 (MARIONETTE_PORT)

• --pref name=value — setzt Firefox-Einstellungen beim Start via moz:firefoxOptions (wiederholbar)

• --enable-script — aktiviert das Tool evaluate_script, das beliebiges JavaScript im Seitenkontext ausführt (ENABLE_SCRIPT=true)

• --enable-privileged-context — aktiviert Tools für privilegierte Kontexte: Auflisten/Auswählen privilegierter Kontexte, Ausführen privilegierter Skripte, Abrufen/Setzen von Firefox-Einstellungen und Auflisten von Erweiterungen. Erfordert MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)

Hinweis zu --pref: Wenn Firefox in der Automatisierung läuft, wendet er RecommendedPreferences an, die das Browserverhalten für Tests modifizieren. Die Option --pref ermöglicht es, diese Standardwerte bei Bedarf zu überschreiben.

Verbindung zu einem bestehenden Firefox

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

# Start Firefox with Marionette enabled
firefox --marionette

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

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

BiDi-abhängige Funktionen (Konsolenereignisse, Netzwerkereignisse) sind im Modus "connect-existing" nicht verfügbar; alle anderen Funktionen funktionieren normal.

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

Tool-Übersicht

• Seiten: auflisten/neu/navigieren/auswählen/schließen

• Snapshot/UID: erstellen/auflösen/löschen

• Eingabe: klicken/hovern/ausfüllen/ziehen/hochladen/Formular ausfüllen

• Netzwerk: auflisten/abrufen (ID-basiert, 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 (Auflisten erfordert MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)

• Firefox-Verwaltung: get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs

• Dienstprogramme: Dialog akzeptieren/verwerfen, 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 dem Read-Tool von Claude Code 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

Testen

npm run test:run          # all tests once (unit + integration)
npm test                  # watch mode

Siehe docs/testing.md für vollständige Details zum Ausführen spezifischer Testsuiten, der E2E-Szenarioabdeckung und bekannter Probleme.

Fehlerbehebung

• Firefox nicht gefunden: Übergeben Sie --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) oder den korrekten Pfad auf Ihrem Betriebssystem.

• Erster Start ist langsam: Selenium richtet die BiDi-Sitzung ein; nachfolgende Starts sind schneller.

• Veraltete UIDs nach Navigation: Erstellen Sie einen neuen Snapshot (take_snapshot), bevor Sie UID-Tools verwenden.

• Windows 10: Fehler bei der Erkennung für MCP-Server 'firefox-devtools': MCP error -32000: Connection closed

  • Lösung 1 Aufruf mit cmd (Weitere Informationen unter https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310)

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

    Die entscheidende Änderung: Unter Windows erfordert das Ausführen eines Node.js-Pakets via npx oft das Präfix cmd /c, um korrekt aus einem anderen Prozess wie dem VSCode-Erweiterungshost ausgeführt zu werden. Daher wurde "command": "npx" durch "command": "cmd" ersetzt und der eigentliche npx-Befehl in das "args"-Array verschoben, vorangestellt mit "/c". Dieser Fix ermöglicht es Windows, den Befehl korrekt zu interpretieren und den Server zu starten.

  • Lösung 2 Anstatt einer weiteren Shell-Ebene können Sie den absoluten Pfad zu npx schreiben:

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

    Hinweis: Der obige Pfad ist ein Beispiel. Sie müssen ihn an den tatsächlichen Speicherort von npx auf Ihrem Computer anpassen. Abhängig von Ihrem Setup könnte die Dateiendung .cmd, .bat oder .exe statt .ps1 lauten. Stellen Sie außerdem sicher, dass Sie doppelte Backslashes (\\) als Pfadtrennzeichen verwenden, wie vom JSON-Format gefordert.

Versionierung

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

CI und Release

• GitHub Actions für CI, Release und npm-Veröffentlichung sind enthalten. Siehe docs/ci-and-release.md für Details und erforderliche Secrets.

Probleme und Mitwirken

Probleme werden auf Bugzilla unter product: Developer Infrastructure, component: AI for Development verfolgt.

• Neues Problem melden

• Meta-Bug (verfolgt alle firefox-devtools-mcp-Probleme)

Für Fragen und Diskussionen treten Sie dem #firefox-devtools-mcp Matrix-Raum bei.

Autor

Gewartet von Mozilla.