Serveur Model Context Protocol pour Firefox DevTools - permet aux assistants IA d'inspecter et de contrôler le navigateur Firefox via 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>
Serveur Model Context Protocol pour automatiser Firefox via WebDriver BiDi (via Selenium WebDriver). Fonctionne avec Claude Code, Claude Desktop, Cursor, Cline et d'autres clients MCP.
Dépôt : https://github.com/mozilla/firefox-devtools-mcp
> **Remarque** : Ce serveur MCP nécessite une installation locale de Firefox et ne peut pas fonctionner sur des services d'hébergement cloud comme glama.ai. Utilisez `npx @mozilla/firefox-devtools-mcp@latest` pour l'exécuter localement, ou utilisez Docker avec le Dockerfile fourni.
## Sécurité
Les serveurs MCP de navigateur comportent des risques inhérents. Quelques pratiques clés :
- **Utilisez un profil Firefox dédié.** N'exécutez jamais le serveur avec votre profil habituel — l'agent a accès à tout ce que le navigateur peut atteindre, y compris les cookies et les sessions enregistrées.
- **Soyez prudent quant aux sites que vous visitez.** Les pages peuvent renvoyer du contenu conçu pour manipuler l'agent (injection d'invites). Restez sur des sites que vous contrôlez ou auxquels vous faites confiance.
- **N'activez que les modules d'outils dont vous avez besoin.** Le préréglage `basic` par défaut inclut déjà `evaluate_script` ; `--tool-preset slim` le supprime. Les préréglages supérieurs comme `--tool-preset developer` (débogage, réseau, console, profileur) et `--tool-preset mozilla` (contexte privilégié) étendent davantage ce que l'agent peut faire.
Consultez [SECURITY.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/SECURITY.md) pour une analyse complète des risques et la manière de signaler des vulnérabilités.
## Prérequis
- Node.js ≥ 20.19.0
- Firefox 100+ installé (détection automatique, ou passez `--firefox-path`)
## Installation et utilisation avec Claude Code ou Codex (npx)
Recommandé : utilisez `npx` pour exécuter la dernière version publiée depuis npm.
### Option A — CLI
#### Claude Code
```bash
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest
# Headless + viewport via arguments
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720
# Ou via des variables d'environnement
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 via arguments
codex mcp add firefox-devtools -- \
npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720
# Ou via des variables d'environnement
codex mcp add firefox-devtools \
--env START_URL=https://example.com \
--env FIREFOX_HEADLESS=true \
-- npx @mozilla/firefox-devtools-mcp@latest
```
### Option B — Modifier le fichier de configuration
#### Claude Code
Ajoutez au mcp_settings.json de Claude Code :
```json
{
"mcpServers": {
"firefox-devtools": {
"command": "npx",
"args": ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
"env": {
"START_URL": "about:blank"
}
}
}
}
```
#### Codex
Ajoutez à ~/.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"
```
### Option C — Script d'assistance (build de développement local)
```bash
npm run setup
# Choisissez Claude Code ; le script enregistre le JSON au bon chemin
```
## Essayez avec MCP Inspector
```bash
npx @modelcontextprotocol/inspector npx @mozilla/firefox-devtools-mcp@latest --start-url https://example.com --headless
```
Appelez ensuite des outils comme :
- `list_pages`, `select_page`, `navigate_page`
- `take_snapshot` puis `click_by_uid` / `fill_by_uid`
- `list_network_requests` (capture toujours active), `get_network_request`
- `list_downloads` (capture toujours active), `set_download_behavior`
- `screenshot_page`, `list_console_messages`
## Options CLI
Vous pouvez passer des drapeaux ou des variables d'environnement (noms à droite) :
- `--firefox-path` — chemin absolu vers le binaire Firefox
- `--headless` — exécuter sans interface (`FIREFOX_HEADLESS=true`)
- `--viewport 1280x720` — taille initiale de la fenêtre
- `--profile-path` — utiliser un profil Firefox spécifique
- `--firefox-arg` — arguments Firefox supplémentaires (répétable)
- `--start-url` — ouvrir cette URL au démarrage (`START_URL`)
- `--accept-insecure-certs` — ignorer les erreurs TLS (`ACCEPT_INSECURE_CERTS=true`)
- `--connect-existing` — se connecter à une instance Firefox déjà en cours d'exécution au lieu d'en lancer une nouvelle (`CONNECT_EXISTING=true`)
- `--marionette-port` — port Marionette pour le mode connect-existing, par défaut 2828 (`MARIONETTE_PORT`)
- `--pref name=value` — définir une préférence Firefox au démarrage via `moz:firefoxOptions` (répétable)
- `--tool-preset` — sélectionner les modules d'outils à activer : `slim`, `basic` (par défaut), `developer`, `mozilla`, ou `all`. Voir [Modules d'outils et préréglages](#modules-doutils-et-préréglages). (`TOOL_PRESET`)
- `--tools` — liste explicite des modules d'outils à activer, remplaçant entièrement `--tool-preset` (par ex. `--tools pages network script`). Voir [Modules d'outils et préréglages](#modules-doutils-et-préréglages).
- `--enable-script` — _obsolète, utilisez `--tool-preset developer` ou `--tools ... script debugging`._ Sélectionne le préréglage d'outils `developer`. (`ENABLE_SCRIPT=true`)
- `--enable-privileged-context` — _obsolète, utilisez `--tool-preset mozilla` ou `--tools ... privileged prefs`._ Sélectionne le préréglage d'outils `mozilla`. Nécessite `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1` (`ENABLE_PRIVILEGED_CONTEXT=true`)
- `--android-device` — activer le mode Firefox pour Android ; la valeur est le numéro de série du périphérique ADB (par ex. `emulator-5554`). Exécutez `adb devices` pour lister les périphériques connectés. Omettez la valeur ou utilisez `auto` pour sélectionner automatiquement le seul périphérique connecté.
- `--android-wipe-app-data` — confirmer que le mode Android efface toutes les données de l'application cible. Requis avec `--android-device`. (`ANDROID_WIPE_APP_DATA=true`)
- `--android-package` — nom du paquet d'application Android, par défaut `org.mozilla.firefox`. Autres paquets : `org.mozilla.firefox_beta` pour Firefox Beta, `org.mozilla.fenix` pour Firefox Nightly, `org.mozilla.fenix.debug` pour Firefox Nightly Debug, `org.mozilla.geckoview_example` pour geckoview (`ANDROID_PACKAGE`)
- `--unrestricted-save-paths` — permettre au paramètre `saveTo` d'écrire n'importe où sur le disque au lieu des racines par défaut. Voir [Enregistrement de sorties volumineuses sur disque](#enregistrement-de-sorties-volumineuses-sur-disque) et la note de sécurité dans [SECURITY.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/SECURITY.md). (`UNRESTRICTED_SAVE_PATHS=true`)
- `--log-file` — écrire les journaux du serveur MCP dans un fichier au lieu de stderr. Utile pour déboguer des sessions avec des clients MCP qui masquent la sortie du serveur. Définissez `DEBUG=*` pour inclure également les journaux de débogage verbeux. Exemple : `--log-file /tmp/firefox-mcp.log`
### Modules d'outils et préréglages
Les outils sont regroupés en modules. Vous choisissez les modules à exposer soit avec un préréglage nommé
(`--tool-preset`) soit avec une liste explicite (`--tools`). Lorsque les deux sont fournis, `--tools` l'emporte et
le préréglage est ignoré.
Modules : `pages`, `snapshot`, `input`, `network`, `console`, `screenshot`, `downloads`,
`utilities`, `management`, `webextension`, `profiler`, `screencast`, `script`, `debugging`,
`prefs`, `privileged`.
Préréglages (chacun est un sur-ensemble du précédent) :
- `slim` — `pages`, `snapshot`, `input`, `screenshot`
- `basic` (par défaut) — `slim` plus `downloads`, `script`, `utilities`, `management`, `webextension`, `screencast`
- `developer` — `basic` plus `debugging`, `network`, `console`, `profiler`
- `mozilla` — `developer` plus `prefs`, `privileged`
- `all` — tous les modules
Notez que `basic`, le préréglage par défaut, inclut `script` et donc l'outil `evaluate_script`.
Consultez [SECURITY.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/SECURITY.md#tool-modules-and-presets) pour comprendre ce que cela implique pour la surface
d'attaque, et utilisez `--tool-preset slim` ou une liste `--tools` explicite pour le supprimer.
```bash
# Utiliser le préréglage developer (ajoute les outils réseau, console, débogage et profileur)
npx @mozilla/firefox-devtools-mcp --tool-preset developer
# Activer uniquement les modules nécessaires
npx @mozilla/firefox-devtools-mcp --tools pages network console
```
Les modules `prefs` et `privileged` nécessitent `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1` et ne sont disponibles que
dans la build interne de Mozilla. Le paquet public les ignore même s'ils sont demandés et
journalise un avertissement nommant les modules supprimés.
### Préférences utiles (`--pref`)
- remote.prefs.recommended=false. Lorsque Firefox s'exécute en automatisation, il applique [RecommendedPreferences](https://searchfox.org/firefox-main/source/remote/shared/RecommendedPreferences.sys.mjs) qui modifient le comportement du navigateur pour les tests. Définissez remote.prefs.recommended sur false pour les ignorer et avoir une configuration plus proche d'une instance Firefox normale.
- remote.log.level=Trace. Activez les journaux de protocole WebDriver verbeux dans Firefox. Le serveur MCP transmettra automatiquement le niveau de journalisation correspondant à geckodriver afin que les deux côtés journalisent au même niveau de verbosité.
- app.update.disabledForTesting=false. Permettez à Firefox de télécharger et d'appliquer automatiquement les mises à jour. Notez que les mises à jour peuvent interrompre votre session. Nécessite également de définir remote.prefs.recommended=false.
### Firefox pour Android
Utilisez `--android-device` pour automatiser Firefox s'exécutant sur un appareil Android. Nécessite `adb` dans votre PATH et geckodriver, qui est géré automatiquement.
> **Avertissement :** Le mode Android efface toutes les données de l'application cible avant chaque session.
> Onglets, historique, marque-pages, mots de passe, cookies et paramètres sont tous perdus. geckodriver exécute
> `adb shell pm clear <package>` lors de la création de la session et n'offre aucun moyen de l'ignorer,
> puis exécute la session sur son propre profil temporaire qui est supprimé ensuite.
> Pour cette raison, `--android-device` nécessite `--android-wipe-app-data`, et vous devriez
> installer une build dédiée à l'automatisation plutôt que d'automatiser le navigateur que vous utilisez.
> [Bug 2064088](https://bugzilla.mozilla.org/show_bug.cgi?id=2064088) suit l'ajout d'une
> option à geckodriver pour conserver les données d'application existantes.
```bash
# Lister les périphériques connectés
adb devices
# Lancer Firefox pour Android sur le seul périphérique connecté
npx @mozilla/firefox-devtools-mcp --android-device auto --android-wipe-app-data
# Cibler un périphérique spécifique
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-wipe-app-data
# Utiliser Firefox Nightly à la place
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix --android-wipe-app-data
```
Le transfert de port entre l'hôte et le périphérique est géré automatiquement par geckodriver.
### Se connecter à une instance Firefox existante
Utilisez `--connect-existing` pour automatiser votre session de navigation réelle, avec cookies, connexions et onglets ouverts intacts :
```bash
# Démarrer Firefox avec Marionette et l'agent distant (BiDi)
firefox --marionette --remote-debugging-port
# Exécuter le serveur MCP
npx @mozilla/firefox-devtools-mcp --connect-existing --marionette-port 2828
```
Les deux drapeaux sont requis car le MCP utilise à la fois WebDriver Classic (`--marionette`) et WebDriver BiDi (`--remote-debugging-port`). Si Firefox est démarré uniquement avec `--marionette`, le serveur MCP ne parvient pas à se connecter et vous demande de redémarrer Firefox avec les deux drapeaux.
> **Avertissement :** Ne laissez pas Marionette activé pendant la navigation normale. Il définit
> `navigator.webdriver = true` et modifie d'autres signaux d'empreinte du navigateur,
> ce qui peut déclencher la détection de robots sur les sites protégés par Cloudflare, Akamai, etc.
> N'activez Marionette que lorsque vous avez besoin de l'automatisation MCP, puis redémarrez Firefox
> normalement ensuite.
## Aperçu des outils
Consultez [docs/tools.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/docs/tools.md) pour la liste complète des outils par module, avec
descriptions et paramètres (générés à partir de la source).
- Pages : list/new/navigate/select/close/get_page_text (get_page_text prend en charge `saveTo` optionnel)
- Snapshot/UID : take/resolve/clear (take prend en charge `saveTo` optionnel)
- Input : click/hover/fill/drag/upload/form fill/press_key/type_text
- Network : list/get (ID d'abord, filtres, capture toujours active ; les deux prennent en charge `saveTo` optionnel)
- Downloads : list_downloads/clear_downloads (capture toujours active), set_download_behavior (allow/deny/default)
- Console : list/clear (list prend en charge `saveTo` optionnel)
- Screenshot : page/by uid (avec `saveTo` optionnel pour les environnements CLI)
- Script : evaluate_script (`sandbox` optionnel pour un domaine isolé ; `saveTo` optionnel pour les résultats volumineux)
- Contexte privilégié : list/select des contextes privilégiés ("chrome"), evaluate_privileged_script (nécessite `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`)
- WebExtension : install_extension, uninstall_extension, list_extensions (list nécessite `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`)
- Gestion Firefox : get_firefox_info, get_firefox_output, restart_firefox
- Préférences Firefox : get_firefox_prefs, set_firefox_prefs (nécessite `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`)
- Profileur : profiler_is_active, profiler_start (préréglage ou configuration explicite), profiler_stop (enregistre le profil dans le répertoire des téléchargements)
- Screencast : screencast_start (enregistre la zone d'affichage de la page dans un fichier vidéo dans le répertoire des téléchargements), screencast_stop (nécessite Firefox 154+)
- Utilitaires : accept/dismiss dialog, history back/forward, set viewport
### Enregistrement de sorties volumineuses sur disque
Les sorties d'outils volumineuses peuvent consommer un contexte significatif dans les clients CLI comme Claude Code. Les
outils `screenshot_page`, `screenshot_by_uid`, `take_snapshot`, `list_console_messages`,
`list_network_requests`, `get_network_request`, `get_page_text`,
`evaluate_script`, et
`evaluate_privileged_script` acceptent un paramètre optionnel `saveTo` qui écrit le
résultat dans un fichier au lieu de le renvoyer en ligne. `saveTo` prend l'une des trois formes suivantes :
- un chemin de fichier (relatif au répertoire de travail courant, ou absolu dans `~/.firefox-devtools-mcp` ; les répertoires parents sont créés)
- un répertoire existant (un fichier horodaté est généré à l'intérieur)
- `true` (un fichier horodaté est généré sous `~/.firefox-devtools-mcp/output/`)
La réponse renvoie le chemin et la taille en octets. Le fichier enregistré contient toujours les données complètes et
non tronquées : les limites de taille en ligne (plafonds de messages console, troncature des en-têtes réseau,
plafonds de lignes de snapshot) ne s'y appliquent jamais.
Les outils produisant du texte (tout sauf les captures d'écran) acceptent également `preview`, un nombre
de caractères de la sortie enregistrée à renvoyer en ligne comme court extrait. Les captures d'écran n'ont pas
d'aperçu.
```
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 })
```
Par défaut, les chemins d'enregistrement sont restreints : les chemins relatifs sont résolus par rapport au répertoire
de travail courant, et les chemins absolus ne sont autorisés que dans `~/.firefox-devtools-mcp`. Les chemins qui
sortent de ces emplacements sont rejetés. Démarrez le serveur avec `--unrestricted-save-paths` pour
écrire à des emplacements arbitraires, y compris des chemins absolus en dehors de ce répertoire.
Les fichiers enregistrés peuvent ensuite être consultés par exemple avec l'outil `Read` de Claude Code sans impacter la taille du contexte.
## Développement local
```bash
npm install
npm run build
# Exécuter avec Inspector contre la build locale
npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720
# Ou exécuter en développement avec rechargement à chaud
npm run inspector:dev
```
Consultez [CONTRIBUTING.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/CONTRIBUTING.md) pour plus de détails sur le développement local, les tests et l'IC.
## Dépannage
- Firefox introuvable : passez `--firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox"` (macOS) ou le chemin correct sur votre système d'exploitation.
- Première exécution lente : Selenium configure la session BiDi ; les exécutions suivantes sont plus rapides.
- UID obsolètes : un UID reste valide jusqu'à ce que son élément soit supprimé ou que la page navigue ; prenez un nouveau snapshot (`take_snapshot`) lorsqu'un outil UID signale qu'il est absent.
- Windows 10 : Erreur lors de la découverte du serveur MCP 'firefox-devtools' : MCP error -32000 : Connection closed
- **Solution 1** Enveloppez avec `cmd /c` ([détails](https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310)) :
```json
"mcpServers": {
"firefox-devtools": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@mozilla/firefox-devtools-mcp@latest"]
}
}
```
- **Solution 2** Utilisez le chemin absolu vers `npx` (ajustez l'extension — `.cmd`, `.bat`, `.exe`, ou `.ps1` — pour correspondre à votre configuration) :
```json
"mcpServers": {
"firefox-devtools": {
"command": "C:\\nvm4w\\nodejs\\npx.ps1",
"args": ["-y", "@mozilla/firefox-devtools-mcp@latest"]
}
}
```
## Gestion des versions
- API pré‑1.0 : les versions commencent à `0.x`. Utilisez `@latest` avec npx pour la version la plus récente.
## Contribution
Consultez [CONTRIBUTING.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/CONTRIBUTING.md) pour savoir comment signaler des problèmes, exécuter des tests et travailler sur le projet localement.
## Auteur
Maintenu par [Mozilla](https://www.mozilla.org).
## Licence
Sous licence [MIT](https://github.com/mozilla/firefox-devtools-mcp/blob/main/LICENSE-MIT) ou [Apache 2.0](https://github.com/mozilla/firefox-devtools-mcp/blob/main/LICENSE-APACHE) à votre choix.