firefox-devtools-mcp

Servidor MCP de Firefox DevTools

Servidor del Protocolo de Contexto de Modelo (MCP) 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 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 prompts). Limítate a sitios que controles o en los que confíes.
• Habilita solo los módulos de herramientas que necesites. El preset predeterminado basic 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 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

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
# 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

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 un Firefox ya en ejecución en lugar de lanzar uno nuevo (CONNECT_EXISTING=true)
• --marionette-port — puerto de Marionette para el modo de conexión a existente, predeterminado 2828 (MARIONETTE_PORT)
• --pref name=value — establecer 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, anulando --tool-preset por completo (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 verbosos. Ejemplo: --log-file /tmp/firefox-mcp.log

Módulos de herramientas y presets

Las herramientas se agrupan en módulos. Eliges qué módulos exponer ya sea con un preset con nombre (--tool-preset) o con una lista explícita (--tools). Cuando se proporcionan ambos, --tools gana 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 lo 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.

# 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

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 omitió.

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 regular de Firefox.
• remote.log.level=Trace. Habilita registros verbosos 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. Las pestañas, el historial, los marcadores, las contraseñas, las cookies y la configuración se pierden. 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 deberías 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.

# 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

El reenvío de puertos entre el host y el dispositivo se gestiona automáticamente por 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 intactas:

# 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 banderas son necesarias porque el MCP usa tanto WebDriver Classic (--marionette) como WebDriver BiDi (--remote-debugging-port). Si Firefox solo se inicia 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, luego reinicia Firefox normalmente después.

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

• Páginas: list/new/navigate/select/close/get_page_text (get_page_text admite saveTo opcional)
• Snapshot/UID: take/resolve/clear (take admite saveTo opcional)
• Entrada: click/hover/fill/drag/upload/relleno de formularios
• Red: list/get (primero por ID, filtros, captura siempre activa; ambos admiten saveTo opcional)
• Descargas: list_downloads/clear_downloads (captura siempre activa), set_download_behavior (allow/deny/default)
• Consola: list/clear (list admite saveTo opcional)
• Captura de pantalla: page/por uid (con saveTo opcional para entornos CLI)
• Script: evaluate_script (sandbox opcional para un ámbito aislado; saveTo opcional para resultados voluminosos)
• Contexto privilegiado: 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)
• Gestión de Firefox: get_firefox_info, get_firefox_output, restart_firefox
• Preferencias de Firefox: get_firefox_prefs, set_firefox_prefs (requiere MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Perfilador: profiler_is_active, profiler_start (configuración de preset o explícita), profiler_stop (guarda el perfil en el directorio de descargas)
• Screencast: screencast_start (graba la vista de la página en un archivo de video en el directorio de descargas), screencast_stop (requiere Firefox 154+)
• Utilidades: 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, sin truncar: las salvaguardas de tamaño en línea (límites de mensajes de consola, truncamiento de encabezados de red, límites de líneas de snapshot) nunca se aplican a él.

Las herramientas que producen texto (todo 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 son rechazadas. Inicia el servidor con --unrestricted-save-paths para escribir en ubicaciones arbitrarias, incluyendo 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

# 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 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 permanece válido hasta que su elemento se elimina o la página navega; toma una nueva instantánea (take_snapshot) cuando una herramienta de UID informe que uno ya no existe.
• Windows 10: Error durante la detección del servidor MCP 'firefox-devtools': Error MCP -32000: Conexión cerrada

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

    "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):

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