Firefox DevTools MCP

Server Model Context Protocol per automatizzare Firefox tramite WebDriver BiDi (attraverso Selenium WebDriver). Funziona con Claude Code, Claude Desktop, Cursor, Cline e altri client MCP.

Repository: https://github.com/mozilla/firefox-devtools-mcp

Nota: Questo server MCP richiede un'installazione locale di Firefox e non può essere eseguito su servizi di hosting cloud come glama.ai. Usa npx @mozilla/firefox-devtools-mcp@latest per eseguirlo localmente, oppure usa Docker con il Dockerfile fornito.

Sicurezza

I server MCP per browser comportano rischi intrinseci. Alcune pratiche chiave:

• Usa un profilo Firefox dedicato. Non eseguire mai il server sul tuo profilo abituale — l'agente ha accesso a tutto ciò che il browser può raggiungere, inclusi cookie e sessioni salvate.
• Presta attenzione ai siti che visiti. Le pagine possono restituire contenuti progettati per manipolare l'agente (prompt injection). Attieniti a siti che controlli o di cui ti fidi.
• Abilita solo i moduli di strumenti di cui hai bisogno. Il preset predefinito basic include già evaluate_script; --tool-preset slim lo rimuove. I preset superiori come --tool-preset developer (debugging, network, console, profiler) e --tool-preset mozilla (contesto privilegiato) espandono ulteriormente ciò che l'agente può fare.

Consulta SECURITY.md per un'analisi completa dei rischi e su come segnalare vulnerabilità.

Requisiti

• Node.js ≥ 20.19.0
• Firefox 100+ installato (rilevato automaticamente, oppure passa --firefox-path)

Installazione e utilizzo con Claude Code o Codex (npx)

Consigliato: usa npx per eseguire l'ultima versione pubblicata su npm.

Opzione A — CLI

Claude Code

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

# Headless + viewport tramite argomenti
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Oppure tramite variabili d'ambiente
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 tramite argomenti
codex mcp add firefox-devtools -- \
  npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Oppure tramite variabili d'ambiente
codex mcp add firefox-devtools \
  --env START_URL=https://example.com \
  --env FIREFOX_HEADLESS=true \
  -- npx @mozilla/firefox-devtools-mcp@latest

Opzione B — Modifica il file di configurazione

Claude Code

Aggiungi a mcp_settings.json di Claude Code:

{
  "mcpServers": {
    "firefox-devtools": {
      "command": "npx",
      "args": ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "env": {
        "START_URL": "about:blank"
      }
    }
  }
}

Codex

Aggiungi a ~/.codex/config.toml:

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

Opzione C — Script di supporto (build di sviluppo locale)

npm run setup
# Scegli Claude Code; lo script salva il JSON nel percorso corretto

Provalo con MCP Inspector

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

Poi chiama strumenti come:

• list_pages, select_page, navigate_page
• take_snapshot poi click_by_uid / fill_by_uid
• list_network_requests (cattura sempre attiva), get_network_request
• list_downloads (cattura sempre attiva), set_download_behavior
• screenshot_page, list_console_messages

Opzioni CLI

Puoi passare flag o variabili d'ambiente (nomi a destra):

• --firefox-path — percorso assoluto del binario di Firefox
• --headless — esegui senza interfaccia (FIREFOX_HEADLESS=true)
• --viewport 1280x720 — dimensione iniziale della finestra
• --profile-path — usa un profilo Firefox specifico
• --firefox-arg — argomenti Firefox aggiuntivi (ripetibile)
• --start-url — apri questo URL all'avvio (START_URL)
• --accept-insecure-certs — ignora gli errori TLS (ACCEPT_INSECURE_CERTS=true)
• --connect-existing — collegati a un Firefox già in esecuzione invece di avviarne uno nuovo (CONNECT_EXISTING=true)
• --marionette-port — porta Marionette per la modalità connect-existing, predefinita 2828 (MARIONETTE_PORT)
• --pref name=value — imposta una preferenza Firefox all'avvio tramite moz:firefoxOptions (ripetibile)
• --tool-preset — seleziona quali moduli di strumenti abilitare: slim, basic (predefinito), developer, mozilla o all. Consulta Moduli di strumenti e preset. (TOOL_PRESET)
• --tools — elenco esplicito di moduli di strumenti da abilitare, che sovrascrive completamente --tool-preset (es. --tools pages network script). Consulta Moduli di strumenti e preset.
• --enable-script — deprecato, usa --tool-preset developer o --tools ... script debugging. Seleziona il preset di strumenti developer. (ENABLE_SCRIPT=true)
• --enable-privileged-context — deprecato, usa --tool-preset mozilla o --tools ... privileged prefs. Seleziona il preset di strumenti mozilla. Richiede MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device — abilita la modalità Firefox per Android; il valore è il seriale del dispositivo ADB (es. emulator-5554). Esegui adb devices per elencare i dispositivi collegati. Ometti il valore o usa auto per selezionare automaticamente l'unico dispositivo collegato.
• --android-wipe-app-data — conferma che la modalità Android cancella tutti i dati dell'app di destinazione. Obbligatorio insieme a --android-device. (ANDROID_WIPE_APP_DATA=true)
• --android-package — nome del pacchetto dell'app Android, predefinito org.mozilla.firefox. Altri pacchetti: org.mozilla.firefox_beta per Firefox Beta, org.mozilla.fenix per Firefox Nightly, org.mozilla.fenix.debug per Firefox Nightly Debug, org.mozilla.geckoview_example per geckoview (ANDROID_PACKAGE)
• --unrestricted-save-paths — consenti al parametro saveTo di scrivere ovunque sul disco invece che nelle radici predefinite. Consulta Salvataggio di output voluminosi su disco e la nota sulla sicurezza in SECURITY.md. (UNRESTRICTED_SAVE_PATHS=true)
• --log-file — scrivi i log del server MCP su un file invece che su stderr. Utile per sessioni di debug con client MCP che nascondono l'output del server. Imposta DEBUG=* per includere anche log di debug dettagliati. Esempio: --log-file /tmp/firefox-mcp.log

