Firefox DevTools MCP

Serveur du Model Context Protocol pour automatiser Firefox via WebDriver BiDi (à travers 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 être exécuté sur des services d'hébergement cloud comme glama.ai. Utilisez npx @mozilla/firefox-devtools-mcp@latest pour l'exécuter en local, ou utilisez Docker avec le Dockerfile fourni.

Sécurité

Les serveurs MCP pour navigateur comportent des risques inhérents. Quelques bonnes pratiques clés :

Utilisez un profil Firefox dédié. Ne lancez 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'invite). Restez sur des sites que vous contrôlez ou auxquels vous faites confiance.
Activez uniquement les modules d'outils dont vous avez besoin. Les préréglages supérieurs comme --tool-preset developer (script, debugging) et --tool-preset mozilla (contexte privilégié) élargissent considérablement ce que l'agent peut faire.

Consultez SECURITY.md pour le détail complet des risques et la procédure de signalement des vulnérabilités.

Exigences

Node.js ≥ 20.19.0
Firefox 100+ installé (détection automatique, ou passez --firefox-path)

Installer et utiliser avec Claude Code (npx)

Recommandé : utilisez npx pour toujours exécuter la dernière version publiée sur npm.

Option A — CLI Claude Code

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

Passez les options soit comme arguments, soit comme variables d'environnement. Exemples :

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

# Or via environment variables
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest \
  --env START_URL=https://example.com \
  --env FIREFOX_HEADLESS=true

Option B — Modifier le JSON des paramètres de Claude Code

Ajoutez à votre fichier de configuration 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"
      }
    }
  }
}

Option C — Script d'aide (build de développement local)

npm run setup
# Choose Claude Code; the script saves JSON to the right path

Essayez-le avec MCP Inspector

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 options 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 — s'attacher à une instance Firefox déjà en cours au lieu d'en lancer une nouvelle (CONNECT_EXISTING=true)
--marionette-port — port Marionette pour le mode connect-existing, 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 (défaut), developer, mozilla ou all. Voir Modules d'outils 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.
--enable-script — déprécié, utilisez --tool-preset developer ou --tools ... script debugging. Sélectionne le préréglage d'outils developer. (ENABLE_SCRIPT=true)
--enable-privileged-context — déprécié, 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 l'unique périphérique connecté.
--android-package — nom du paquet de l'application Android, 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)
--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 aussi 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, 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, network, console
basic (défaut) — slim plus screenshot, utilities, management, webextension, profiler, screencast
developer — basic plus script, debugging
mozilla — developer plus prefs, privileged
all — tous les modules

# Use the developer preset (adds script and debugging tools)
npx @mozilla/firefox-devtools-mcp --tool-preset developer

# Enable only the modules you need
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 silencieusement même s'ils sont demandés.

Préférences utiles (`--pref`)

remote.prefs.recommended=false. Lorsque Firefox s'exécute en automatisation, il applique RecommendedPreferences qui modifient le comportement du navigateur pour les tests. Définissez remote.prefs.recommended sur false pour les ignorer et obtenir une configuration plus proche d'une instance Firefox normale.
remote.log.level=Trace. Activez les journaux verbeux du protocole WebDriver 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 exécuté sur un appareil Android. Nécessite adb dans votre PATH et geckodriver, qui est géré automatiquement.

# List connected devices
adb devices

# Launch Firefox for Android on the single connected device
npx @mozilla/firefox-devtools-mcp --android-device auto

# Target a specific device
npx @mozilla/firefox-devtools-mcp --android-device <serial>

# Use Firefox Nightly instead
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix

La redirection de ports entre l'hôte et l'appareil est gérée automatiquement par geckodriver.

Se connecter à une instance Firefox existante

Utilisez --connect-existing pour automatiser votre véritable session de navigation, avec cookies, identifiants de connexion et onglets ouverts intacts :

# Start Firefox with Marionette and the Remote Agent (BiDi)
firefox --marionette --remote-debugging-port

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

Les deux options sont nécessaires 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 options.

Avertissement : Ne laissez pas Marionette activé pendant une 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

Pages : lister/créer/naviguer/sélectionner/fermer
Instantané/UID : prendre/résoudre/effacer (prendre accepte saveTo optionnel)
Saisie : cliquer/survoler/remplir/glisser/téléverser/remplissage de formulaire <<<<<<< HEAD
Réseau : lister/obtenir (ID d'abord, filtres, capture toujours active ; les deux acceptent saveTo optionnel)
Console : lister/effacer (la liste accepte saveTo optionnel) =======
Réseau : lister/obtenir (ID d'abord, filtres, capture toujours active)
Téléchargements : list_downloads/clear_downloads (capture toujours active), set_download_behavior (allow/deny/default)
Console : lister/effacer

6873767 (Bug 2055949 - [firefox-devtools-mcp] expose download events to firefox devtools mcp)

Capture d'écran : page/par uid (avec saveTo optionnel pour les environnements CLI)
Script : evaluate_script (avec saveTo optionnel pour les résultats volumineux)
Contexte privilégié : lister/sélectionner les contextes privilégiés ("chrome"), evaluate_privileged_script (nécessite MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
WebExtension : install_extension, uninstall_extension, list_extensions (la liste nécessite MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
Gestion de Firefox : get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs
Profiler : profiler_is_active, profiler_start (préréglage ou configuration explicite), profiler_stop (enregistre le profil dans le dossier des téléchargements)
Screencast : screencast_start (enregistre la zone d'affichage de la page dans un fichier vidéo dans le dossier des téléchargements), screencast_stop (nécessite Firefox 154+)
Utilitaires : accepter/refuser la boîte de dialogue, historique précédent/suivant, définir la zone d'affichage

Enregistrer les sorties volumineuses sur le disque

Les sorties volumineuses des outils peuvent consommer beaucoup de contexte 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, 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é y est généré)
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, non tronquées : les limites de taille en ligne (plafonds des messages de console, troncature des en-têtes réseau, plafonds de lignes des instantanés) 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 sous forme de 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 dans des emplacements arbitraires, y compris des chemins absolus hors de ce répertoire.

Les fichiers enregistrés peuvent ensuite être consultés avec l'outil Read de Claude Code sans impact sur la taille du contexte.

Développement local

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

Consultez CONTRIBUTING.md pour plus de détails sur le développement local, les tests et l'intégration continue (CI).

Dépannage

Firefox introuvable : passez --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) ou le chemin correct sur votre système d'exploitation.
La première exécution est lente : Selenium configure la session BiDi ; les exécutions suivantes sont plus rapides.
UID obsolètes après une navigation : prenez un nouvel instantané (take_snapshot) avant d'utiliser les outils UID.
Windows 10: Error during discovery for MCP server 'firefox-devtools': MCP error -32000: Connection closed
- Solution 1 Envelopper avec cmd /c (détails) :
```
"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 — selon votre configuration) :
```
"mcpServers": {
  "firefox-devtools": {
    "command": "C:\\nvm4w\\nodejs\\npx.ps1",
    "args": ["-y", "@mozilla/firefox-devtools-mcp@latest"]
  }
}
```

Versions

API pré-1.0 : les versions commencent à 0.x. Utilisez @latest avec npx pour la version la plus récente.

Contribuer

Consultez CONTRIBUTING.md pour savoir comment signaler des problèmes, exécuter les tests et travailler sur le projet en local.

Auteur

Maintenu par Mozilla.

Licence

Sous licence MIT ou Apache 2.0, au choix.

Lire plus

firefox-devtools-mcp v0.10.0

Catégories