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 normal — o agente tem acesso a tudo que o navegador pode alcançar, incluindo cookies e sessões salvas.
• Tenha cuidado com os sites que 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. Predefinições mais altas como --tool-preset developer (script, depuração) e --tool-preset mozilla (contexto privilegiado) expandem significativamente o que o agente pode fazer.

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

Requisitos

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

Instalar e usar com Claude Code (npx)

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

Opção A — CLI do Claude Code

claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest

Passe opções como argumentos ou variáveis de ambiente. Exemplos:

# 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

Opção B — Editar o JSON de configurações do Claude Code

Adicione ao seu arquivo de configuração do Claude Code:

• macOS: ~/Library/Application Support/Claude/Code/mcp_settings.json
• Linux: ~/.config/claude/code/mcp_settings.json
• Windows: %APPDATA%\Claude\Code\mcp_settings.json

{
  "mcpServers": {
    "firefox-devtools": {
      "command": "npx",
      "args": ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "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 ao iniciar (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 predefinições. (TOOL_PRESET)
• --tools — lista explícita de módulos de ferramentas para habilitar, substituindo --tool-preset completamente (ex.: --tools pages network script). Consulte Módulos de ferramentas e predefinições.
• --enable-script — obsoleto, use --tool-preset developer ou --tools ... script debugging. Seleciona a predefinição de ferramentas developer. (ENABLE_SCRIPT=true)
• --enable-privileged-context — obsoleto, use --tool-preset mozilla ou --tools ... privileged prefs. Seleciona a predefinição 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-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)
• --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 predefinições

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

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

Predefinições (cada uma é um superconjunto da anterior):

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

# Use the developer preset (adds script and debugging 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 na build interna da Mozilla; o pacote público os ignora silenciosamente mesmo se solicitados.

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. Habilita 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. Permite 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.

# List connected devices
adb devices

# Launch Firefox for Android on the single connected device
npx @mozilla/firefox-devtools-mcp --android-device auto

# Target a specific device
npx @mozilla/firefox-devtools-mcp --android-device <serial>

# Use Firefox Nightly instead
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix

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

Conectar a um Firefox existente

Use --connect-existing para automatizar sua sessão de navegação real, 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 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 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

• 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/form fill
• 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/by 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, set_firefox_prefs, get_firefox_prefs
• Profiler: profiler_is_active, profiler_start (predefinição 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 saveTo opcional 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 pais 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ão permitidos apenas 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.

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.
• 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 relatar que um sumiu.
• Windows 10: Erro durante a descoberta do servidor MCP 'firefox-devtools': MCP error -32000: Connection closed

  • 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: 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.