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

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 pueda 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 prompts). Limítate a sitios que controles o en los que confíes.
• Habilita solo los módulos de herramientas que necesites. El preset basic predeterminado ya incluye evaluate_script; --tool-preset slim lo elimina. Los presets superiores como --tool-preset developer (depuración, red, consola, perfilador) y --tool-preset mozilla (contexto privilegiado) amplían aún más 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 o Codex (npx)

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

Opción A — CLI

Claude Code

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

# Headless + viewport mediante argumentos
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# O mediante variables de entorno
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 mediante argumentos
codex mcp add firefox-devtools -- \
  npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# O mediante variables de entorno
codex mcp add firefox-devtools \
  --env START_URL=https://example.com \
  --env FIREFOX_HEADLESS=true \
  -- npx @mozilla/firefox-devtools-mcp@latest

Opción B — Editar el archivo de configuración

Claude Code

Añade a 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

Añade a ~/.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"

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

npm run setup
# Elige Claude Code; el script guarda el JSON en la ruta correcta

Pruébalo con MCP Inspector

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

Luego 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 banderas 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 específico de Firefox
• --firefox-arg — argumentos adicionales de Firefox (repetible)
• --start-url — abrir esta URL al inicio (START_URL)
• --accept-insecure-certs — ignorar errores TLS (ACCEPT_INSECURE_CERTS=true)
• --connect-existing — conectarse a una instancia de Firefox ya en ejecución en lugar de lanzar una nueva (CONNECT_EXISTING=true)
• --marionette-port — puerto de Marionette para el modo connect-existing, predeterminado 2828 (MARIONETTE_PORT)
• --pref name=value — establecer una preferencia de Firefox al inicio mediante moz:firefoxOptions (repetible)
• --tool-preset — seleccionar qué módulos de herramientas habilitar: slim, basic (predeterminado), developer, mozilla o all. Consulta Módulos de herramientas y presets. (TOOL_PRESET)
• --tools — lista explícita de módulos de herramientas a habilitar, que anula por completo --tool-preset (p. ej. --tools pages network script). Consulta Módulos de herramientas y presets.
• --enable-script — obsoleto, usa --tool-preset developer o --tools ... script debugging. Selecciona el preset de herramientas developer. (ENABLE_SCRIPT=true)
• --enable-privileged-context — obsoleto, usa --tool-preset mozilla o --tools ... privileged prefs. Selecciona el preset de herramientas mozilla. 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 (p. ej. emulator-5554). Ejecuta adb devices para listar los dispositivos conectados. Omite el valor o usa auto para seleccionar automáticamente el único dispositivo conectado.
• --android-wipe-app-data — confirmar que el modo Android borra todos los datos de la aplicación objetivo. Requerido junto con --android-device. (ANDROID_WIPE_APP_DATA=true)
• --android-package — nombre del paquete de la aplicación Android, predeterminado 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)
• --unrestricted-save-paths — permitir que el parámetro saveTo escriba en cualquier lugar del disco en lugar de las raíces predeterminadas. Consulta Guardar salida voluminosa en disco y la nota de seguridad en SECURITY.md. (UNRESTRICTED_SAVE_PATHS=true)
• --log-file — escribir los registros del servidor MCP en un archivo en lugar de stderr. Útil para sesiones de depuración con clientes MCP que ocultan la salida del servidor. Establece DEBUG=* para incluir también registros de depuración detallados. Ejemplo: --log-file /tmp/firefox-mcp.log

Módulos de herramientas y presets

Las herramientas se agrupan en módulos. Puedes elegir qué módulos exponer con 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, downloads, utilities, management, webextension, profiler, screencast, script, debugging, prefs, privileged.

Presets (cada uno es un superconjunto del anterior):

• slim — pages, snapshot, input, screenshot
• basic (predeterminado) — slim más downloads, script, utilities, management, webextension, screencast
• developer — basic más debugging, network, console, profiler
• mozilla — developer más prefs, privileged
• all — todos los módulos

Ten en cuenta que basic, el predeterminado, incluye script y, por tanto, la herramienta evaluate_script. Consulta SECURITY.md para saber qué significa eso para la superficie de ataque, y usa --tool-preset slim o una lista explícita de --tools para eliminarlo.

# Usa el preset developer (añade herramientas de red, consola, depuración y perfilador)
npx @mozilla/firefox-devtools-mcp --tool-preset developer

