firefox-devtools-mcp

Servidor MCP de Firefox DevTools

Servidor del Protocolo de Contexto de Modelo (MCP) que permite a los agentes de IA usar Firefox. Tiene dos casos de uso principales:

• Navegación agéntica: el agente usa el navegador para tareas habituales, como leer páginas, rellenar formularios y completar flujos de varios pasos en sitios web.
• Desarrollo web asistido por agente: el agente carga la página en la que estás trabajando y la inspecciona con herramientas de desarrollo, como la consola, las solicitudes de red, el depurador y el perfilador.

Controla Firefox mediante WebDriver BiDi (a través de Selenium WebDriver) y 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 con 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 obtener un desglose completo de los riesgos y cómo informar 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 versión publicada más reciente 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 de Firefox específico. Firefox se ejecuta en una subcarpeta firefox_devtools_mcp_profile de esa ruta, marcada con un archivo .firefox-devtools-mcp; apuntar --profile-path a un perfil marcado lo reutiliza directamente
• --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, que anula --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 detallados. 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 se ignora el preset.

Presets (cada uno es un superconjunto del anterior):

• slim — el mínimo para navegar e interactuar con páginas
• basic (predeterminado) — añade herramientas para navegación habitual
• developer — añade herramientas para desarrolladores web
• mozilla — añade herramientas para desarrolladores de Firefox
• all — todos los módulos

Consulta docs/tools.md para la lista de módulos y los módulos en cada preset.

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

# 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 módulo launch también requiere la compilación interna de Mozilla: reinicia Firefox bajo un binario, perfil, entorno y conjunto de preferencias elegidos por el llamador, lo cual es un cambio de configuración que el operador debería controlar. Usa --pref, --firefox-path y las otras opciones de línea de comandos en su lugar. El módulo bidi también requiere la compilación interna de Mozilla: envía cualquier comando WebDriver BiDi, por lo que da acceso a lo que exponen los otros módulos. El paquete público omite estos módulos 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 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 configuraciones. 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 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 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 que reinicies 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. Solo habilita Marionette 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).

Guardar salida voluminosa en disco

La salida grande de herramientas puede consumir contexto significativo en clientes CLI como Claude Code. Varias herramientas aceptan un parámetro opcional saveTo que escribe el resultado en un archivo en lugar de devolverlo en línea. Consulta docs/tools.md para la lista. saveTo toma una de tres formas:

• una ruta de archivo (relativa al directorio de trabajo actual, o absoluta dentro de ~/.firefox-devtools-mcp/output; los directorios padre se crean). Se rechazan las rutas que llegan a un perfil de Firefox, o los archivos que este servidor lee de vuelta
• 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 instantáneas) nunca se aplican a él.

Las herramientas que producen texto también aceptan preview, un número de caracteres de la salida guardada para devolver en línea como un extracto breve. La lista en docs/tools.md muestra qué herramientas lo admiten.

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 se pueden ver luego, 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.