Firefox DevTools MCP

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

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

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 :

{
  "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 :

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

npm run setup
# Choisissez Claude Code ; le script enregistre le JSON au bon chemin

Essayez 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 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. (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 — 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 et la note de sécurité dans 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 pour comprendre ce que cela implique pour la surface d'attaque, et utilisez --tool-preset slim ou une liste --tools explicite pour le supprimer.

# 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 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 suit l'ajout d'une option à geckodriver pour conserver les données d'application existantes.

# 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 :

# 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 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

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

    root@kitploit:~

    "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) :

    root@kitploit:~

    "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 pour savoir comment signaler des problèmes, exécuter des tests et travailler sur le projet localement.

Auteur

Maintenu par Mozilla.

Licence

Sous licence MIT ou Apache 2.0 à votre choix.