# Habilita solo los módulos que necesitas
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 incluso si se solicitan y registra una advertencia nombrando los módulos que descartó.

Preferencias útiles (--pref)

• remote.prefs.recommended=false. Cuando Firefox se ejecuta en automatización, aplica RecommendedPreferences que modifican el comportamiento del navegador para pruebas. Establece remote.prefs.recommended en false para omitirlas y tener una configuración más cercana a una instancia normal de Firefox.
• remote.log.level=Trace. Habilita 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. Requiere también 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.

Advertencia: El modo Android borra todos los datos de la aplicación objetivo antes de cada sesión. Se pierden pestañas, historial, marcadores, contraseñas, cookies y configuración. geckodriver ejecuta adb shell pm clear <package> al crear la sesión y no ofrece forma de omitirlo, luego ejecuta la sesión en su propio perfil temporal que se elimina después. Debido a esto, --android-device requiere --android-wipe-app-data, y debes instalar una compilación dedicada a la automatización en lugar de automatizar el navegador que usas. Bug 2064088 rastrea la adición de una opción a geckodriver para conservar los datos existentes de la aplicación.

# Lista los dispositivos conectados
adb devices

# Lanza Firefox para Android en el único dispositivo conectado
npx @mozilla/firefox-devtools-mcp --android-device auto --android-wipe-app-data

# Apunta a un dispositivo específico
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-wipe-app-data

# Usa Firefox Nightly en su lugar
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix --android-wipe-app-data

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

Conectarse a 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:

# Inicia Firefox con Marionette y el Remote Agent (BiDi)
firefox --marionette --remote-debugging-port

# Ejecuta el servidor MCP
npx @mozilla/firefox-devtools-mcp --connect-existing --marionette-port 2828

Ambas banderas son necesarias porque el MCP usa 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 pide reiniciar Firefox con ambas banderas.

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 MCP y luego reinicia Firefox normalmente.

Resumen de herramientas

Consulta docs/tools.md para la lista completa de herramientas por módulo, con descripciones y parámetros (generada desde el código fuente).

• Pages: list/new/navigate/select/close/get_page_text (get_page_text admite saveTo opcional)
• Snapshot/UID: take/resolve/clear (take admite saveTo opcional)
• Input: click/hover/fill/drag/upload/form fill/press_key/type_text
• Network: list/get (primero por ID, filtros, captura siempre activa; ambos admiten saveTo opcional)
• Downloads: list_downloads/clear_downloads (captura siempre activa), set_download_behavior (allow/deny/default)
• Console: list/clear (list admite saveTo opcional)
• Screenshot: page/by uid (con saveTo opcional para entornos CLI)
• Script: evaluate_script (sandbox opcional para un ámbito aislado; saveTo opcional para resultados voluminosos)
• Privileged Context: list/select 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)
• Firefox Management: get_firefox_info, get_firefox_output, restart_firefox
• Firefox Preferences: get_firefox_prefs, set_firefox_prefs (requiere MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Profiler: profiler_is_active, profiler_start (configuración preestablecida o 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 video en el directorio de descargas), screencast_stop (requiere Firefox 154+)
• Utilities: accept/dismiss dialog, history back/forward, set viewport

Guardar salida voluminosa en disco

La salida grande de herramientas puede consumir 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, get_page_text, 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 toma una de tres formas:

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

La respuesta devuelve la ruta y el tamaño en bytes. El archivo guardado siempre contiene los datos completos y 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 snapshot) 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 para devolver en línea como un extracto breve. Las capturas de pantalla no tienen vista previa.

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

Por defecto, 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 escapan 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 pueden verse, por ejemplo, con la herramienta Read de Claude Code sin afectar el tamaño del contexto.

Desarrollo local

npm install
npm run build

# Ejecutar con Inspector contra la compilación local
npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720

# O ejecutar en desarrollo con recarga en caliente
npm run inspector:dev

Consulta CONTRIBUTING.md para más detalles sobre desarrollo local, pruebas y 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.
• UIDs obsoletos: un UID sigue siendo válido hasta que su elemento se elimina o la página navega; toma un snapshot nuevo (take_snapshot) cuando una herramienta de UID informe que uno ya no existe.
• Windows 10: Error durante el descubrimiento del servidor MCP 'firefox-devtools': MCP error -32000: Connection closed

  • Solución 1 Envuelve 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:~

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

Versionado

• API previa a 1.0: las versiones comienzan 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

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