firefox-devtools-mcp

Firefox DevTools MCP

Servidor do Model Context Protocol para automatizar o Firefox via WebDriver BiDi (através do Selenium WebDriver). Funciona com Claude Code, Claude Desktop, Cursor, Cline e outros clientes MCP.

Repositório: https://github.com/mozilla/firefox-devtools-mcp

Nota: Este servidor MCP requer uma instalação local do navegador Firefox e não pode ser executado em serviços de hospedagem em nuvem como glama.ai. Use npx @mozilla/firefox-devtools-mcp@latest para executar localmente, ou use Docker com o Dockerfile fornecido.

Segurança

Servidores MCP de navegador apresentam riscos inerentes. Algumas práticas importantes:

• Use um perfil Firefox dedicado. Nunca execute o servidor contra seu perfil regular — o agente tem acesso a tudo o que o navegador pode alcançar, incluindo cookies e sessões salvas.
• Tenha cuidado com quais sites você visita. Páginas podem retornar conteúdo projetado para manipular o agente (injeção de prompt). Fique em sites que você controla ou confia.
• Habilite apenas os módulos de ferramentas que você precisa. O preset padrão basic já inclui evaluate_script; --tool-preset slim o remove. Presets mais altos como --tool-preset developer (depuração, rede, console, profiler) e --tool-preset mozilla (contexto privilegiado) expandem ainda mais o que o agente pode fazer.

Consulte SECURITY.md para uma análise completa dos riscos e como reportar vulnerabilidades.

Requisitos

• Node.js ≥ 20.19.0
• Firefox 100+ instalado (detectado automaticamente, ou passe --firefox-path)

Instalar e usar com Claude Code ou Codex (npx)

Recomendado: use npx para executar a versão publicada mais recente do npm.

Opção 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

Opção B — Editar o arquivo de configuração

Claude Code

Adicione ao mcp_settings.json do Claude Code:

{
  "mcpServers": {
    "firefox-devtools": {
      "command": "npx",
      "args": ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "env": {
        "START_URL": "about:blank"
      }
    }
  }
}

Codex

Adicione ao ~/.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"

Opção C — Script auxiliar (build de desenvolvimento local)

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

Experimente com o MCP Inspector

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

Em seguida, chame ferramentas como:

• list_pages, select_page, navigate_page
• take_snapshot e depois click_by_uid / fill_by_uid
• list_network_requests (captura sempre ativa), get_network_request
• list_downloads (captura sempre ativa), set_download_behavior
• screenshot_page, list_console_messages

Opções de CLI

Você pode passar flags ou variáveis de ambiente (nomes à direita):

• --firefox-path — caminho absoluto para o binário do Firefox
• --headless — executar sem interface gráfica (FIREFOX_HEADLESS=true)
• --viewport 1280x720 — tamanho inicial da janela
• --profile-path — usar um perfil Firefox específico
• --firefox-arg — argumentos extras do Firefox (repetível)
• --start-url — abrir esta URL na inicialização (START_URL)
• --accept-insecure-certs — ignorar erros de TLS (ACCEPT_INSECURE_CERTS=true)
• --connect-existing — anexar a um Firefox já em execução em vez de iniciar um novo (CONNECT_EXISTING=true)
• --marionette-port — porta Marionette para o modo conectar-existente, padrão 2828 (MARIONETTE_PORT)
• --pref name=value — definir preferência do Firefox na inicialização via moz:firefoxOptions (repetível)
• --tool-preset — selecionar quais módulos de ferramentas habilitar: slim, basic (padrão), developer, mozilla ou all. Consulte Módulos de ferramentas e presets. (TOOL_PRESET)
• --tools — lista explícita de módulos de ferramentas a habilitar, substituindo --tool-preset completamente (ex.: --tools pages network script). Consulte Módulos de ferramentas e presets.
• --enable-script — obsoleto, use --tool-preset developer ou --tools ... script debugging. Seleciona o preset de ferramentas developer. (ENABLE_SCRIPT=true)
• --enable-privileged-context — obsoleto, use --tool-preset mozilla ou --tools ... privileged prefs. Seleciona o preset de ferramentas mozilla. Requer MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device — habilitar modo Firefox para Android; o valor é o serial do dispositivo ADB (ex.: emulator-5554). Execute adb devices para listar dispositivos conectados. Omita o valor ou use auto para selecionar automaticamente o único dispositivo conectado.
• --android-wipe-app-data — confirmar que o modo Android apaga todos os dados do aplicativo alvo. Obrigatório junto com --android-device. (ANDROID_WIPE_APP_DATA=true)
• --android-package — nome do pacote do aplicativo Android, padrão org.mozilla.firefox. Outros pacotes: 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 o parâmetro saveTo grave em qualquer lugar do disco em vez das raízes padrão. Consulte Salvando saída volumosa em disco e a nota de segurança em SECURITY.md. (UNRESTRICTED_SAVE_PATHS=true)
• --log-file — gravar logs do servidor MCP em um arquivo em vez de stderr. Útil para sessões de depuração com clientes MCP que ocultam a saída do servidor. Defina DEBUG=* para também incluir logs de depuração detalhados. Exemplo: --log-file /tmp/firefox-mcp.log

