MCP Browser Debugger
Servidor MCP avançado para debugging completo de frontend com análise de DOM, execução de JavaScript3. 🆕 Fluxo completo: Login e inspeção:
"Primeiro, verifique se o browser está aberto.
Se estiver fechado, abra o browser visível.
Depois faça login em https://meusite.com/login usando:
- Campo email: #email
- Campo senha: #password
- Botão: button.submit
- Email: meu@email.com
- Senha: minhasenha
Depois me mostre o DOM da página logada"
- Debugar uma página web:o de rede e muito mais.
Desenvolvido em TypeScript com padrões profissionais de código (ESLint + Prettier).
🚀 Funcionalidades
🌐 Controle do Browser
- open_browser: Abre o browser em modo VISÍVEL (headful) para você ver as ações do agent em tempo real
- login: Faz login automatizado e mantém a sessão ativa para inspeção
Navegação e Carregamento
- navigate: Navega para qualquer URL com controle de timeout e condições de espera
- get_page_info: Obtém informações completas sobre a página atual
Análise de DOM
- get_dom: Extrai o HTML completo do DOM
- get_element: Inspeciona elementos específicos com estilos computados
- query_selector_all: Busca múltiplos elementos por seletor CSS
- evaluate_xpath: Avalia expressões XPath
Código Fonte
- get_page_source: Extrai todo código fonte incluindo scripts e estilos
- execute_js: Executa JavaScript arbitrário no contexto da página
Debugging e Monitoramento
- get_console_logs: Captura todos os logs do console
- get_network_activity: Monitora todas as requisições HTTP
- screenshot: Captura screenshots da página ou elementos específicos
Interação
- click_element: Clica em elementos
- type_text: Digita texto em campos de input
Inspeção de Dados
- get_local_storage: Acessa localStorage
- get_cookies: Lista todos os cookies
📦 Instalação
npm install
npm run build
🛠️ Scripts Disponíveis
npm run dev # Desenvolvimento com ts-node
npm run start # Executa código compilado
npm run build # Compila TypeScript para JavaScript
npm run lint # Verifica código com ESLint
npm run lint:fix # Corrige problemas do ESLint automaticamente
npm run format # Formata código com Prettier
npm run format:check # Verifica formatação sem modificar
⚙️ Configuração no Claude Desktop
Adicione ao seu arquivo de configuração do MCP client:
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"browser-debugger": {
"command": "node",
"args": ["c:\\Users\\Emmanuel\\Desktop\\mcp\\mcp-browser\\dist\\index.js"]
}
}
}
Nota: Após qualquer alteração no código, execute npm run build antes de reiniciar o Claude Desktop.
🔧 Uso
⚠️ IMPORTANTE: Fluxo Correto para Evitar Perda de Sessão
SEMPRE siga esta ordem:
-
Primeiro: Verificar se browser está aberto
"Verifique se o browser está aberto" -
Se fechado: Abrir browser visível
"Abra o browser em modo visível" -
Fazer login (se necessário)
"Faça login em https://site.com/login usando..." -
Continuar usando SEM abrir browser novamente
"Navegue para...", "Me mostre o DOM", etc.
Exemplos de Comandos para o Agent
- 🆕 Verificar status do browser:
"Verifique se o browser está aberto"
- 🆕 Abrir browser visível:
"Abra o browser em modo visível e navegue para https://google.com"
- 🆕 Fluxo completo: Login e inspeção:
"Abra o browser visível, faça login em https://meusite.com/login usando:
- Campo email: #email
- Campo senha: #password
- Botão: button.submit
- Email: meu@email.com
- Senha: minhasenha
Depois me mostre o DOM da página logada"
- Debugar uma página web:
"Navegue para https://example.com e me mostre o DOM completo"
- Analisar erros de console:
"Navegue para https://meusite.com e me mostre todos os erros do console"
- Inspecionar elemento específico:
"Encontre o elemento com classe 'header' e me mostre seus estilos computados"
- Executar JavaScript customizado:
"Execute este código: document.querySelectorAll('img').length"
- Monitorar requisições de rede:
"Mostre todas as requisições HTTP que falharam (status 4xx ou 5xx)"
- Extrair código fonte:
"Me mostre todos os scripts inline e externos da página"
- Capturar screenshot:
"Tire um screenshot da página inteira"
🛠️ Ferramentas Disponíveis
1. get_browser_status ⭐ NOVO - USE PRIMEIRO!
Verifica se o browser está aberto ou fechado. SEMPRE use esta ferramenta antes de abrir um novo browser!
Parâmetros: Nenhum
Retorno:
isOpen: Browser está aberto?headless: Modo headless (invisível) ou headful (visível)?currentUrl: URL atual da páginapageTitle: Título da página atualmessage: Mensagem explicativa
Exemplo de uso:
"Verifique se o browser está aberto"
⚠️ Por que é importante:
- Se você abrir um browser que já está aberto, perderá a sessão de login!
- Use esta ferramenta para evitar loops infinitos
2. close_browser ⭐ NOVO
Fecha o browser e encerra a sessão.
Parâmetros: Nenhum
⚠️ ATENÇÃO:
- Isso irá perder todos os cookies, localStorage e sessões de login!
- Use apenas quando o usuário pedir explicitamente para fechar o browser
- Após fechar, você precisará usar
open_browserpara abrir novamente
Exemplo de uso:
"Feche o browser"
3. open_browser ⭐ NOVO
Abre o browser em modo VISÍVEL para você ver tudo que o agent está fazendo!
⚠️ ATENÇÃO: Use get_browser_status ANTES! Se o browser já estiver aberto, NÃO use esta ferramenta.
Parâmetros:
url: URL para abrir (opcional)headless: Se false, browser fica visível (padrão: false)width: Largura da janela (padrão: 1920)height: Altura da janela (padrão: 1080)
Exemplo de uso:
Passo 1: "Verifique se o browser está aberto"
Passo 2: Se fechado -> "Abra o browser visível em https://github.com"
4. login ⭐ NOVO
Faz login automatizado e mantém a sessão aberta para inspeção.
Parâmetros:
url(obrigatório): URL da página de loginusernameSelector(obrigatório): Seletor CSS do campo username/emailpasswordSelector(obrigatório): Seletor CSS do campo senhasubmitSelector(obrigatório): Seletor CSS do botão de submitusername(obrigatório): Username ou emailpassword(obrigatório): SenhawaitForSelector: Seletor para confirmar login bem-sucedido (opcional)timeout: Timeout em ms (padrão: 30000)delayAfterType: Delay após digitar, útil para SPAs (padrão: 500)
Exemplo de uso:
"Faça login em https://exemplo.com/login usando:
- Campo de email: input[name='email']
- Campo de senha: input[type='password']
- Botão: button[type='submit']
- Email: usuario@exemplo.com
- Senha: minhasenha123"
5. navigate
Navega para uma URL específica.
Parâmetros:
url(obrigatório): URL completawaitUntil: "load" | "domcontentloaded" | "networkidle0" | "networkidle2"timeout: Timeout em ms
6. get_dom
Extrai o HTML completo do DOM.
Parâmetros:
prettify: Formatar HTML (padrão: true)
7. get_element
Inspeciona um elemento específico.
Parâmetros:
selector(obrigatório): Seletor CSSincludeStyles: Incluir estilos computadosincludeAttributes: Incluir atributos
8. execute_js
Executa JavaScript no contexto da página.
Parâmetros:
code(obrigatório): Código JavaScriptreturnValue: Retornar valor da execução
9. screenshot
Captura screenshot.
Parâmetros:
selector: Elemento específico (opcional)fullPage: Página inteira com scrollpath: Caminho para salvar
10. get_console_logs
Recupera logs do console.
Parâmetros:
filterType: "all" | "log" | "error" | "warning" | "info"clear: Limpar logs após recuperação
11. get_network_activity
Recupera atividade de rede.
Parâmetros:
filterType: "all" | "request" | "response"clear: Limpar histórico
12. get_page_source
Extrai código fonte completo.
Parâmetros:
includeScripts: Incluir scriptsincludeStyles: Incluir estilos
13. query_selector_all
Busca múltiplos elementos.
Parâmetros:
selector(obrigatório): Seletor CSSlimit: Limitar resultados (padrão: 100)
14. get_page_info
Informações gerais da página.
15. click_element
Clica em um elemento.
Parâmetros:
selector(obrigatório): Seletor CSSwaitForNavigation: Aguardar navegação
16. type_text
Digita texto em input.
Parâmetros:
selector(obrigatório): Seletor CSStext(obrigatório): Texto a digitarclearFirst: Limpar antes de digitar
17. get_local_storage
Acessa localStorage.
18. get_cookies
Lista cookies.
19. evaluate_xpath
Avalia XPath.
Parâmetros:
xpath(obrigatório): Expressão XPath
🎯 Casos de Uso
Debugging de Aplicação React/Vue/Angular
1. Navegar para a aplicação
2. Capturar console logs e erros
3. Inspecionar componentes específicos
4. Executar JavaScript para verificar estado da aplicação
5. Monitorar requisições API
Análise de Performance
1. Navegar com networkidle0
2. Capturar todas as requisições de rede
3. Analisar tamanho de recursos
4. Verificar tempo de carregamento
Extração de Dados
1. Navegar para a página
2. Executar query_selector_all para elementos desejados
3. Executar JavaScript customizado para processar dados
4. Extrair informações específicas
Testes de UI
1. Navegar para a página
2. Interagir com elementos (click, type)
3. Verificar mudanças no DOM
4. Capturar screenshots de evidência
🔒 Segurança
- Browser executa em modo headless
- Sandbox desabilitado apenas para compatibilidade local
- Não armazena credenciais
- Logs são mantidos em memória e podem ser limpos
📝 Notas
- O browser é iniciado automaticamente na primeira ferramenta chamada
- Uma única instância de página é mantida entre chamadas
- Console logs e requisições de rede são acumulados entre navegações (use
clear: truepara limpar) - Screenshots podem ser salvos em disco ou retornados como base64