firefox-devtools-mcp

Serveur MCP Firefox DevTools

Serveur du protocole de contexte de modèle (MCP) 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 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 un contenu conçu pour manipuler l'agent (injection d'invite). Tenez-vous-en aux 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 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.

Consultez SECURITY.md pour une ventilation complète des risques et la manière de signaler les vulnérabilités.

Exigences

• 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

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 indicateurs ou des variables d'environnement (noms à droite) :

• --firefox-path — chemin absolu vers le binaire Firefox
• --headless — exécuter sans interface utilisateur (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é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 de connexion à une instance 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 périphérique connecté unique.
• --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 Enregistrement de sorties volumineuses 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 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 — chaque module

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 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 de Mozilla. Le package public les ignore même s'ils sont demandés et enregistre 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 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 à 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 cookies, connexions 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 indicateurs sont requis car le MCP utilise à la fois WebDriver Classic (--marionette) et WebDriver BiDi (--remote-debugging-port). Si Firefox n'est démarré qu'avec --marionette, le serveur MCP ne parvient pas à se connecter et vous demande de redémarrer Firefox avec les deux indicateurs.

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 : lister/nouveau/naviguer/sélectionner/fermer/obtenir_texte_page (obtenir_texte_page prend en charge saveTo facultatif)
• Instantané/UID : prendre/résoudre/effacer (prendre prend en charge saveTo facultatif)
• Saisie : cliquer/survoler/remplir/glisser/téléverser/remplir formulaire
• Réseau : lister/obtenir (d'abord par ID, filtres, capture toujours active ; les deux prennent en charge saveTo facultatif)
• Téléchargements : lister_téléchargements/effacer_téléchargements (capture toujours active), définir_comportement_téléchargement (autoriser/refuser/par défaut)
• Console : lister/effacer (lister prend en charge saveTo facultatif)
• Capture d'écran : page/par uid (avec saveTo facultatif pour les environnements CLI)
• Script : évaluer_script (sandbox facultatif pour un domaine isolé ; saveTo facultatif pour les résultats volumineux)
• Contexte privilégié : lister/sélectionner les contextes privilégiés (« chrome »), évaluer_script_privilégié (nécessite MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• WebExtension : installer_extension, désinstaller_extension, lister_extensions (lister nécessite MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Gestion Firefox : obtenir_infos_firefox, obtenir_sortie_firefox, redémarrer_firefox
• Préférences Firefox : obtenir_préférences_firefox, définir_préférences_firefox (nécessite MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Profileur : profileur_est_actif, profileur_démarrer (préréglage ou configuration explicite), profileur_arrêter (enregistre le profil dans le répertoire des téléchargements)
• Screencast : screencast_démarrer (enregistre la zone d'affichage de la page dans un fichier vidéo dans le répertoire des téléchargements), screencast_arrêter (nécessite Firefox 154+)
• Utilitaires : accepter/refuser la boîte de dialogue, historique précédent/suivant, définir la zone d'affichage

Enregistrement de sorties volumineuses sur le 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 facultatif saveTo qui écrit le résultat dans un fichier au lieu de le renvoyer en ligne. saveTo prend l'une des trois formes :

• un chemin de fichier (relatif au répertoire de travail actuel, 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, non tronquées : les protections de taille en ligne (limites de messages de console, troncature des en-têtes réseau, limites de lignes d'instantané) 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 de sauvegarde 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 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

# 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'intégration continue.

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'un élément a disparu.
• 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"]
      }
    }
    

Gestion des versions

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

Contribution

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

Auteur

Maintenu par Mozilla.

Licence

Sous licence MIT ou Apache 2.0, à votre choix.