Servidor MCP Puppeteer Real Browser

Dê a um assistente de IA compatível com MCP um navegador Chrome local que ele possa abrir, navegar, ler e controlar.

Em manutenção: Este projeto ainda está em mudança. O branch main pode estar mais novo que o pacote publicado no npm. O selo npm acima mostra a versão publicada usada pelo @latest.

O que ele faz

Este pacote roda como um servidor local Model Context Protocol (MCP). Seu cliente MCP inicia o servidor, e o servidor inicia um processo Chrome para automação de navegador.

Principais recursos:

Abre um navegador visível por padrão, com modo headless opcional
Navega por páginas e lê HTML ou texto
Encontra elementos, clica, digita, espera e rola
Usa rebrowser-puppeteer-core e um pequeno conjunto de configurações anti-detecção
Detecta Chrome no Windows, macOS e Linux
Suporta caminho personalizado do Chrome, proxy e perfil de automação dedicado
Rastreia o processo exato do Chrome que inicia e fecha apenas esse processo
Impõe um fluxo de trabalho de conteúdo primeiro antes da interação com a página

Nenhuma automação de navegador é invisível. Os sites ainda podem detectá-la ou bloqueá-la.

Segurança e limites atuais

Leia isto antes de usar o servidor:

Use-o apenas em sites que você tem permissão para automatizar.
Revise as chamadas de ferramentas antes de aprovar logins, formulários, compras, downloads ou outras ações sensíveis.
As ferramentas de navegador e arquivo rodam com suas permissões normais de usuário.
O servidor suporta uma sessão de navegador por vez.
solve_captcha é atualmente um espaço reservado. Ele não usa um serviço de resolução de CAPTCHA. A inicialização do navegador apenas faz uma tentativa de melhor esforço de clique em widgets Turnstile detectados.
save_content_as_markdown é listado pelo servidor, mas o validador de fluxo de trabalho atual o bloqueia. Este é um problema de código conhecido.

Requisitos

Node.js 18 ou mais recente
npm e npx (incluídos com o instalador normal do Node.js)
Google Chrome ou Chromium
Um cliente MCP que possa iniciar um servidor stdio local

O Claude Desktop está disponível no macOS e Windows. Outros clientes MCP podem usar este servidor no Linux.

Início rápido

Você não precisa instalar este pacote globalmente. npx pode baixar e executar o pacote publicado quando seu cliente MCP precisar dele.

A opção -y evita que uma pergunta de instalação do npm bloqueie o servidor MCP enquanto ele inicia.

Claude Desktop

Abra Claude Desktop → Configurações → Desenvolvedor → Editar Configuração.
Adicione este servidor dentro de mcpServers:

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": [
        "-y",
        "puppeteer-real-browser-mcp-server@latest"
      ]
    }
  }
}

Salve o arquivo.
Saia completamente do Claude Desktop e abra-o novamente.

O Claude Desktop armazena este arquivo aqui:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Consulte o guia oficial de servidor MCP local para as etapas atuais do Claude Desktop.

Claude Code

Execute:

claude mcp add --transport stdio puppeteer-real-browser \
  -- npx -y puppeteer-real-browser-mcp-server@latest

Depois verifique a conexão:

claude mcp get puppeteer-real-browser

Dentro do Claude Code, /mcp também mostra o status do servidor.

O escopo padrão é local ao projeto atual. Adicione --scope user antes do nome do servidor se quiser o servidor em todos os seus projetos. Consulte o guia oficial de MCP do Claude Code para detalhes de escopo.

Cursor

Crie .cursor/mcp.json em um projeto, ou ~/.cursor/mcp.json para todos os projetos:

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": [
        "-y",
        "puppeteer-real-browser-mcp-server@latest"
      ]
    }
  }
}

Reinicie o Cursor após salvar o arquivo. Consulte o guia oficial de MCP do Cursor para locais e formatos de configuração atuais.

Outros clientes MCP

Use um servidor stdio local com este comando e lista de argumentos:

command: npx
args: -y puppeteer-real-browser-mcp-server@latest

O servidor se comunica por entrada padrão e saída padrão. Seu cliente MCP deve manter o processo aberto enquanto usa as ferramentas.

Teste a configuração

Pergunte ao seu assistente de IA:

Inicie o navegador, abra https://example.com, leia o texto da página e depois feche o navegador.

A ordem esperada das ferramentas é:

browser_init → navigate → get_content → browser_close

Ferramentas disponíveis

O servidor expõe 11 ferramentas.

