Chrome DevTools MCP Server

Um servidor MCP para desenvolvimento frontend assistido por IA usando o Chrome DevTools. Requer Google Chrome.

GitHub
5
Experimente este MCPPatrocinado

Documentação

Chrome DevTools MCP Server

License: MIT

Um servidor de controle Chrome DevTools baseado no Model Context Protocol (MCP), que fornece poderosos recursos de depuração de navegador para desenvolvimento front-end assistido por IA.

Recursos

Este projeto fornece um conjunto completo de ferramentas de controle do navegador Chrome, permitindo que a IA possa:

  • 🚀 Iniciar e controlar o navegador Chrome - Inicia automaticamente uma instância do Chrome para o ambiente de desenvolvimento
  • 🔗 Conectar-se remotamente ao CDP - Conecta-se a programas Chrome, Electron ou outros com núcleo V8 já em execução
  • 🔍 Consulta e análise de DOM - Obtém a estrutura da árvore DOM da página e consulta elementos específicos
  • 🌐 Monitoramento de requisições de rede - Captura e analisa em tempo real todas as requisições e respostas de rede
  • 📝 Captura de logs do Console - Obtém toda a saída do console, incluindo erros, avisos e logs
  • 💻 Execução de JavaScript - Executa qualquer código JavaScript no contexto da página
  • 🎯 Navegação de página - Controla a navegação do navegador para uma URL específica
  • 📸 Captura de tela - Captura a tela da página atual
  • ℹ️ Obtenção de informações da página - Obtém título, URL, metadados e outras informações da página
  • 🐛 Depuração com breakpoints em JavaScript - Define vários tipos de breakpoints, com suporte a breakpoints condicionais
  • 🎮 Controle de depuração - Operações de depuração como pausar, continuar, executar passo a passo, etc.

Parte 1: Desenvolvimento, instalação e inicialização

Requisitos de ambiente

  • Python 3.7+
  • Navegador Google Chrome
  • macOS/Linux/Windows

Etapas de instalação

  1. Clone o projeto:
git clone https://github.com/yourusername/chrome-devtool-mcp.git
cd chrome-devtool-mcp
  1. Crie um ambiente virtual (recomendado):
python -m venv venv
source venv/bin/activate  # macOS/Linux
# 或
venv\Scripts\activate  # Windows
  1. Instale as dependências:
pip install -r requirements.txt

Iniciar o servidor

Inicie o servidor com o seguinte comando:

python src/chrome_devtools_mcp.py

Ou use o script de inicialização:

./start.sh

O servidor será iniciado em http://localhost:12524.

Porta personalizada

Se precisar usar outra porta, altere o número da porta no script ou defina a variável de ambiente:

MCP_PORT=8080 python src/chrome_devtools_mcp.py

Parte 2: Guia de integração com Claude Code

Método 1: Usar o arquivo de configuração MCP

  1. Crie ou edite o arquivo de configuração MCP do Claude Code:

macOS/Linux:

mkdir -p ~/.config/claude/mcp
nano ~/.config/claude/mcp/chrome-devtools.json

Windows:

mkdir -p $env:APPDATA\claude\mcp
notepad $env:APPDATA\claude\mcp\chrome-devtools.json
  1. Adicione a seguinte configuração:
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "python",
      "args": ["/path/to/chrome-devtool-mcp/mcp_server.py"],
      "env": {}
    }
  }
}
  1. Reinicie o Claude Code para carregar a configuração.

Método 2: Iniciar com um agente já integrado

Se você já tem outros servidores MCP em execução, pode adicionar o servidor Chrome DevTools da seguinte forma:

  1. Modifique o arquivo de configuração MCP existente e adicione a configuração chrome-devtools:
{
  "mcpServers": {
    "existing-server": {
      // ... 现有配置
    },
    "chrome-devtools": {
      "command": "python",
      "args": ["/path/to/chrome-devtool-mcp/mcp_server.py"],
      "env": {}
    }
  }
}
  1. Ou use a abordagem de variáveis de ambiente:
