Firefox DevTools MCP

Servidor 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 essenciais:

• Use um perfil Firefox dedicado. Nunca execute o servidor contra seu perfil normal — o agente tem acesso a tudo 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). Limite-se a sites que você controla ou nos quais confia.
• Ative 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 (detecção automática, ou passe --firefox-path)

Instalação e uso 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 argumentos
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Ou via variáveis de ambiente
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 argumentos
codex mcp add firefox-devtools -- \
  npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Ou via variáveis de ambiente
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
# Escolha Claude Code; o script salva o JSON no caminho correto

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 connect-existing, padrão 2828 ()

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 tem precedência 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, , ,

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 --tools explícita para removê-la.

# Use o preset developer (adiciona ferramentas de rede, console, depuração e profiler)
npx @mozilla/firefox-devtools-mcp --tool-preset developer

# Ative apenas os módulos que você precisa
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 descartou.

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 ignorá-las e ter uma configuração mais próxima de uma instância regular do Firefox.
• remote.log.level=Trace. Ative 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 com a mesma verbosidade.
• app.update.disabledForTesting=false. Permita 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 pular essa etapa, depois executa a sessão em seu próprio perfil temporário que é excluído em seguida. Por isso, --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 acompanha a adição de uma opção ao geckodriver para manter os dados existentes do aplicativo.

# Liste dispositivos conectados
adb devices

# Inicie o Firefox para Android no único dispositivo conectado
npx @mozilla/firefox-devtools-mcp --android-device auto --android-wipe-app-data

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

# Use o Firefox Nightly em vez disso
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:

# Inicie o Firefox com Marionette e o Remote Agent (BiDi)
firefox --marionette --remote-debugging-port

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

Ambas as flags são necessá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 ativado durante a navegação normal. Ele define navigator.webdriver = true e altera outros sinais de impressão digital do navegador, o que pode acionar a detecção de bots em sites protegidos por Cloudflare, Akamai, etc. Ative 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).

• Pages: list/new/navigate/select/close/get_page_text (get_page_text suporta saveTo opcional)
• Snapshot/UID: take/resolve/clear (take suporta saveTo opcional)
• Input: click/hover/fill/drag/upload/form fill/press_key/type_text
• Network: 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/by uid (com saveTo opcional para ambientes CLI)
• Script: evaluate_script (sandbox opcional para um realm isolado; saveTo opcional para resultados volumosos)
• Privileged Context: 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)
• Firefox Management: get_firefox_info, get_firefox_output, restart_firefox
• Firefox Preferences: get_firefox_prefs, set_firefox_prefs (requer MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)

Salvando saída volumosa em disco

A saída grande de ferramentas pode consumir contexto significativo em clientes CLI como o 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 aceita uma de três formas:

• um caminho de arquivo (relativo ao diretório de trabalho atual, ou absoluto dentro de ~/.firefox-devtools-mcp; os diretórios pai são criados)
• um diretório existente (um arquivo com carimbo de data/hora é gerado dentro dele)
• true (um arquivo com carimbo de data/hora é gerado em ~/.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 do 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 preview.

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

# Execute com Inspector contra o build local
npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720

# Ou execute em desenvolvimento com 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.
• 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; faça um novo snapshot (take_snapshot) quando uma ferramenta de UID relatar que um não existe mais.
• Windows 10: Erro durante a descoberta do servidor MCP 'firefox-devtools': MCP error -32000: Connection closed

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

    root@kitploit:~

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

Versionamento

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

Contribuindo

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.