ff-mcp-bridge
Controls a real Firefox browser through an extension, enabling tabs, navigation, page reading, clicks, typing, screenshots, JavaScript execution, console access, and network metadata.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
# ff-mcp-bridge
EN: A Firefox extension plus a local MCP server that lets an MCP client (e.g. Claude Code) control your real Firefox: tabs, navigation, page reading, clicks, typing, screenshots, JS, console and network metadata. Compatible with Claude Code via MCP.
PT-BR: Extensão do Firefox + servidor MCP local que permite a um cliente MCP (ex.: Claude Code) controlar o seu Firefox real, com seus logins.
Este projeto não é um produto da Anthropic e não é afiliado a ela.
Arquitetura
Claude Code ──stdio(MCP)──▶ server (Node) ──WebSocket 127.0.0.1:8765──▶ extensão Firefox
├─ background page (persistente)
└─ content script (por aba)Related MCP server: mcp-zen
Instalação (3 passos, tudo automático depois)
Clone este repositório e rode
npm install(Node >= 18; Firefox instalado).Registre no Claude Code para qualquer pasta (ajuste o caminho):
claude mcp add --scope user ff-mcp-bridge -- node D:\codigos\extensao-firefox\server\src\index.jsUse: peça ao Claude Code algo como "use ff-mcp-bridge para abrir example.com".
O que acontece sozinho na primeira chamada de ferramenta:
Se o Firefox com a extensão não estiver conectado, o servidor o abre (via
web-ext) num perfil dedicado e persistente em%USERPROFILE%\.ff-mcp-bridge\firefox-profile. Faça login nos seus sites nesse perfil uma vez; ele guarda os logins.A extensão pareia sozinha: busca o token no servidor local (
POST /pair, aceito só paraOrigin: moz-extension://). Não é preciso colar nada. O token das opções é só reserva.O Firefox continua aberto quando a sessão do Claude Code termina; na próxima, a extensão reconecta.
Variáveis de ambiente do servidor: FF_MCP_AUTOLAUNCH=0 (não abrir o Firefox), FF_MCP_FIREFOX (caminho do firefox.exe), FF_MCP_PROFILE (pasta do perfil), FF_MCP_HEADLESS=1, FF_MCP_PORT. Com porta diferente de 8765, informe a mesma porta nas opções da extensão.
Manual (sem auto-launch): npm run run:ext abre o Firefox com a extensão. A extensão é carregada como temporária, ou seja, só vale enquanto esse Firefox estiver aberto. Para instalação permanente: npx web-ext sign --channel=unlisted com chaves AMO suas.
Ferramentas
Tool | Descrição |
| Lista abas ( |
| Abre / fecha abas |
| Vai a uma URL, |
| Árvore de acessibilidade com |
| Até 20 elementos por role/nome/texto |
| Texto de |
|
|
| Define valor de input/textarea/select/checkbox/contenteditable |
| Executa JS ( |
| Console capturado desde o carregamento do content script |
| Metadados de rede via |
Todas aceitam tabId opcional (padrão: aba ativa).
Testes
npm run smoke # bridge sem Firefox
$env:MOZ_REMOTE_ALLOW_SYSTEM_ACCESS='1'; npm run e2e # Firefox headless + MCP real (precisa de Firefox instalado)
node scripts/e2e-autolaunch.mjs # sem nada aberto: o servidor abre o Firefox e a extensão pareia sozinha (usa a porta 8765)Segurança
O servidor escuta somente em
127.0.0.1(porta8765, mude comFF_MCP_PORT).O token autentica a extensão, e o
Originprecisa sermoz-extension://. Conexões inválidas são fechadas com código 4401.O auto-pareamento entrega o token a qualquer extensão do Firefox que consiga fazer
POSTem127.0.0.1:8765/pair. Páginas web não conseguem (oOrigindelas é rejeitado e a resposta não tem CORS). Uma extensão maliciosa já instalada teria acesso ao navegador de qualquer forma, mas se isso te preocupa, rode o servidor sem pareamento removendo a rota/paire use o token manual.A extensão tem
<all_urls>: ela acessa todas as abas. Quem controla o servidor controla o navegador. Não exponha a porta.Use um perfil dedicado do Firefox para automação.
O manifest declara
'unsafe-eval'na CSP para ojavascript_toolrodar no content script. Isso é aceitável para uso local, mas a AMO pode exigir revisão extra.
Limitações conhecidas
Eventos sintéticos (
isTrusted=false): falham em alguns sites (botões que exigem gesto real, captchas, alguns editores ricos).Sem API
debugger: sem emulação de dispositivo nem corpo de requisições.Páginas restritas (
about:,moz-extension:,addons.mozilla.org, visualizador de PDF) devolvem "Esta página não permite scripts (URL restrita do Firefox)".Só uma extensão conectada por servidor. Duas sessões do Claude Code simultâneas disputam a porta: use
FF_MCP_PORTdiferente e a mesma porta nas opções.Iframes não são percorridos pelo
read_page/find(all_frames: false).
Testado / não testado
Item | Estado |
| Testado: 7/7 passam |
| Testado: 0 erros; avisos sobre CSP |
| Testado: 17/17 passam (site local em 127.0.0.1 e example.com → clique no link até iana.org) |
Auto-launch do Firefox + auto-pareamento ( | Testado (~8s até a primeira resposta) |
Estado do badge ( | Testado lendo o estado da |
| Testado: |
Sessão real do Claude Code ( | Testado: terminou em |
DuckDuckGo, captchas, editores ricos | Não testado |
Roadmap
native messaging, múltiplas sessões, resize_window, gravação de GIF, grupo de abas.
Licença
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Unofficial Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables MCP clients to control a real local browser window for web automation tasks such as clicking, typing, scrolling, and taking screenshots.184 npm-
- AlicenseNot gradedqualityBmaintenanceLets MCP clients control a live Zen/Firefox browser to navigate, click, fill forms, screenshot, and execute JavaScript through a persistent server and browser extension.MIT
- AlicenseBqualityCmaintenanceEnables MCP clients to drive a real Chromium browser for automation, including navigation, JavaScript execution, CDP commands, network capture, and multi-tab control.7GPL 3.0
- AlicenseNot gradedqualityBmaintenanceMCP server for the Firefox you actually use: an add-on plus a small native helper, so an agent gets your real profile, tabs and logged-in sessions instead of a blank headless browser. 45 tools for tabs, accessibility snapshots with refs, clicking, typing, screenshots, bookmarks, history and downloads.9Mozilla Public 2.0