firefox-devtools-mcp

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 na 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 dedicado do Firefox. Nunca execute o servidor com seu perfil habitual — o agente tem acesso a tudo que o navegador pode acessar, incluindo cookies e sessões salvas.
• Tenha cuidado com os sites que você visita. As páginas podem retornar conteúdo projetado para manipular o agente (injeção de prompt). Limite-se a sites que você controla ou confia.
• Evite habilitar flags extras a menos que necessário. --enable-script e --enable-privileged-context 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 — Claude Code CLI

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

Passe as 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 depois click_by_uid / fill_by_uid
• list_network_requests (captura sempre ativa), get_network_request
• 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 específico do Firefox
• --firefox-arg — argumentos extras do Firefox (repetível)
• --start-url — abrir esta URL ao iniciar (START_URL)
• --accept-insecure-certs — ignorar erros 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 (MARIONETTE_PORT)
• --pref name=value — definir preferência do Firefox na inicialização via moz:firefoxOptions (repetível)
• --enable-script — habilitar a ferramenta evaluate_script (executa JavaScript arbitrário no contexto da página) e ferramentas de depuração (listar scripts, inspecionar fonte, definir logpoints). Ferramentas de depuração requerem Firefox 153+. (ENABLE_SCRIPT=true)
• --enable-privileged-context — habilitar ferramentas de contexto privilegiado: listar/selecionar contextos privilegiados, avaliar scripts privilegiados, obter/definir preferências do Firefox e listar extensões. Requer MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device — habilitar o 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 depurar sessões 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

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 normal 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 para o geckodriver para que ambos os lados registrem logs com a 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 enabled
firefox --marionette

# Run the MCP server
npx @mozilla/firefox-devtools-mcp --connect-existing --marionette-port 2828

Ou defina marionette.enabled como true em about:config (ou user.js) para habilitar o Marionette em cada inicialização.

Recursos dependentes de BiDi (eventos de console, eventos de rede) não estão disponíveis no modo connect-existing; todos os outros recursos funcionam normalmente.

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 a detecção de bots em sites protegidos por Cloudflare, Akamai, etc. Habilite o Marionette apenas quando precisar de automação MCP e, em seguida, reinicie o Firefox normalmente.

Visão geral das ferramentas

• Páginas: list/new/navigate/select/close
• Snapshot/UID: take/resolve/clear
• Entrada: click/hover/fill/drag/upload/form fill
• Rede: list/get (ID‑first, filtros, captura sempre ativa)
• Console: list/clear
• Captura de tela: page/by uid (com saveTo opcional para ambientes CLI)
• Script: evaluate_script
• 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 (configuração predefinida ou explícita), profiler_stop (salva o perfil no diretório de downloads)
• Utilitários: accept/dismiss dialog, history back/forward, set viewport

Otimização de captura de tela para Claude Code

Ao usar capturas de tela no Claude Code CLI, os dados de imagem em base64 podem consumir um contexto significativo. Use o parâmetro saveTo para salvar as capturas de tela no disco:

screenshot_page({ saveTo: "/tmp/page.png" })
screenshot_by_uid({ uid: "abc123", saveTo: "/tmp/element.png" })

O arquivo pode então ser visualizado 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 após a navegação: tire um novo snapshot (take_snapshot) antes de usar ferramentas UID.
• 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: 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 registrar problemas, executar testes e trabalhar no projeto localmente.

Autor

Mantido pela Mozilla.

Licença

Licenciado sob MIT ou Apache 2.0, à sua escolha.