Ferramenta	Finalidade	Entrada necessária
`browser_init`	Iniciar ou reutilizar a sessão gerenciada do Chrome	Nenhuma
`navigate`	Abrir uma URL	`url`
`get_content`	Ler HTML/texto da página inteira ou selecionado	Nenhuma
`find_selector`	Encontrar um seletor CSS a partir do texto do elemento	`text`
`click`	Clicar em um elemento	`selector`
`type`	Limpar e digitar em um campo de entrada	`selector`, `text`
`wait`	Aguardar um seletor, navegação ou tempo	`type`, `value`
`random_scroll`	Rolar com tempo e distância variados	Nenhuma
`solve_captcha`	Retornar um resultado de tentativa de espaço reservado	`type`
`save_content_as_markdown`	Salvar como `.md`; atualmente bloqueado	`filePath`
`browser_close`	Fechar o navegador gerenciado e redefinir o estado do fluxo de trabalho	Nenhuma

Fluxo de trabalho de conteúdo primeiro

O servidor bloqueia interação cega. Use esta ordem:

browser_init → navigate → get_content → find_selector → click or type

Após uma nova navegação, chame get_content novamente antes de clicar ou digitar. Você pode chamar wait após a navegação quando uma página carrega conteúdo lentamente.

Configuração do navegador

As opções do navegador são entradas para browser_init. Elas não são configurações de nível superior do servidor MCP.

Opção	Significado
`headless`	Defina `true` para ocultar a janela do navegador. Padrão: `false`.
`proxy`	URL do proxy, como `http://proxy.example.com:8080`.
`profilePath`	Caminho do perfil de automação dedicado.
`disableXvfb`	Defina `false` para iniciar o Xvfb no Linux.
`connectOption.timeout`	Tempo limite de conexão e configuração em ms.
`connectOption.slowMo`	Atrasar operações em ms.
`customConfig.chromePath`	Caminho absoluto para um executável do Chrome.
`customConfig.chromeFlags`	Sinalizadores personalizados; substitui a lista de sinalizadores do servidor.
`contentPriority`	Configurações de sugestão de prioridade de conteúdo.

contentPriority é um objeto com valores Booleanos prioritizeContent e autoSuggestGetContent. Ele muda as sugestões, mas não remove o fluxo de trabalho obrigatório de conteúdo primeiro.

Exemplo de solicitação:

{
  "headless": true,
  "proxy": "http://proxy.example.com:8080",
  "connectOption": {
    "timeout": 60000,
    "slowMo": 100
  },
  "customConfig": {
    "chromePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  }
}

Caminho do Chrome

O servidor primeiro verifica estas variáveis de ambiente:

CHROME_PATH
PUPPETEER_EXECUTABLE_PATH

Se nenhuma apontar para um arquivo, o servidor verifica locais comuns do Chrome e Chromium. No Windows, ele também verifica o registro e caminhos portáteis comuns.

Você pode definir CHROME_PATH na configuração do cliente MCP:

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": [
        "-y",
        "puppeteer-real-browser-mcp-server@latest"
      ],
      "env": {
        "CHROME_PATH": "/absolute/path/to/chrome"
      }
    }
  }
}

PROXY_URL não é uma variável de ambiente suportada. Passe um proxy para browser_init em vez disso.

Proteção de propriedade do navegador

O servidor mantém o identificador exato do launcher e o ID do processo para o processo Chrome que ele inicia. Fechamento normal, falha de inicialização, tempo limite, desconexão MCP e desligamento por sinal fazem a limpeza por meio desse identificador. Ele não procura ou fecha o Chrome pelo nome do processo.

Por segurança, o servidor rejeita configurações que possam anexar a outro navegador ou assumir a propriedade de um perfil pessoal do Chrome:

customConfig.userDataDir
customConfig.port
customConfig.portStrictMode
customConfig.handleSIGINT
connectOption.browserURL
connectOption.browserWSEndpoint
connectOption.transport
--remote-debugging-port, --remote-debugging-pipe e --user-data-dir dentro de sinalizadores personalizados do Chrome

Use profilePath para dados persistentes de automação. O diretório deve ser absoluto e vazio ou já marcado como de propriedade deste servidor.

Solução de problemas

O servidor MCP não aparece

Verifique se as ferramentas estão instaladas:
```
node --version
npm --version
npx --version
```
Verifique se o Node.js é versão 18 ou mais recente.
Verifique se o arquivo JSON não tem vírgulas ou aspas ausentes.
Saia completamente e reabra o cliente MCP.
Se um aplicativo de desktop não conseguir encontrar npx, use seu caminho absoluto como command. Execute which npx no macOS/Linux ou where npx no Windows para encontrá-lo.

