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)

Related MCP server: gecko-mcp

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 (ständige 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 — 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 — 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 Modus "connect-existing", Standard 2828 (MARIONETTE_PORT)

• --pref name=value — Firefox-Einstellung beim Start über moz:firefoxOptions festlegen (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: privilegierte Kontexte auflisten/auswählen, privilegierte Skripte ausführen, Firefox-Einstellungen abrufen/festlegen und Erweiterungen auflisten. 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 Standardeinstellungen bei Bedarf zu überschreiben.

Verbindung zu einem bestehenden Firefox

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 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 bei Websites, die durch Cloudflare, Akamai usw. geschützt sind, eine Bot-Erkennung auslösen kann. 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, ständige 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/vor, Viewport festlegen

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 stattdessen den Parameter saveTo, um Screenshots 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 Mit cmd /c umschließen (Details):

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

  • Lösung 2 Verwenden Sie den absoluten Pfad zu npx (passen Sie die Erweiterung – .cmd, .bat, .exe oder .ps1 – an Ihr Setup an):

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

Versionierung

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

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 Mitwirkung

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.