Módulos de ferramentas e presets

As ferramentas são agrupadas em módulos. Você escolhe quais módulos expor com um preset nomeado (--tool-preset) ou com uma lista explícita (--tools). Quando ambos são fornecidos, --tools vence e o preset é ignorado.

Módulos: pages, snapshot, input, network, console, screenshot, downloads, utilities, management, webextension, profiler, screencast, script, debugging, prefs, privileged.

Presets (cada um é um superconjunto do anterior):

• slim — pages, snapshot, input, screenshot
• basic (padrão) — slim mais downloads, script, utilities, management, webextension, screencast
• developer — basic mais debugging, network, console, profiler
• mozilla — developer mais prefs, privileged
• all — todos os módulos

Observe que basic, o padrão, inclui script e, portanto, a ferramenta evaluate_script. Consulte SECURITY.md para entender o que isso significa para a superfície de ataque, e use --tool-preset slim ou uma lista explícita de --tools para removê-lo.

# 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

Os módulos prefs e privileged requerem MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 e estão disponíveis apenas no build interno da Mozilla. O pacote público os ignora mesmo se solicitados e registra um aviso nomeando os módulos que foram removidos.

Preferências úteis (--pref)

• remote.prefs.recommended=false. Quando o Firefox é executado em automação, ele aplica RecommendedPreferences que modificam o comportamento do navegador para testes. Defina remote.prefs.recommended como false para ignorar essas preferências e ter uma configuração mais próxima de uma instância regular do Firefox.
• remote.log.level=Trace. Habilite logs detalhados do protocolo WebDriver no Firefox. O servidor MCP passará automaticamente o nível de log correspondente ao geckodriver para que ambos os lados registrem na mesma verbosidade.
• app.update.disabledForTesting=false. Permitir que o Firefox baixe e aplique atualizações automaticamente. Observe que as atualizações podem interromper sua sessão. Requer também definir remote.prefs.recommended=false.

Firefox para Android

Use --android-device para automatizar o Firefox em execução em um dispositivo Android. Requer adb no seu PATH e geckodriver, que é gerenciado automaticamente.

Aviso: O modo Android apaga todos os dados do aplicativo alvo antes de cada sessão. Abas, histórico, favoritos, senhas, cookies e configurações são todos perdidos. O geckodriver executa adb shell pm clear <package> ao criar a sessão e não oferece como ignorar, depois executa a sessão em seu próprio perfil temporário que é excluído em seguida. Por causa disso, --android-device requer --android-wipe-app-data, e você deve instalar um build dedicado à automação em vez de automatizar o navegador que você usa. Bug 2064088 rastreia a adição de uma opção ao geckodriver para manter os dados existentes do aplicativo.

# 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

O encaminhamento de portas entre o host e o dispositivo é tratado automaticamente pelo geckodriver.

Conectar a um Firefox existente

Use --connect-existing para automatizar sua sessão real de navegação, com cookies, logins e abas abertas intactos:

# 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 as flags são obrigatórias porque o MCP usa tanto WebDriver Classic (--marionette) quanto WebDriver BiDi (--remote-debugging-port). Se o Firefox for iniciado apenas com --marionette, o servidor MCP falha ao conectar e pede que você reinicie o Firefox com ambas as flags.

Aviso: Não deixe o Marionette habilitado durante a navegação normal. Ele define navigator.webdriver = true e altera outros sinais de impressão digital do navegador, o que pode acionar detecção de bots em sites protegidos por Cloudflare, Akamai, etc. Habilite o Marionette apenas quando precisar de automação MCP e reinicie o Firefox normalmente depois.

Visão geral das ferramentas

Consulte docs/tools.md para a lista completa de ferramentas por módulo, com descrições e parâmetros (gerados a partir do código-fonte).

