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 del browser Firefox e non può essere eseguito su servizi di cloud hosting come glama.ai. Usa npx @mozilla/firefox-devtools-mcp@latest per eseguire localmente, oppure usa Docker con il Dockerfile fornito.

Sicurezza

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

Usa un profilo Firefox dedicato. Non eseguire mai il server con il tuo profilo principale: l'agente ha accesso a tutto ciò che il browser può raggiungere, inclusi cookie e sessioni salvate.
Fai attenzione ai siti che visiti. Le pagine possono restituire contenuti progettati per manipolare l'agente (iniezione di prompt). Attieniti a siti che controlli o di cui ti fidi.
Abilita solo i moduli di strumenti di cui hai bisogno. Preset più elevati come --tool-preset developer (script, debug) e --tool-preset mozilla (contesto privilegiato) espandono significativamente ciò che l'agente può fare.

Vedi SECURITY.md per una panoramica completa dei rischi e come segnalare vulnerabilità.

Requisiti

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

Installazione e utilizzo con Claude Code (npx)

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

Opzione A — Claude Code CLI

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

Passa le opzioni come argomenti o variabili d'ambiente. Esempi:

# 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

Opzione B — Modifica il JSON delle impostazioni di Claude Code

Aggiungi al file di configurazione di Claude Code:

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

Opzione C — Script helper (build di sviluppo locale)

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

## Provalo con MCP Inspector

```bash
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 (i nomi a destra):

--firefox-path — percorso assoluto al binario di Firefox
--headless — esegui senza interfaccia utente (FIREFOX_HEADLESS=true)
--viewport 1280x720 — dimensione iniziale della finestra
--profile-path — usa un profilo Firefox specifico
--firefox-arg — argomenti extra di Firefox (ripetibile)
--start-url — apri questo URL all'avvio (START_URL)
--accept-insecure-certs — ignora errori TLS (ACCEPT_INSECURE_CERTS=true)
--connect-existing — collega a un Firefox già in esecuzione invece di avviarne uno nuovo (CONNECT_EXISTING=true)
--marionette-port — porta Marionette per la modalità connect-existing, default 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 (default), developer, mozilla, o all. Vedi Moduli e preset degli strumenti. (TOOL_PRESET)
--tools — elenco esplicito di moduli di strumenti da abilitare, sovrascrive completamente --tool-preset (es. --tools pages network script). Vedi Moduli e preset degli strumenti.
--enable-script — deprecato, usa --tool-preset developer o --tools ... script debugging. Seleziona il preset developer. (ENABLE_SCRIPT=true)
--enable-privileged-context — deprecato, usa --tool-preset mozilla o --tools ... privileged prefs. Seleziona il preset 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 connessi. Ometti il valore o usa auto per selezionare automaticamente l'unico dispositivo connesso.
--android-package — nome del pacchetto dell'app Android, default 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)
--log-file — scrive i log del server MCP su un file invece di 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 e preset degli strumenti

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

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

Preset (ciascuno è un superset del precedente):

slim — pages, snapshot, input, network, console
basic (default) — slim più screenshot, utilities, management, webextension, profiler, screencast
developer — basic più script, debugging
mozilla — developer più prefs, privileged
all — tutti i moduli

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

# Abilita solo i moduli necessari
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 silenziosamente anche se richiesti.

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ù simile a un'istanza Firefox normale.
remote.log.level=Trace. Abilita i log dettagliati del protocollo WebDriver in Firefox. Il server MCP passerà automaticamente il livello di log corrispondente a geckodriver in modo che entrambi i lati loggano 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 PATH e geckodriver, che viene gestito automaticamente.

# Elenca i dispositivi connessi
adb devices

# Avvia Firefox per Android sul singolo dispositivo connesso
npx @mozilla/firefox-devtools-mcp --android-device auto

# Punta a un dispositivo specifico
npx @mozilla/firefox-devtools-mcp --android-device <seriale>

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

Il port forwarding 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, login e schede aperte intatte:

# Avvia Firefox con Marionette e l'Agente Remoto (BiDi)
firefox --marionette --remote-debugging-port

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

Entrambi i flag sono necessari perché l'MCP utilizza 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.

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

Panoramica degli strumenti

Pages: list/new/navigate/select/close
Snapshot/UID: take/resolve/clear (take supporta saveTo opzionale)
Input: click/hover/fill/drag/upload/form fill
Network: list/get (ID-first, filtri, cattura sempre attiva)
Downloads: list_downloads/clear_downloads (cattura sempre attiva), set_download_behavior (allow/deny/default)
Console: list/clear
Screenshot: page/by uid (con saveTo opzionale per ambienti CLI)
Script: evaluate_script (con 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, set_firefox_prefs, get_firefox_prefs
Profiler: profiler_is_active, profiler_start (preset o configurazione 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

Salvare output voluminosi su disco

L'output di grandi strumenti può consumare contesto significativo in client CLI come Claude Code. Gli strumenti screenshot_page, screenshot_by_uid, take_snapshot, list_console_messages, list_network_requests, get_network_request, evaluate_script e evaluate_privileged_script accettano un parametro opzionale saveTo che scrive il risultato su un file invece di restituirlo inline. saveTo assume 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 (viene generato un file con timestamp al suo interno)
true (viene generato un file con timestamp 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 di dimensione inline (limiti di messaggi console, troncamento header di rete, limiti di righe snapshot) non si applicano mai ad esso.

Gli strumenti che producono testo (tutti 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 ristretti: 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 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 sviluppo con ricarica a caldo
npm run inspector:dev

Vedi CONTRIBUTING.md per maggiori dettagli sullo sviluppo locale, test e 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.
Prima esecuzione lenta: Selenium configura la sessione BiDi; le esecuzioni successive sono più veloci.
UID obsoleti dopo la navigazione: scatta una nuova istantanea (take_snapshot) prima di usare gli strumenti UID.
Windows 10: Errore durante il rilevamento del server MCP 'firefox-devtools': MCP error -32000: Connessione chiusa
- Soluzione 1 Avvolgi con cmd /c (dettagli):
```
"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):
```
"mcpServers": {
  "firefox-devtools": {
    "command": "C:\\nvm4w\\nodejs\\npx.ps1",
    "args": ["-y", "@mozilla/firefox-devtools-mcp@latest"]
  }
}
```

Versioning

API pre-1.0: le versioni iniziano con 0.x. Usa @latest con npx per l'ultima release.

Contributi

Vedi CONTRIBUTING.md per come segnalare problemi, eseguire test e lavorare al progetto localmente.

Autore

Mantenuto da Mozilla.

Licenza

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

firefox-devtools-mcp v0.10.0

Categorie