Os logs do Claude Desktop são armazenados aqui:

macOS: ~/Library/Logs/Claude
Windows: %APPDATA%\Claude\logs

Chrome não é encontrado

Encontre o executável real do Chrome e defina CHROME_PATH na configuração do cliente MCP. Exemplos comuns são:

Windows: C:/Program Files/Google/Chrome/Application/chrome.exe
macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
Linux: /usr/bin/google-chrome ou /usr/bin/chromium

Não execute o cliente MCP como Administrador nem use sudo npm install -g apenas para resolver um problema de caminho do Chrome.

O servidor parece travado quando executado em um terminal

Isso pode ser normal. Um servidor MCP stdio aguarda mensagens de protocolo de um cliente MCP. Use o MCP Inspector em vez de digitar no processo.

Teste o pacote publicado:

npx -y @modelcontextprotocol/inspector \
  npx puppeteer-real-browser-mcp-server@latest

Consulte o guia oficial do MCP Inspector para detalhes de uso.

Uma ação de página está bloqueada

Siga o fluxo de trabalho obrigatório:

browser_init
navigate
get_content
find_selector quando você precisar de um seletor
click ou type

Se a página mudou, chame get_content novamente.

Uma conexão de navegador expira

Verifique se o caminho do Chrome existe.
Feche o navegador gerenciado atual com browser_close e inicie-o novamente.
Aumente connectOption.timeout na entrada browser_init.
Verifique se o software de segurança está bloqueando o processo filho do Chrome.
Inclua a mensagem de erro completa ao relatar o problema.

Obter ajuda

Pesquise ou abra uma issue no GitHub. Inclua:

Sistema operacional
Versões do Node.js e npm
Nome e versão do cliente MCP
Versão do Chrome e caminho do executável
Mensagem de erro completa
Etapas exatas que reproduzem o problema

Não inclua senhas, cookies, tokens ou conteúdo privado de páginas.

Desenvolvimento

Executar a partir do código-fonte

git clone https://github.com/withLinda/puppeteer-real-browser-mcp-server.git
cd puppeteer-real-browser-mcp-server
npm ci
npm run build

Teste o build local com o MCP Inspector:

npx -y @modelcontextprotocol/inspector node dist/index.js

Para usar o build local em um cliente MCP, use um caminho absoluto:

{
  "mcpServers": {
    "puppeteer-real-browser-local": {
      "command": "node",
      "args": [
        "/absolute/path/to/puppeteer-real-browser-mcp-server/dist/index.js"
      ]
    }
  }
}

Estrutura do projeto

src/index.ts                     MCP stdio server and request handlers
src/tool-definitions.ts          Tool names and input schemas
src/browser-manager.ts           Browser state, detection, and configuration
src/managed-browser-session.ts   Owned Chrome launch and cleanup
src/handlers/                    Tool implementations
src/*.test.ts                    Unit and regression tests
test/integration/                MCP protocol integration tests
test/e2e/                        Real-browser tests
test/safety/                     Browser cleanup safety guard
scripts/check-packaged-server.ts Package smoke test

Fluxo de trabalho de teste

Use TDD para mudanças de comportamento: escreva um teste que falha, faça-o passar e depois limpe o código.

# Browser cleanup safety guard
npm run test:safety

# Fast source tests
npm run test:unit

# MCP protocol integration tests
npm run test:integration

# Build the package
npm run build

# Test the built npm package shape and stdio lifecycle
npm run test:package:smoke:built

# Real Chrome tests
npm run test:e2e

# Release-focused automated checks
npm run test:all

Durante o TDD, use npm run test:watch. Antes de executar testes de navegador real, anote os processos Chrome já abertos na sua máquina. Após o teste, verifique se apenas o processo Chrome iniciado pelo teste foi fechado.

Contribuindo

Issues e pull requests são bem-vindos. Para uma mudança de código:

Crie um branch focado.
Adicione um teste que falha para um comportamento.
Faça a menor mudança de código que passe no teste.
Refatore enquanto os testes permanecem verdes.
Execute as verificações de segurança, fonte, build e pacote.
Explique a causa raiz, solução, prevenção e verificação na mensagem do commit.

Licença

Este projeto usa a Licença MIT.

Agradecimentos

A implementação original e a API pública foram baseadas em puppeteer-real-browser por ZFC Digital. O código-fonte atual substitui essa dependência de runtime em fim de vida por um launcher gerenciado interno construído a partir de chrome-launcher, rebrowser-puppeteer-core e ghost-cursor.

Puppeteer Real Browser

Documentação