• Páginas: list/new/navigate/select/close/get_page_text (get_page_text suporta saveTo opcional)
• Snapshot/UID: take/resolve/clear (take suporta saveTo opcional)
• Entrada: click/hover/fill/drag/upload/preenchimento de formulário
• Rede: list/get (ID-primeiro, filtros, captura sempre ativa; ambos suportam saveTo opcional)
• Downloads: list_downloads/clear_downloads (captura sempre ativa), set_download_behavior (allow/deny/default)
• Console: list/clear (list suporta saveTo opcional)
• Screenshot: page/por uid (com saveTo opcional para ambientes CLI)
• Script: evaluate_script (sandbox opcional para um realm isolado; saveTo opcional para resultados volumosos)
• Contexto Privilegiado: list/select contextos privilegiados ("chrome"), evaluate_privileged_script (requer MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• WebExtension: install_extension, uninstall_extension, list_extensions (list requer MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Gerenciamento do Firefox: get_firefox_info, get_firefox_output, restart_firefox
• Preferências do Firefox: get_firefox_prefs, set_firefox_prefs (requer MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Profiler: profiler_is_active, profiler_start (preset ou configuração explícita), profiler_stop (salva o perfil no diretório de downloads)
• Screencast: screencast_start (grava a viewport da página em um arquivo de vídeo no diretório de downloads), screencast_stop (requer Firefox 154+)
• Utilitários: accept/dismiss dialog, history back/forward, set viewport

Salvando saída volumosa em disco

Saída grande de ferramentas pode consumir contexto significativo em clientes CLI como Claude Code. As ferramentas screenshot_page, screenshot_by_uid, take_snapshot, list_console_messages, list_network_requests, get_network_request, get_page_text, evaluate_script e evaluate_privileged_script aceitam um parâmetro opcional saveTo que grava o resultado em um arquivo em vez de retorná-lo inline. saveTo assume uma de três formas:

• um caminho de arquivo (relativo ao diretório de trabalho atual, ou absoluto dentro de ~/.firefox-devtools-mcp; diretórios pai são criados)
• um diretório existente (um arquivo com timestamp é gerado dentro dele)
• true (um arquivo com timestamp é gerado sob ~/.firefox-devtools-mcp/output/)

A resposta retorna o caminho e o tamanho em bytes. O arquivo salvo sempre contém os dados completos, sem truncamento: as proteções de tamanho inline (limites de mensagens do console, truncamento de cabeçalhos de rede, limites de linhas de snapshot) nunca se aplicam a ele.

As ferramentas que produzem texto (todas exceto as capturas de tela) também aceitam preview, um número de caracteres da saída salva para ecoar inline como um pequeno trecho. Capturas de tela não têm pré-visualização.

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 padrão, os caminhos de salvamento são restritos: caminhos relativos são resolvidos em relação ao diretório de trabalho atual, e caminhos absolutos só são permitidos dentro de ~/.firefox-devtools-mcp. Caminhos que escapam desses locais são rejeitados. Inicie o servidor com --unrestricted-save-paths para gravar em locais arbitrários, incluindo caminhos absolutos fora desse diretório.

Os arquivos salvos podem então ser visualizados, por exemplo, com a ferramenta Read do Claude Code, sem impactar o tamanho do contexto.

Desenvolvimento 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 mais detalhes sobre desenvolvimento local, testes e CI.

Solução de problemas

• Firefox não encontrado: passe --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) ou o caminho correto no seu sistema operacional.
• A primeira execução é lenta: o Selenium configura a sessão BiDi; execuções subsequentes são mais rápidas.
• UIDs obsoletos: um UID permanece válido até que seu elemento seja removido ou a página navegue; tire um novo snapshot (take_snapshot) quando uma ferramenta de UID informar que um não existe mais.
• Windows 10: Erro durante a descoberta do servidor MCP 'firefox-devtools': Erro MCP -32000: Conexão fechada

  • Solução 1 Envolva com cmd /c (detalhes):

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

  • Solução 2 Use o caminho absoluto para npx (ajuste a extensão — .cmd, .bat, .exe ou .ps1 — para corresponder à sua configuração):

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

Versionamento

• API pré‑1.0: as versões começam em 0.x. Use @latest com npx para a versão mais recente.

Contribuição

Consulte CONTRIBUTING.md para saber como relatar problemas, executar testes e trabalhar no projeto localmente.

Autor

Mantido pela Mozilla.

Licença

Licenciado sob MIT ou Apache 2.0, à sua escolha.