export CLAUDE_MCP_CHROME_DEVTOOLS="python /path/to/chrome-devtool-mcp/mcp_server.py"
claude-code

Verificar a integração

No Claude Code, você pode verificar se as ferramentas foram integradas com sucesso da seguinte forma:

请列出所有可用的 MCP 工具

Você deve conseguir ver as seguintes ferramentas:

  • launch_chrome
  • connect_remote_chrome
  • connect_websocket_url
  • list_available_targets
  • navigate_to
  • get_dom_tree
  • query_elements
  • get_network_logs
  • get_console_logs
  • execute_javascript
  • take_screenshot
  • get_page_info
  • get_script_sources
  • get_script_source
  • search_in_scripts
  • get_page_functions
  • set_breakpoint
  • list_breakpoints
  • remove_breakpoint
  • get_paused_info
  • resume_execution
  • step_over
  • close_chrome

Parte 3: Guia de integração com Cursor

Método 1: Integração via arquivo de configuração (recomendado)

  1. Primeiro, certifique-se de que o servidor MCP está em execução: 
    python simple_mcp_server.py
# 服务器运行在 http://localhost:12524
  2. Abra as configurações do Cursor ( Cmd+, ou Ctrl+,)
  3. Pesquise por "Model Context Protocol" ou "MCP"
  4. Adicione na configuração MCP: 
    {
  "mcpServers": {
    "chrome-devtools": {
      "command": "python3",
      "args": ["/path/to/chrome-devtool-mcp/src/chrome_devtools_mcp.py"]
    }
  }
}
  5. Reinicie o Cursor para carregar as ferramentas MCP

Método 2: Configuração com variáveis de ambiente

Se precisar personalizar a porta ou o host:

  1. Defina as variáveis de ambiente e inicie o servidor: 
    MCP_PORT=8080 MCP_HOST=127.0.0.1 python src/chrome_devtools_mcp.py
  2. Use a porta correspondente na configuração do Cursor: 
    {
  "mcpServers": {
    "chrome-devtools": {
      "command": "python3",
      "args": ["/path/to/chrome-devtool-mcp/src/chrome_devtools_mcp.py"],
      "env": {
        "MCP_PORT": "8080",
        "MCP_HOST": "127.0.0.1"
      }
    }
  }
}

Verificar a conexão

Após a conexão bem-sucedida, você pode no Cursor:

  1. Use o símbolo @ para ver as ferramentas MCP disponíveis
  2. Ou pergunte "liste todas as ferramentas Chrome DevTools disponíveis"

Você deve conseguir ver as seguintes ferramentas:

  • launch_chrome
  • connect_remote_chrome
  • connect_websocket_url
  • list_available_targets
  • navigate_to
  • get_dom_tree
  • query_elements
  • get_network_logs
  • get_console_logs
  • execute_javascript
  • take_screenshot
  • get_page_info
  • get_script_sources
  • get_script_source
  • search_in_scripts
  • get_page_functions
  • set_breakpoint
  • list_breakpoints
  • remove_breakpoint
  • get_paused_info
  • resume_execution
  • step_over
  • close_chrome

Solução de problemas

Se não for possível conectar:

  1. Certifique-se de que o servidor está em execução: 
    curl http://localhost:12524/health
  2. Verifique as configurações do firewall e garanta que a porta 12524 esteja acessível
  3. Consulte os logs do servidor para obter informações detalhadas de erro
  4. Tente acessar http://localhost:12524/docs no navegador para ver a documentação da API

Exemplos de uso

Fluxo básico de uso

  1. Iniciar o Chrome:
使用 launch_chrome 工具启动一个 Chrome 浏览器实例
  1. Navegar para a página de destino:
使用 navigate_to 工具访问 http://localhost:3000
  1. Verificar a estrutura da página:
使用 get_dom_tree 工具获取页面的 DOM 结构
  1. Consultar elementos específicos:
使用 query_elements 工具查找所有 class 为 "button" 的元素
  1. Monitorar requisições de rede:
使用 get_network_logs 工具查看所有 API 请求
  1. Executar JavaScript:
使用 execute_javascript 工具在页面上执行 console.log('Hello from AI!')

Cenários avançados de depuração

Cenário 1: Depurar o estado de um aplicativo React

1. 启动 Chrome 并导航到 React 应用
2. 使用 execute_javascript 执行：
   window.__REACT_DEVTOOLS_GLOBAL_HOOK__.renderers.values().next().value.findFiberByHostInstance(document.querySelector('#root'))._debugOwner.stateNode.state
3. 分析返回的状态数据

Cenário 2: Monitorar e analisar chamadas de API

1. 清空网络日志
2. 触发应用中的某个操作
3. 使用 get_network_logs 筛选特定 API 端点
4. 分析请求和响应数据

Cenário 3: Análise de desempenho

1. 使用 execute_javascript 执行 performance.mark('start')
2. 执行一系列操作
3. 使用 execute_javascript 执行 performance.mark('end') 和 performance.measure('operation', 'start', 'end')
4. 获取性能数据

Cenário 4: Depurar o evento de clique do botão de login

1. 使用 connect_remote_chrome 连接到已运行的应用
2. 使用 query_elements 找到登录按钮选择器（如 '#login-btn'）
3. 使用 set_breakpoint('dom', '#login-btn') 在登录按钮上设置断点
4. 点击登录按钮，调试器会暂停
5. 使用 get_console_logs 查看控制台输出
6. 使用 get_paused_info 查看暂停位置和调用栈
7. 使用 resume_execution 继续执行

Cenário 5: Depurar um aplicativo Electron remoto

1. 启动 Electron 应用时添加 --remote-debugging-port=9222 参数
2. 使用 connect_remote_chrome('localhost', 9222) 连接
3. 使用各种调试工具进行分析
4. 设置断点并调试特定功能

Cenário 6: Alternar entre várias abas

1. 使用 list_available_targets() 列出所有可用的标签页
2. 选择目标标签页的 webSocketDebuggerUrl
3. 使用 connect_websocket_url(ws_url) 切换到该标签页
4. 现在所有操作都会在新的标签页上执行

Código de exemplo:

# 列出所有标签页
targets = list_available_targets()
# 选择第二个标签页
ws_url = targets['data']['targets'][1]['webSocketDebuggerUrl']
# 切换到该标签页
connect_websocket_url(ws_url)

Descrição detalhada das ferramentas da API

launch_chrome

Inicia uma instância do navegador Chrome, com suporte ao modo headless.

Parâmetros:

  • headless (bool): Se deve executar em modo headless, padrão false
  • port (int): Porta de depuração remota, padrão 9222

connect_remote_chrome

Conecta-se a uma instância remota do Chrome/Chromium (como aplicativos Electron).

Parâmetros:

  • host (str): Endereço do host remoto, padrão localhost
  • port (int): Porta de depuração remota, padrão 9222

connect_websocket_url

Conecta-se diretamente a uma sessão de depuração específica usando a URL WebSocket.

Parâmetros:

  • ws_url (str): URL do depurador WebSocket, como 'ws://localhost:9222/devtools/page/ABC123'

Casos de uso:

  • Alternar entre diferentes abas/páginas
  • Conectar-se a uma sessão de depuração específica
  • URL WebSocket obtida de outras ferramentas

list_available_targets

Lista todas as abas/páginas do Chrome disponíveis e suas URLs WebSocket.

Parâmetros:

  • host (str): Endereço do host do Chrome, padrão localhost
  • port (int): Porta de depuração do Chrome, padrão 9222

navigate_to

Navega para uma URL específica.

Parâmetros:

  • url (str): URL de destino

get_dom_tree

Obtém a estrutura da árvore DOM da página atual.

Parâmetros:

  • depth (int): Profundidade máxima da árvore DOM, padrão 3

query_elements

Consulta elementos DOM usando seletores CSS.

Parâmetros:

  • selector (str): Seletor CSS

get_network_logs

Obtém os logs de requisições de rede.

Parâmetros:

  • filter_url (str, opcional): Padrão de filtro de URL

get_console_logs

Obtém os logs do console.