Moduli di strumenti e preset

Gli strumenti sono raggruppati in moduli. Puoi scegliere quali moduli esporre con un preset nominato (--tool-preset) o con un elenco esplicito (--tools). Quando vengono forniti entrambi, --tools ha la precedenza e il preset viene ignorato.

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

Preset (ciascuno è un superset del precedente):

• slim — pages, snapshot, input, screenshot
• basic (predefinito) — slim più downloads, script, utilities, management, webextension, screencast
• developer — basic più debugging, network, console, profiler
• mozilla — developer più prefs, privileged
• all — ogni modulo

Nota che basic, il predefinito, include script e quindi lo strumento evaluate_script. Consulta SECURITY.md per capire cosa significa per la superficie d'attacco e usa --tool-preset slim o un elenco --tools esplicito per rimuoverlo.

# Usa il preset developer (aggiunge strumenti network, console, debugging e profiler)
npx @mozilla/firefox-devtools-mcp --tool-preset developer

# Abilita solo i moduli di cui hai bisogno
npx @mozilla/firefox-devtools-mcp --tools pages network console

I moduli prefs e privileged richiedono MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 e sono disponibili solo nella build interna di Mozilla. Il pacchetto pubblico li salta anche se richiesti e registra un avviso che nomina i moduli scartati.

Preferenze utili (--pref)

• remote.prefs.recommended=false. Quando Firefox viene eseguito in automazione, applica RecommendedPreferences che modificano il comportamento del browser per i test. Imposta remote.prefs.recommended su false per saltarle e avere una configurazione più vicina a un'istanza Firefox normale.
• remote.log.level=Trace. Abilita log dettagliati del protocollo WebDriver in Firefox. Il server MCP passerà automaticamente il livello di log corrispondente a geckodriver così entrambi i lati registrano con la stessa verbosità.
• app.update.disabledForTesting=false. Consenti a Firefox di scaricare e applicare automaticamente gli aggiornamenti. Nota che gli aggiornamenti potrebbero interrompere la sessione. Richiede anche l'impostazione di remote.prefs.recommended=false.

Firefox per Android

Usa --android-device per automatizzare Firefox in esecuzione su un dispositivo Android. Richiede adb nel tuo PATH e geckodriver, che viene gestito automaticamente.

Avviso: La modalità Android cancella tutti i dati dell'app di destinazione prima di ogni sessione. Schede, cronologia, segnalibri, password, cookie e impostazioni vengono tutti persi. geckodriver esegue adb shell pm clear <package> quando crea la sessione e non offre alcun modo per saltarlo, poi esegue la sessione sul proprio profilo temporaneo che viene eliminato successivamente. Per questo motivo, --android-device richiede --android-wipe-app-data e dovresti installare una build dedicata all'automazione piuttosto che automatizzare il browser che usi. Bug 2064088 tiene traccia dell'aggiunta di un'opzione a geckodriver per mantenere i dati esistenti dell'app.

# Elenca i dispositivi collegati
adb devices

# Avvia Firefox per Android sull'unico dispositivo collegato
npx @mozilla/firefox-devtools-mcp --android-device auto --android-wipe-app-data

# Punta a un dispositivo specifico
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-wipe-app-data

# Usa Firefox Nightly invece
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix --android-wipe-app-data

L'inoltro delle porte tra host e dispositivo è gestito automaticamente da geckodriver.

Collegamento a Firefox esistente

Usa --connect-existing per automatizzare la tua sessione di navigazione reale, con cookie, accessi e schede aperte intatti:

# Avvia Firefox con Marionette e Remote Agent (BiDi)
firefox --marionette --remote-debugging-port

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

Entrambi i flag sono obbligatori perché l'MCP usa sia WebDriver Classic (--marionette) che WebDriver BiDi (--remote-debugging-port). Se Firefox viene avviato solo con --marionette, il server MCP non riesce a connettersi e ti chiede di riavviare Firefox con entrambi i flag.

Avviso: Non lasciare Marionette abilitato durante la navigazione normale. Imposta navigator.webdriver = true e modifica altri segnali di fingerprint del browser, che possono attivare il rilevamento bot su siti protetti da Cloudflare, Akamai, ecc. Abilita Marionette solo quando hai bisogno dell'automazione MCP, poi riavvia Firefox normalmente.

