Firefox DevTools MCP

Servidor del Model Context Protocol para automatizar Firefox mediante WebDriver BiDi (a través de Selenium WebDriver). Funciona con Claude Code, Claude Desktop, Cursor, Cline y otros clientes MCP.

Repositorio: https://github.com/mozilla/firefox-devtools-mcp

Nota: Este servidor MCP requiere una instalación local del navegador Firefox y no puede ejecutarse en servicios de alojamiento en la nube como glama.ai. Usa npx @mozilla/firefox-devtools-mcp@latest para ejecutarlo localmente, o usa Docker con el Dockerfile incluido.

Seguridad

Los servidores MCP de navegador conllevan riesgos inherentes. Algunas prácticas clave:

• Usa un perfil de Firefox dedicado. Nunca ejecutes el servidor contra tu perfil habitual: el agente tiene acceso a todo lo que el navegador puede alcanzar, incluidas cookies y sesiones guardadas.
• Ten cuidado con los sitios que visitas. Las páginas pueden devolver contenido diseñado para manipular al agente (inyección de prompt). Limítate a sitios que controles o en los que confíes.
• Habilita solo los módulos de herramientas que necesites. Los presets más altos, como --tool-preset developer (script, debugging) y --tool-preset mozilla (contexto privilegiado), amplían significativamente lo que el agente puede hacer.

Consulta SECURITY.md para un desglose completo de los riesgos y cómo reportar vulnerabilidades.

Requisitos

• Node.js ≥ 20.19.0
• Firefox 100+ instalado (detección automática, o pasa --firefox-path)

Instalación y uso con Claude Code (npx)

Recomendado: usa npx para ejecutar siempre la versión publicada más reciente desde npm.

Opción A — CLI de Claude Code

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

Pasa las opciones como argumentos o como variables de entorno. Ejemplos:

# 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

Opción B — Editar el JSON de configuración de Claude Code

Añade esto a tu archivo de configuración de 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"
      }
    }
  }
}

Opción C — Script auxiliar (compilación de desarrollo local)

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

Pruébalo con MCP Inspector

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

Después llama a herramientas como:

• list_pages, select_page, navigate_page
• take_snapshot y luego click_by_uid / fill_by_uid
• list_network_requests (captura siempre activa), get_network_request
• list_downloads (captura siempre activa), set_download_behavior
• screenshot_page, list_console_messages

Opciones de CLI

Puedes pasar opciones o variables de entorno (nombres a la derecha):

• --firefox-path — ruta absoluta al binario de Firefox
• --headless — ejecutar sin interfaz gráfica (FIREFOX_HEADLESS=true)
• --viewport 1280x720 — tamaño inicial de la ventana
• --profile-path — usar un perfil específico de Firefox
• --firefox-arg — argumentos adicionales de Firefox (repetible)
• --start-url — abrir esta URL al iniciar (START_URL)
• --accept-insecure-certs — ignorar errores TLS (ACCEPT_INSECURE_CERTS=true)
• --connect-existing — conectarse a un Firefox ya en ejecución en lugar de lanzar uno nuevo (CONNECT_EXISTING=true)
• --marionette-port — puerto de Marionette para el modo connect-existing, por defecto 2828 ()

Módulos de herramientas y presets

Las herramientas se agrupan en módulos. Puedes elegir qué módulos exponer mediante un preset con nombre (--tool-preset) o con una lista explícita (--tools). Cuando se proporcionan ambos, --tools tiene prioridad y el preset se ignora.

Módulos: pages, snapshot, input, network, console, screenshot, utilities, management, webextension, profiler, screencast, script, debugging, prefs, privileged.

Presets (cada uno es un superconjunto del anterior):

• slim — pages, snapshot, input, network, console
• basic (por defecto) — slim más screenshot, utilities, management, webextension, profiler, screencast
• developer — basic más ,

# 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

Los módulos prefs y privileged requieren MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 y solo están disponibles en la compilación interna de Mozilla; el paquete público los omite silenciosamente incluso si se solicitan.

Preferencias útiles (--pref)

• remote.prefs.recommended=false. Cuando Firefox se ejecuta en modo automatizado, aplica RecommendedPreferences que modifican el comportamiento del navegador con fines de prueba. Establece remote.prefs.recommended en false para omitirlas y tener una configuración más parecida a una instancia normal de Firefox.
• remote.log.level=Trace. Habilita los registros detallados del protocolo WebDriver en Firefox. El servidor MCP pasará automáticamente el nivel de registro correspondiente a geckodriver para que ambos lados registren con la misma verbosidad.
• app.update.disabledForTesting=false. Permite que Firefox descargue y aplique actualizaciones automáticamente. Ten en cuenta que las actualizaciones pueden interrumpir tu sesión. También requiere establecer remote.prefs.recommended=false.

Firefox para Android

Usa --android-device para automatizar Firefox ejecutándose en un dispositivo Android. Requiere adb en tu PATH y geckodriver, que se gestiona automáticamente.

# 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

El reenvío de puertos entre el host y el dispositivo lo gestiona automáticamente geckodriver.

Conectarse a un Firefox existente

Usa --connect-existing para automatizar tu sesión de navegación real, con cookies, inicios de sesión y pestañas abiertas intactos:

# 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

