firefox-devtools-mcp

Firefox DevTools MCP

Servidor do Model Context Protocol que permite que agentes de IA usem o Firefox. Ele tem dois casos de uso principais:

• Navegação agêntica: o agente usa o navegador para tarefas comuns, como ler páginas, preencher formulários e percorrer fluxos de várias etapas em sites.
• Desenvolvimento web assistido por agente: o agente carrega a página em que você está trabalhando e a inspeciona com ferramentas de desenvolvedor, como console, requisições de rede, depurador e profiler.

Ele controla o Firefox por meio do WebDriver BiDi (via Selenium WebDriver) e 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 do Firefox dedicado. Nunca execute o servidor contra seu perfil normal — o agente tem acesso a tudo o que o navegador pode alcançar, 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 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 de como relatar 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 específico do Firefox. O Firefox é executado em uma subpasta firefox_devtools_mcp_profile desse caminho, marcada com um arquivo .firefox-devtools-mcp; apontar --profile-path para um perfil marcado o reutiliza diretamente
• --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 do Marionette para o modo conectar a 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 o modo Firefox para Android; o valor é o serial do dispositivo ADB (ex.: emulator-5554). Execute adb devices para listar os 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 de destino. 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.

Presets (cada um é um superconjunto do anterior):

• slim — o mínimo para navegar e interagir com páginas
• basic (padrão) — adiciona ferramentas para navegação regular
• developer — adiciona ferramentas para desenvolvedores web
• mozilla — adiciona ferramentas para desenvolvedores do Firefox
• all — todos os módulos

Consulte docs/tools.md para a lista de módulos e os módulos em cada preset.

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ê-la.

# 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 exigem MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 e estão disponíveis apenas no build interno da Mozilla. O módulo launch também exige o build interno da Mozilla: ele reinicia o Firefox sob um binário, perfil, ambiente e conjunto de preferências escolhidos pelo chamador, o que é uma mudança de configuração que o operador deve controlar. Use --pref, --firefox-path e as outras opções de linha de comando. O módulo bidi também exige o build interno da Mozilla: ele envia qualquer comando WebDriver BiDi, portanto dá acesso ao que os outros módulos expõem. O pacote público ignora esses módulos 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 ignorá-las 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 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. Também exige 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 de destino 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 ignorá-lo, depois executa a sessão em seu próprio perfil temporário, que é excluído em seguida. Por causa disso, --android-device exige --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.

# 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 a 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).

Salvando saída volumosa em disco

A saída grande de ferramentas pode consumir contexto significativo em clientes CLI como o Claude Code. Várias ferramentas aceitam um parâmetro opcional saveTo que grava o resultado em um arquivo em vez de retorná-lo inline. Consulte docs/tools.md para a lista. 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/output; os diretórios pai são criados). Caminhos que alcançam um perfil do Firefox, ou os arquivos que este servidor lê de volta, são recusados
• um diretório existente (um arquivo com carimbo de data/hora é gerado dentro dele)
• true (um arquivo com carimbo de data/hora é 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 salvaguardas 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 também aceitam preview, um número de caracteres da saída salva para ecoar inline como um pequeno trecho. A lista em docs/tools.md mostra quais ferramentas suportam isso.

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.

Contribuindo

Veja 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.