firefox-devtools-mcp

Firefox DevTools MCP

Servidor del Protocolo de Contexto de Modelo 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. Use npx @mozilla/firefox-devtools-mcp@latest para ejecutarlo localmente, o use Docker con el Dockerfile proporcionado.

Seguridad

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

• Use un perfil de Firefox dedicado. Nunca ejecute el servidor contra su perfil habitual — el agente tiene acceso a todo lo que el navegador pueda alcanzar, incluyendo cookies y sesiones guardadas.
• Tenga cuidado con los sitios que visita. Las páginas pueden devolver contenido diseñado para manipular al agente (inyección de prompts). Limítese a sitios que controle o en los que confíe.
• Evite habilitar flags adicionales a menos que sea necesario. --enable-script y --enable-privileged-context amplían significativamente lo que el agente puede hacer.

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

Requisitos

• Node.js ≥ 20.19.0
• Firefox 100+ instalado (autodetectado, o pase --firefox-path)

Instalar y usar con Claude Code (npx)

Recomendado: use npx para ejecutar siempre la última versión publicada desde npm.

Opción A — CLI de Claude Code

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

Pase las opciones como argumentos o 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ñada a su 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 (build de desarrollo local)

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

Pruébelo con MCP Inspector

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

Luego llame a herramientas como:

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

Opciones de CLI

Puede pasar flags o variables de entorno (nombres a la derecha):

• --firefox-path — ruta absoluta al binario de Firefox
• --headless — ejecutar sin interfaz de usuario (FIREFOX_HEADLESS=true)
• --viewport 1280x720 — tamaño inicial de la ventana
• --profile-path — usar un perfil de Firefox específico
• --firefox-arg — argumentos extra de Firefox (repetible)
• --start-url — abrir esta URL al iniciar (START_URL)
• --accept-insecure-certs — ignorar errores TLS (ACCEPT_INSECURE_CERTS=true)
• --connect-existing — adjuntarse a un Firefox ya en ejecución en lugar de lanzar uno nuevo (CONNECT_EXISTING=true)
• --marionette-port — puerto Marionette para el modo conectar-a-existente, por defecto 2828 (MARIONETTE_PORT)
• --pref name=value — establecer preferencia de Firefox al inicio mediante moz:firefoxOptions (repetible)
• --enable-script — habilitar la herramienta evaluate_script (ejecuta JavaScript arbitrario en el contexto de la página) y herramientas de depuración (listar scripts, inspeccionar fuente, establecer logpoints). Las herramientas de depuración requieren Firefox 153+. (ENABLE_SCRIPT=true)
• --enable-privileged-context — habilitar herramientas de contexto privilegiado: listar/seleccionar contextos privilegiados, evaluar scripts privilegiados, obtener/establecer preferencias de Firefox y listar extensiones. Requiere MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device — habilitar el modo Firefox para Android; el valor es el serial del dispositivo ADB (ej. emulator-5554). Ejecute adb devices para listar los dispositivos conectados. Omita el valor o use auto para seleccionar automáticamente el único dispositivo conectado.
• --android-package — nombre del paquete de la app Android, por defecto org.mozilla.firefox. Otros paquetes: org.mozilla.firefox_beta para Firefox Beta, org.mozilla.fenix para Firefox Nightly, org.mozilla.fenix.debug para Firefox Nightly Debug, org.mozilla.geckoview_example para geckoview (ANDROID_PACKAGE)
• --log-file — escribir los logs del servidor MCP a un archivo en lugar de stderr. Útil para depurar sesiones con clientes MCP que ocultan la salida del servidor. Establezca DEBUG=* para incluir también logs de depuración detallados. Ejemplo: --log-file /tmp/firefox-mcp.log

Preferencias útiles (--pref)

• remote.prefs.recommended=false. Cuando Firefox se ejecuta en automatización, aplica RecommendedPreferences que modifican el comportamiento del navegador para pruebas. Establezca remote.prefs.recommended a false para omitirlas y tener una configuración más cercana a una instancia normal de Firefox.
• remote.log.level=Trace. Habilita logs detallados del protocolo WebDriver en Firefox. El servidor MCP pasará automáticamente el nivel de log 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. Tenga en cuenta que las actualizaciones pueden interrumpir su sesión. Requiere establecer también remote.prefs.recommended=false.

Firefox para Android

Use --android-device para automatizar Firefox ejecutándose en un dispositivo Android. Requiere adb en su 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 maneja automáticamente geckodriver.

Conectar a un Firefox existente

Use --connect-existing para automatizar su sesión de navegación real — con cookies, inicios de sesión y pestañas abiertas intactas:

# Start Firefox with Marionette enabled
firefox --marionette

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

O establezca marionette.enabled a true en about:config (o user.js) para habilitar Marionette en cada lanzamiento.

Las funciones dependientes de BiDi (eventos de consola, eventos de red) no están disponibles en el modo conectar-a-existente; todas las demás funciones funcionan normalmente.

Advertencia: No deje Marionette habilitado durante la navegación normal. Establece navigator.webdriver = true y cambia otras señales de huella digital del navegador, lo que puede activar la detección de bots en sitios protegidos por Cloudflare, Akamai, etc. Solo habilite Marionette cuando necesite automatización MCP, luego reinicie Firefox normalmente después.

Resumen de herramientas

• Páginas: listar/nueva/navegar/seleccionar/cerrar
• Instantánea/UID: tomar/resolver/limpiar
• Entrada: clic/sobrevolar/rellenar/arrastrar/subir/rellenar formulario
• Red: listar/obtener (primero por ID, filtros, captura siempre activa)
• Consola: listar/limpiar
• Captura de pantalla: página/por uid (con saveTo opcional para entornos CLI)
• Script: evaluate_script
• Contexto Privilegiado: listar/seleccionar contextos privilegiados ("chrome"), evaluate_privileged_script (requiere MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• WebExtension: install_extension, uninstall_extension, list_extensions (listar 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
• Perfilador: profiler_is_active, profiler_start (predefinido o configuración explícita), profiler_stop (guarda el perfil en el directorio de descargas)
• Utilidades: aceptar/rechazar diálogo, historial atrás/adelante, establecer viewport

Optimización de capturas de pantalla para Claude Code

Al usar capturas de pantalla en la CLI de Claude Code, los datos de imagen en base64 pueden consumir un contexto significativo. Use el parámetro saveTo para guardar las capturas en disco en su lugar:

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

El archivo puede luego visualizarse con la herramienta Read de Claude Code sin afectar el 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

Consulte CONTRIBUTING.md para más detalles sobre desarrollo local, pruebas e CI.

Solución de problemas

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

  • Solución 1 Envuelva con cmd /c (detalles):

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

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

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

Versionado

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

Contribuciones

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

Autor

Mantenido por Mozilla.

Licencia

Licenciado bajo MIT o Apache 2.0 a su elección.