Puppeteer MCP

pptr-mcp

Servidor MCP para automação de navegador via Puppeteer. Diferente de outros MCPs de navegador que expõem ferramentas fixas (navegar, clicar, capturar tela), este servidor executa código JavaScript arbitrário com acesso direto à instância do navegador Puppeteer.

Diferença Principal

A maioria dos servidores MCP de navegador fornece um conjunto limitado de ações predefinidas. Essa abordagem exige múltiplas idas e voltas para fluxos de trabalho complexos e não consegue lidar com casos extremos.

pptr-mcp adota uma abordagem diferente: ele expõe uma única ferramenta execute que executa seu código JavaScript em uma VM Node.js com um global browser. Você escreve código Puppeteer diretamente, obtendo acesso completo à API em uma única chamada.

Traditional MCP (5 round-trips)         pptr-mcp (1 round-trip)
================================        ================================

  Agent           Server                  Agent           Server
    |                |                      |                |
    |-- navigate --->|                      |-- execute ---->|
    |<-- ok ---------|                      |                |
    |                |                      |   +------------------------+
    |-- waitFor ---->|                      |   | const page = await     |
    |<-- ok ---------|                      |   |   browser.newPage();   |
    |                |                      |   | await page.goto(url);  |
    |-- click ------>|                      |   | await page.click(s);   |
    |<-- ok ---------|                      |   | await page.type(i, t); |
    |                |                      |   | return await           |
    |-- type ------->|                      |   |   page.screenshot();   |
    |<-- ok ---------|                      |   +------------------------+
    |                |                      |                |
    |-- screenshot ->|                      |<-- result -----|
    |<-- image ------|                      |                |
    |                |                      |                |

Requisitos

• Node.js >= 20

Instalação

npm install -g pptr-mcp

Configuração do MCP

Adicione à configuração do seu cliente MCP (ex.: Claude Desktop):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp"]
    }
  }
}

Com opções de CLI:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp", "--no-headless", "--viewport=1080p"]
    }
  }
}

Com flags personalizadas do Chrome (após --):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "pptr-mcp",
        "--viewport=1280x720",
        "--",
        "--proxy-server=http://proxy:8080"
      ]
    }
  }
}

Opções de CLI

Opção	Descrição
--no-headless	Executar com janela do navegador visível
--viewport=VALUE	Definir tamanho da viewport (ex.: 1920x1080 ou 1080p)
--help, -h	Mostrar ajuda
-- [args]	Passar argumentos restantes para o Chrome

Opções desconhecidas antes de -- também são passadas para o Chrome.

Plugin do Claude Code

Instale como um plugin do Claude Code:

/plugin marketplace add iatsiuk/pptr-mcp
/plugin install pptr-mcp@pptr-mcp

Variáveis de Ambiente

Variável	Descrição
CHROME_PATH	Caminho para o executável do Chrome
PUPPETEER_EXECUTABLE_PATH	Alternativa ao CHROME_PATH
PUPPETEER_CACHE_DIR	Diretório de cache de download do navegador
PPTR_MCP_TIMEOUT	Tempo limite de execução em ms (padrão: 30000)

Ferramenta: execute

Executa código JavaScript com acesso ao navegador Puppeteer.

Parâmetros

Nome	Tipo	Padrão	Descrição
code	string	obrigatório	Código JavaScript a ser executado
persistent	boolean	true	Reutilizar sessão do navegador entre chamadas

Receitas

Desativar modo headless

Mostrar janela do navegador durante a execução:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp", "--no-headless"]
    }
  }
}

Diretório de perfil personalizado do Chrome

Use seu próprio perfil do Chrome com logins e cookies salvos:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp", "--", "--user-data-dir=/path/to/profile"]
    }
  }
}

Usar Chrome do sistema em vez do baixado

Por padrão, o pptr-mcp baixa o Chrome for Testing - uma versão otimizada e testada para o Puppeteer incluído. Para usar o Chrome do seu sistema em vez disso:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp"],
      "env": {
        "CHROME_PATH": "/path/to/chrome"
      }
    }
  }
}

Segurança

Este servidor é projetado para desenvolvimento local confiável com assistentes de LLM (Claude Code, Cursor, etc.). O código executado vem do LLM a seu pedido.

O que isso significa

• Não é uma sandbox: A VM Node.js isola o código por conveniência, não por segurança. Ela não é projetada para executar código não confiável.
• Controle total do navegador: O código executado pode navegar para qualquer URL, ler o conteúdo da página, tirar capturas de tela e interagir com aplicações web.
• Chrome roda sem sandbox: A flag --no-sandbox é usada para compatibilidade com Docker/containers.
• Sessões persistentes: Com persistent: true (padrão), cookies e estado do navegador são preservados entre chamadas. Use persistent: false para isolamento.

Não projetado para

• Implantações de servidor multi-tenant ou compartilhadas
• Executar código não confiável de fontes externas
• Construir serviços web que aceitam entrada arbitrária do usuário

Licença

WTFPL