firefox-devtools-mcp

Firefox DevTools MCP

Serveur 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 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). Limitez-vous aux sites que vous contrôlez ou en lesquels vous avez confiance.
• Évitez d'activer des options supplémentaires sauf si nécessaire. --enable-script et --enable-privileged-context étendent considérablement ce que l'agent peut faire.

Consultez SECURITY.md pour une analyse complète des risques et comment signaler les vulnérabilités.

Prérequis

• Node.js ≥ 20.19.0
• Firefox 100+ installé (détecté automatiquement, ou passez --firefox-path)

Installation et utilisation 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'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
• 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é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 à 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)
• --enable-script — activer l'outil evaluate_script (exécute du JavaScript arbitraire dans le contexte de la page) et les outils de débogage (lister les scripts, inspecter la source, définir des points de journalisation). Les outils de débogage nécessitent Firefox 153+. (ENABLE_SCRIPT=true)
• --enable-privileged-context — activer les outils de contexte privilégié : lister/sélectionner les contextes privilégiés, évaluer des scripts privilégiés, obtenir/définir les préférences Firefox et lister les extensions. 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-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)
• --log-file — écrire les journaux du serveur MCP dans un fichier au lieu de stderr. Utile pour déboguer les sessions avec les 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

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. Active 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 avec la même verbosité.
• app.update.disabledForTesting=false. Permet à 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 périphérique 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

Le transfert de port entre l'hôte et le périphérique est géré automatiquement par geckodriver.

Connexion à 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 enabled
firefox --marionette

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

Ou définissez marionette.enabled sur true dans about:config (ou user.js) pour activer Marionette à chaque lancement.

Les fonctionnalités dépendantes de BiDi (événements de console, événements réseau) ne sont pas disponibles en mode connexion existante ; toutes les autres fonctionnalités fonctionnent normalement.

Avertissement : Ne laissez pas Marionette activé pendant la navigation normale. Il définit navigator.webdriver = true et modifie d'autres signaux d'empreinte numérique du navigateur, ce qui peut déclencher la détection de robots sur les sites protégés par Cloudflare, Akamai, etc. Activez Marionette uniquement lorsque vous avez besoin de l'automatisation MCP, puis redémarrez Firefox normalement par la suite.

Aperçu des outils

• Pages : lister/nouveau/naviguer/sélectionner/fermer
• Snapshot/UID : prendre/résoudre/effacer
• Saisie : cliquer/survoler/remplir/glisser/téléverser/remplir formulaire
• Réseau : lister/obtenir (ID d'abord, filtres, capture toujours active)
• Console : lister/effacer
• Capture d'écran : page/par uid (avec option saveTo pour les environnements CLI)
• Script : evaluate_script
• 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
• Profileur : profiler_is_active, profiler_start (préréglage ou configuration explicite), profiler_stop (enregistre le profil dans le répertoire de téléchargements)
• Utilitaires : accepter/rejeter la boîte de dialogue, historique précédent/suivant, définir la fenêtre d'affichage

Optimisation des captures d'écran pour Claude Code

Lors de l'utilisation de captures d'écran dans la CLI Claude Code, les données d'image base64 peuvent consommer un contexte important. Utilisez le paramètre saveTo pour enregistrer les captures d'écran sur le disque à la place :

screenshot_page({ saveTo: "/tmp/page.png" })
screenshot_by_uid({ uid: "abc123", saveTo: "/tmp/element.png" })

Le fichier peut ensuite être visualisé 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

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.
• La première exécution est lente : Selenium configure la session BiDi ; les exécutions suivantes sont plus rapides.
• UID obsolètes après navigation : prenez un nouveau snapshot (take_snapshot) avant d'utiliser les outils UID.
• 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

Consultez CONTRIBUTING.md pour savoir comment soumettre 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.