firefox-devtools-mcp

Firefox DevTools MCP

Serveur Model Context Protocol qui permet aux agents IA d'utiliser Firefox. Il a deux cas d'utilisation principaux :

• Navigation agentique : l'agent utilise le navigateur pour des tâches courantes, comme lire des pages, remplir des formulaires et parcourir des flux multi-étapes sur des sites web.
• Développement web assisté par agent : l'agent charge la page sur laquelle vous travaillez et l'inspecte avec les outils de développement, tels que la console, les requêtes réseau, le débogueur et le profileur.

Il contrôle Firefox via WebDriver BiDi (via Selenium WebDriver) et 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 du navigateur 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'invite). Restez sur des sites que vous contrôlez ou auxquels vous faites confiance.
• Activez uniquement les modules d'outils dont vous avez besoin. Le préréglage par défaut basic inclut déjà evaluate_script ; --tool-preset slim le supprime. Les préréglages supérieurs tels que --tool-preset developer (débogage, réseau, console, profileur) et --tool-preset mozilla (contexte privilégié) étendent davantage ce que l'agent peut faire.

Voir SECURITY.md pour une ventilation complète des risques et comment 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 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

Codex

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

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

# Or via environment variables
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
# Choose Claude Code; the script saves JSON to the right path

Essayez avec MCP Inspector

npx @modelcontextprotocol/inspector npx @mozilla/firefox-devtools-mcp@latest --start-url https://example.com --headless

Ensuite, appelez 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 s'exécute dans un sous-dossier firefox_devtools_mcp_profile de ce chemin, marqué par un fichier .firefox-devtools-mcp ; pointer --profile-path vers un profil marqué le réutilise directement
• --firefox-arg — arguments Firefox supplémentaires (répétables)
• --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 à un Firefox déjà en cours d'exécution au lieu d'en lancer un nouveau (CONNECT_EXISTING=true)
• --marionette-port — port Marionette pour le mode connexion-existante, 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 exemple --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 exemple 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 package de l'application Android, par défaut org.mozilla.firefox. Autres packages : 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 Enregistrer une sortie volumineuse sur le 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 les sessions de débogage 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 gagne et le préréglage est ignoré.

Préréglages (chacun est un sur-ensemble du précédent) :

• slim — le minimum pour naviguer et interagir avec les pages
• basic (par défaut) — ajoute des outils pour la navigation courante
• developer — ajoute des outils pour les développeurs web
• mozilla — ajoute des outils pour les développeurs Firefox
• all — chaque module

Voir docs/tools.md pour la liste des modules et les modules dans chaque préréglage.

Notez que basic, le préréglage par défaut, inclut script et donc l'outil evaluate_script. Voir SECURITY.md pour ce que cela signifie pour la surface d'attaque, et utilisez --tool-preset slim ou une liste explicite --tools pour le supprimer.

# Use the developer preset (adds network, console, debugging and profiler 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 Mozilla. Le module launch nécessite également la build interne Mozilla : il redémarre Firefox sous un binaire, un profil, un environnement et un ensemble de préférences choisis par l'appelant, ce qui est un changement de configuration que l'opérateur devrait posséder. Utilisez --pref, --firefox-path et les autres options de ligne de commande à la place. Le module bidi nécessite également la build interne Mozilla : il envoie n'importe quelle commande WebDriver BiDi, donc il donne accès à ce que les autres modules exposent. Le package public ignore ces modules même s'ils sont demandés et journalise un avertissement nommant les modules qu'il a 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 régulière.
• 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 à la même verbosité.
• app.update.disabledForTesting=false. Autorisez Firefox à télécharger et 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. Les onglets, l'historique, les marque-pages, les mots de passe, les cookies et les 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.

# List connected devices
adb devices

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

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

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

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

Se connecter à un Firefox existant

Utilisez --connect-existing pour automatiser votre session de navigation réelle, avec les cookies, les connexions et les 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 drapeaux sont requis car le MCP utilise à la fois WebDriver Classic (--marionette) et WebDriver BiDi (--remote-debugging-port). Si Firefox est uniquement démarré 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 des sites protégés par Cloudflare, Akamai, etc. Activez Marionette uniquement lorsque vous avez besoin de l'automatisation MCP, puis redémarrez Firefox normalement ensuite.

Aperçu des outils

Voir 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).

Enregistrer une sortie volumineuse sur le disque

Une sortie d'outil volumineuse peut consommer un contexte significatif dans les clients CLI comme Claude Code. Plusieurs outils acceptent un paramètre optionnel saveTo qui écrit le résultat dans un fichier au lieu de le renvoyer en ligne. Voir docs/tools.md pour la liste. 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/output ; les répertoires parents sont créés). Les chemins atteignant un profil Firefox, ou les fichiers que ce serveur relit, sont refusé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, non tronquées : les garde-fous de taille en ligne (limites de messages de console, troncature d'en-têtes réseau, limites de lignes d'instantané) ne s'y appliquent jamais.

Les outils produisant du texte acceptent également preview, un nombre de caractères de la sortie enregistrée à renvoyer en ligne comme court extrait. La liste dans docs/tools.md montre quels outils le prennent en charge.

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 se résolvent par rapport au répertoire de travail courant, et les chemins absolus ne sont autorisés que dans ~/.firefox-devtools-mcp. Les chemins qui s'échappent 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 visualisés par exemple avec l'outil Read de Claude Code sans impacter 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

Voir 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.
• La première exécution est 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 nouvel instantané (take_snapshot) lorsqu'un outil UID signale qu'il est introuvable.
• Windows 10 : Erreur lors de la découverte du serveur MCP 'firefox-devtools' : Erreur MCP -32000 : Connexion fermée

  • Solution 1 Enveloppez 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 — pour correspondre à votre configuration) :

    "mcpServers": {
      "firefox-devtools": {
        "command": "C:\\nvm4w\\nodejs\\npx.ps1",
        "args": ["-y", "@mozilla/firefox-devtools-mcp@latest"]
      }
    }
    

Versioning

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