Panoramica degli strumenti

Consulta docs/tools.md per l'elenco completo degli strumenti per modulo, con descrizioni e parametri (generati dal sorgente).

• Pages: list/new/navigate/select/close/get_page_text (get_page_text supporta saveTo opzionale)
• Snapshot/UID: take/resolve/clear (take supporta saveTo opzionale)
• Input: click/hover/fill/drag/upload/form fill/press_key/type_text
• Network: list/get (ID‑first, filtri, cattura sempre attiva; entrambi supportano saveTo opzionale)
• Downloads: list_downloads/clear_downloads (cattura sempre attiva), set_download_behavior (allow/deny/default)
• Console: list/clear (list supporta saveTo opzionale)
• Screenshot: page/by uid (con saveTo opzionale per ambienti CLI)
• Script: evaluate_script (sandbox opzionale per un realm isolato; saveTo opzionale per risultati voluminosi)
• Contesto privilegiato: list/select contesti privilegiati ("chrome"), evaluate_privileged_script (richiede MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• WebExtension: install_extension, uninstall_extension, list_extensions (list richiede MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Gestione Firefox: get_firefox_info, get_firefox_output, restart_firefox
• Preferenze Firefox: get_firefox_prefs, set_firefox_prefs (richiede MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Profiler: profiler_is_active, profiler_start (configurazione preset o esplicita), profiler_stop (salva il profilo nella directory dei download)
• Screencast: screencast_start (registra il viewport della pagina in un file video nella directory dei download), screencast_stop (richiede Firefox 154+)
• Utilities: accept/dismiss dialog, history back/forward, set viewport

Salvataggio di output voluminosi su disco

L'output di strumenti di grandi dimensioni può consumare contesto significativo nei client CLI come Claude Code. Gli strumenti screenshot_page, screenshot_by_uid, take_snapshot, list_console_messages, list_network_requests, get_network_request, get_page_text, evaluate_script e evaluate_privileged_script accettano un parametro opzionale saveTo che scrive il risultato su un file invece di restituirlo inline. saveTo accetta una di tre forme:

• un percorso file (relativo alla directory di lavoro corrente, o assoluto all'interno di ~/.firefox-devtools-mcp; le directory padre vengono create)
• una directory esistente (un file con timestamp viene generato al suo interno)
• true (un file con timestamp viene generato sotto ~/.firefox-devtools-mcp/output/)

La risposta restituisce il percorso e la dimensione in byte. Il file salvato contiene sempre i dati completi e non troncati: le salvaguardie sulla dimensione inline (limiti dei messaggi console, troncamento degli header di rete, limiti delle righe dello snapshot) non si applicano mai ad esso.

Gli strumenti che producono testo (tutto tranne gli screenshot) accettano anche preview, un numero di caratteri dell'output salvato da restituire inline come breve estratto. Gli screenshot non hanno anteprima.

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

Per impostazione predefinita, i percorsi di salvataggio sono limitati: i percorsi relativi vengono risolti rispetto alla directory di lavoro corrente e i percorsi assoluti sono consentiti solo all'interno di ~/.firefox-devtools-mcp. I percorsi che escono da queste posizioni vengono rifiutati. Avvia il server con --unrestricted-save-paths per scrivere in posizioni arbitrarie, inclusi percorsi assoluti al di fuori di quella directory.

I file salvati possono poi essere visualizzati ad esempio con lo strumento Read di Claude Code senza influire sulla dimensione del contesto.

Sviluppo locale

npm install
npm run build

# Esegui con Inspector contro la build locale
npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720

# Oppure esegui in dev con hot reload
npm run inspector:dev

Consulta CONTRIBUTING.md per maggiori dettagli sullo sviluppo locale, i test e la CI.

Risoluzione dei problemi

• Firefox non trovato: passa --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) o il percorso corretto sul tuo sistema operativo.
• Il primo avvio è lento: Selenium configura la sessione BiDi; le esecuzioni successive sono più veloci.
• UID obsoleti: un UID rimane valido finché il suo elemento non viene rimosso o la pagina naviga; fai uno snapshot fresco (take_snapshot) quando uno strumento UID segnala che non esiste più.
• Windows 10: Errore durante il rilevamento per il server MCP 'firefox-devtools': MCP error -32000: Connection closed

  • Soluzione 1 Avvolgi con cmd /c (dettagli):

    root@kitploit:~

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

  • Soluzione 2 Usa il percorso assoluto di npx (regola l'estensione — .cmd, .bat, .exe o .ps1 — in base alla tua configurazione):

    root@kitploit:~

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

Versioning

• API pre‑1.0: le versioni iniziano da 0.x. Usa @latest con npx per la release più recente.

Contributi

Consulta CONTRIBUTING.md per sapere come segnalare problemi, eseguire test e lavorare sul progetto localmente.

Autore

Mantenuto da Mozilla.

Licenza

Concesso in licenza con MIT o Apache 2.0 a tua scelta.