Parâmetros:

  • level (str, opcional): Filtro de nível de log (error, warning, log, info)

execute_javascript

Executa código JavaScript no contexto da página.

Parâmetros:

  • code (str): Código JavaScript a ser executado

take_screenshot

Captura a tela da página atual.

Parâmetros:

  • full_page (bool): Se deve capturar a página inteira, padrão false

get_page_info

Obtém as informações básicas da página atual.

Sem parâmetros.

close_chrome

Fecha a instância do navegador Chrome.

Sem parâmetros.

set_breakpoint

Define breakpoints de JavaScript. Suporta breakpoints tradicionais e logpoints.

Parâmetros:

  • breakpoint_type (str): Tipo de breakpoint - 'dom', 'event', 'function', 'xhr', 'line', 'logpoint'
  • target (str): Alvo do breakpoint (como seletor DOM, nome de função, URL:número da linha)
  • options (dict, opcional): Opções adicionais
    • condition: Expressão condicional, só é acionada quando a condição é verdadeira
      • logMessage: Mensagem de log (para logpoints)
      • pause: Se deve pausar a execução (padrão: False para logpoint, True para outros)

Exemplos:

  • Breakpoint de DOM: set_breakpoint('dom', '#login-button')
  • Breakpoint de função: set_breakpoint('function', 'handleLogin')
  • Breakpoint de linha: set_breakpoint('line', 'app.js:42')
  • Breakpoint de XHR: set_breakpoint('xhr', '/api/login')
  • Logpoint: set_breakpoint('function', 'processData', {'logMessage': 'Processing data...', 'pause': False})
  • Logpoint condicional: set_breakpoint('function', 'validate', {'condition': 'value < 0', 'logMessage': 'Invalid value', 'pause': False})

list_breakpoints

Lista todos os breakpoints ativos.

Sem parâmetros.

remove_breakpoint

Remove o breakpoint especificado.

Parâmetros:

  • breakpoint_id (str): ID do breakpoint

get_paused_info

Obtém as informações quando o depurador está pausado.

Sem parâmetros.

resume_execution

Retoma a execução a partir do breakpoint.

Sem parâmetros.

step_over

Executa passo a passo, pulando a linha atual.

Sem parâmetros.

get_script_sources

Obtém a lista de todos os códigos-fonte JavaScript carregados na página atual.

Sem parâmetros.

Retorno:

  • scripts: Lista de scripts, contendo scriptId, url, startLine, endLine
  • count: Número total de scripts

get_script_source

Obtém o código-fonte de um script específico.

Parâmetros:

  • script_id (str): ID do script (obtido de get_script_sources)

search_in_scripts

Pesquisa funções, classes ou texto em todos os scripts carregados.

Parâmetros:

  • pattern (str): Padrão de pesquisa (como nome de função, nome de classe, texto)
  • search_type (str): Tipo de pesquisa - 'function', 'class', 'variable', 'text'

get_page_functions

Obtém todas as funções definidas na página.

Sem parâmetros.

Solução de problemas

O Chrome não inicia

  1. Certifique-se de que o Chrome está instalado
  2. Verifique se a porta 9222 está em uso: 
    lsof -i :9222  # macOS/Linux
netstat -an | findstr 9222  # Windows

Falha na conexão WebSocket

  1. Certifique-se de que o Chrome foi iniciado em modo de depuração
  2. Verifique as configurações do firewall
  3. Tente usar uma porta diferente

Ferramentas MCP não reconhecidas

  1. Certifique-se de que o servidor MCP está em execução
  2. Verifique se o caminho do arquivo de configuração está correto
  3. Reinicie o Claude Code ou o Cursor

Guia de contribuição

Sinta-se à vontade para enviar Issues e Pull Requests!

Licença

Este projeto é de código aberto sob a licença MIT.

Licença MIT - Consulte o arquivo LICENSE para obter mais detalhes.

Esta licença permite que você:

Desde que você:

  • 📄 Inclua o aviso de direitos autorais e a declaração de licença
  • 📝 Documente as alterações feitas (se houver modificações)