Ambas opciones son necesarias porque el MCP utiliza tanto WebDriver Classic (--marionette) como WebDriver BiDi (--remote-debugging-port). Si Firefox se inicia solo con --marionette, el servidor MCP no puede conectarse y te pedirá que reinicies Firefox con ambas opciones.

Advertencia: No dejes Marionette habilitado durante la navegación normal. Establece navigator.webdriver = true y cambia otras señales de huella del navegador, lo que puede activar la detección de bots en sitios protegidos por Cloudflare, Akamai, etc. Habilita Marionette solo cuando necesites automatización con MCP y, después, reinicia Firefox normalmente.

Resumen de herramientas

• Páginas: list/new/navigate/select/close
• Instantánea/UID: take/resolve/clear (take admite saveTo opcional)
• Entrada: click/hover/fill/drag/upload/form fill <<<<<<< HEAD
• Red: list/get (ID‑primero, filtros, captura siempre activa; ambos admiten saveTo opcional)
• Consola: list/clear (list admite saveTo opcional) =======
• Red: list/get (ID‑primero, filtros, captura siempre activa)
• Descargas: list_downloads/clear_downloads (captura siempre activa), set_download_behavior (allow/deny/default)
• Consola: list/clear

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

• Captura de pantalla: page/by uid (con saveTo opcional para entornos CLI)
• Script: evaluate_script (con saveTo opcional para resultados voluminosos)
• Contexto privilegiado: list/select de contextos privilegiados ("chrome"), evaluate_privileged_script (requiere MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• WebExtension: install_extension, uninstall_extension, list_extensions (list requiere MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Gestión de Firefox: get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs
• Profiler: profiler_is_active, profiler_start (preset o configuración explícita), profiler_stop (guarda el perfil en el directorio de descargas)
• Screencast: screencast_start (graba el viewport de la página en un archivo de vídeo en el directorio de descargas), screencast_stop (requiere Firefox 154+)
• Utilidades: accept/dismiss dialog, history back/forward, set viewport

Guardar resultados voluminosos en disco

La salida grande de las herramientas puede consumir un contexto significativo en clientes CLI como Claude Code. Las herramientas screenshot_page, screenshot_by_uid, take_snapshot, list_console_messages, list_network_requests, get_network_request, evaluate_script y evaluate_privileged_script aceptan un parámetro opcional saveTo que escribe el resultado en un archivo en lugar de devolverlo en línea. saveTo admite una de estas tres formas:

• una ruta de archivo (relativa al directorio de trabajo actual, o absoluta dentro de ~/.firefox-devtools-mcp; los directorios padre se crean automáticamente)
• un directorio existente (se genera un archivo con marca de tiempo dentro de él)
• true (se genera un archivo con marca de tiempo en ~/.firefox-devtools-mcp/output/)

La respuesta devuelve la ruta y el tamaño en bytes. El archivo guardado siempre contiene los datos completos, sin truncar: las salvaguardas de tamaño en línea (límites de mensajes de consola, truncamiento de cabeceras de red, límites de líneas de instantáneas) nunca se aplican a él.

Las herramientas que producen texto (todas excepto las capturas de pantalla) también aceptan preview, un número de caracteres de la salida guardada que se devuelve en línea como un extracto breve. Las capturas de pantalla no tienen preview.

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

De forma predeterminada, las rutas de guardado están restringidas: las rutas relativas se resuelven contra el directorio de trabajo actual, y las rutas absolutas solo se permiten dentro de ~/.firefox-devtools-mcp. Las rutas que escapen de estas ubicaciones se rechazan. Inicia el servidor con --unrestricted-save-paths para escribir en ubicaciones arbitrarias, incluidas rutas absolutas fuera de ese directorio.

Los archivos guardados se pueden ver después con la herramienta Read de Claude Code sin afectar al tamaño del contexto.

Desarrollo 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

Consulta CONTRIBUTING.md para más detalles sobre el desarrollo local, las pruebas y la CI.

Solución de problemas

• Firefox no encontrado: pasa --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) o la ruta correcta en tu sistema operativo.
• La primera ejecución es lenta: Selenium configura la sesión BiDi; las ejecuciones posteriores son más rápidas.
• UID obsoletos tras la navegación: toma una instantánea nueva (take_snapshot) antes de usar las herramientas de UID.
• Windows 10: Error durante la detección del servidor MCP 'firefox-devtools': MCP error -32000: Connection closed

  • Solución 1 Envuélvelo con cmd /c (detalles):

    root@kitploit:~

    "mcpServers": {
      "firefox-devtools": {
        "command": "cmd",
        "args": ["/c", "npx", "-y", "@mozilla/firefox-devtools-mcp@latest"]
      }
    }
    

  • Solución 2 Usa la ruta absoluta a npx (ajusta la extensión — .cmd, .bat, .exe o .ps1 — para que coincida con tu configuración):

    root@kitploit:~

Versionado

• API pre‑1.0: las versiones empiezan en 0.x. Usa @latest con npx para la versión más reciente.

Contribuciones

Consulta CONTRIBUTING.md para saber cómo reportar problemas, ejecutar pruebas y trabajar en el proyecto localmente.

Autor

Mantenido por Mozilla.

Licencia

Publicado bajo MIT o Apache 2.0, a tu elección.