Server Model Context Protocol per Firefox DevTools - consente agli assistenti AI di ispezionare e controllare il browser Firefox tramite WebDriver BiDi
# Firefox DevTools MCP
[](https://www.npmjs.com/package/@mozilla/firefox-devtools-mcp)
[](https://github.com/mozilla/firefox-devtools-mcp/actions/workflows/ci.yml)
[](https://codecov.io/gh/mozilla/firefox-devtools-mcp)
[](LICENSE-MIT) [](LICENSE-APACHE)
<a href="https://glama.ai/mcp/servers/@mozilla/firefox-devtools-mcp"><img src="https://assets.kitploit.com/production/public/readmes/8655/a78a7d97ae218a4638aa3f14a824feef8d0e205b36490113ed8fa15dac83148a.png" height="223" alt="Glama"></a>
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](https://github.com/mozilla/firefox-devtools-mcp/blob/main/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
```bash
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
```bash
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:
```json
{
"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:
```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)
```bash
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 (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](#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](#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](#salvataggio-di-output-voluminosi-su-disco) e la nota sulla sicurezza in [SECURITY.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/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](https://github.com/mozilla/firefox-devtools-mcp/blob/main/SECURITY.md#tool-modules-and-presets) per capire cosa significa per la
superficie d'attacco e usa `--tool-preset slim` o un elenco `--tools` esplicito per rimuoverlo.
```bash
# 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](https://searchfox.org/firefox-main/source/remote/shared/RecommendedPreferences.sys.mjs) 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](https://bugzilla.mozilla.org/show_bug.cgi?id=2064088) tiene traccia dell'aggiunta di
> un'opzione a geckodriver per mantenere i dati esistenti dell'app.
```bash
# 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:
```bash
# 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](https://github.com/mozilla/firefox-devtools-mcp/blob/main/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
```bash
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](https://github.com/mozilla/firefox-devtools-mcp/blob/main/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](https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310)):
```json
"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):
```json
"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](https://github.com/mozilla/firefox-devtools-mcp/blob/main/CONTRIBUTING.md) per sapere come segnalare problemi, eseguire test e lavorare sul progetto localmente.
## Autore
Mantenuto da [Mozilla](https://www.mozilla.org).
## Licenza
Concesso in licenza con [MIT](https://github.com/mozilla/firefox-devtools-mcp/blob/main/LICENSE-MIT) o [Apache 2.0](https://github.com/mozilla/firefox-devtools-mcp/blob/main/LICENSE-APACHE) a tua scelta.