Servidor del Protocolo de Contexto de Modelo para Firefox DevTools - permite a los asistentes de IA inspeccionar y controlar el navegador Firefox a través de WebDriver BiDi
# Firefox DevTools MCP
[](https://www.npmjs.com/package/@mozilla/firefox-devtools-mcp)
[](https://github.com/mozilla/firefox-devtools-mcp/actions/workflows/ci.yml)
[](https://codecov.io/gh/mozilla/firefox-devtools-mcp)
[](LICENSE-MIT) [](LICENSE-APACHE)
<a href="https://glama.ai/mcp/servers/@mozilla/firefox-devtools-mcp"><img src="https://assets.kitploit.com/production/public/readmes/8655/a78a7d97ae218a4638aa3f14a824feef8d0e205b36490113ed8fa15dac83148a.png" height="223" alt="Glama"></a>
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](https://github.com/mozilla/firefox-devtools-mcp/blob/main/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
```bash
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
```bash
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:
```json
{
"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:
```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)
```bash
npm run setup
# Elige Claude Code; el script guarda el JSON en la ruta correcta
```
## Pruébalo con MCP Inspector
```bash
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](#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](#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](#guardar-salida-voluminosa-en-disco) y la nota de seguridad en [SECURITY.md](https://github.com/mozilla/firefox-devtools-mcp/blob/main/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](https://github.com/mozilla/firefox-devtools-mcp/blob/main/SECURITY.md#tool-modules-and-presets) para saber qué significa eso para la
superficie de ataque, y usa `--tool-preset slim` o una lista explícita de `--tools` para eliminarlo.
```bash
# 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](https://searchfox.org/firefox-main/source/remote/shared/RecommendedPreferences.sys.mjs) 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](https://bugzilla.mozilla.org/show_bug.cgi?id=2064088) rastrea la adición de una
> opción a geckodriver para conservar los datos existentes de la aplicación.
```bash
# 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:
```bash
# 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](https://github.com/mozilla/firefox-devtools-mcp/blob/main/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
```bash
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](https://github.com/mozilla/firefox-devtools-mcp/blob/main/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](https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310)):
```json
"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):
```json
"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](https://github.com/mozilla/firefox-devtools-mcp/blob/main/CONTRIBUTING.md) para saber cómo reportar problemas, ejecutar pruebas y trabajar en el proyecto localmente.
## Autor
Mantenido por [Mozilla](https://www.mozilla.org).
## Licencia
Licenciado bajo [MIT](https://github.com/mozilla/firefox-devtools-mcp/blob/main/LICENSE-MIT) o [Apache 2.0](https://github.com/mozilla/firefox-devtools-mcp/blob/main/LICENSE-APACHE), a tu elección.