Puppeteer MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Tiny surface — 7 tools covers 90% of browser automation needs
Chromium only — fast install, no extra browser binaries
CSS-selector based — predictable, no learning curve if you know the DOM
Note: repo is archived; prefer playwright MCP for anything new

Demo ao vivo

Como fica na prática

puppeteer.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

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

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "puppeteer",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "puppeteer": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-puppeteer"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Puppeteer

Screenshot a list of URLs for a visual audit

👤 QA, designers, content managers ⏱ ~10 min beginner

Quando usar: You have a list of pages and need to eyeball them all after a change.

Fluxo

Navigate and capture

For each URL in [list], navigate, wait for load, take a full-page screenshot named <slug>.png.✓ Copiado

→ N screenshots saved
Diff against baseline (optional)

Compare each screenshot to the matching file in ./baseline/. Flag any that differ by more than 5% pixel diff.✓ Copiado

→ Changed-page list
Summarize findings

Write a 1-paragraph summary: how many pages, how many changed, which likely need review.✓ Copiado

→ Quick status you can paste into a PR description

Resultado: A baseline-ready screenshot set with a diff report, without setting up a visual regression pipeline.

Armadilhas

Dynamic content (dates, A/B banners) shows false diffs — Add puppeteer_evaluate to hide those elements via CSS before the screenshot

Combine com: filesystem

Fill a form repeatedly with test data

👤 QA engineers, backend devs testing input flows ⏱ ~15 min intermediate

Quando usar: You need to exercise a form with 20 variations of input to verify validation.

Pré-requisitos

Test environment URL — Never run against production — spin up a staging instance

Fluxo

Navigate to the form

Open https://staging.app/signup. Take a screenshot to confirm.✓ Copiado

→ Page loaded, form visible
Submit test cases

For each test case [list: {email, password, expected_error}], fill the fields, click submit, and capture the error message element's text.✓ Copiado

→ Per-case actual vs expected
Report mismatches

Summarize: which cases passed, which failed, what the gap was. Take a screenshot of each failure.✓ Copiado

→ Test report with evidence

Resultado: Validation coverage beyond what you'd write a Playwright spec for, in 10 minutes.

Armadilhas

Previous form state persists between runs — Call puppeteer_navigate to a fresh URL between cases, or explicitly clear fields with selector-based puppeteer_fill passing empty string

Find broken or missing images on a page

👤 Content/docs maintainers ⏱ ~10 min intermediate

Quando usar: Post-migration or after a CMS change — broken images are common and embarrassing.

Fluxo

Load the page

Open <URL>. Wait 2 seconds for lazy-loaded images.✓ Copiado

→ Page loaded
Find broken images via evaluate

Run page.evaluate to return every <img> where naturalWidth === 0 — those failed to load. Include src and alt for each.✓ Copiado

→ List of broken image sources
Repeat across the site

Repeat for these 20 URLs. Output a CSV of page, broken-img-src, alt-text.✓ Copiado

→ Actionable CSV

Resultado: A concrete fix-list of broken images with the page they appear on.

Armadilhas

Lazy-loaded images haven't triggered yet — Scroll the page first with window.scrollTo(0, document.body.scrollHeight) via evaluate, then wait and check

Combine com: filesystem

Combinações

Combine com outros MCPs para 10× de alavancagem

puppeteer + filesystem

Screenshot every page and save as image files for review

Open each URL in urls.txt, take a full-page screenshot, save to ./audit/<slug>.png.✓ Copiado

puppeteer + sentry

Reproduce a Sentry-reported error by replaying the user's path

Sentry issue WEB-3a91 has breadcrumbs showing the user clicked .checkout-btn then filled #card-number. Reproduce that in Puppeteer and capture the console.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
puppeteer_navigate	url	Open or redirect to a URL	free
puppeteer_screenshot	name, selector?, width?, height?	Capture the page or a specific element	disk space
puppeteer_click	selector	Click an element by CSS selector	free
puppeteer_fill	selector, value	Type into an input	free
puppeteer_select	selector, value	Choose an option from a <select>	free
puppeteer_hover	selector	Reveal hover-only menus or tooltips	free
puppeteer_evaluate	script	Run arbitrary JS in page context — last resort for anything selectors can't do	free

Custo e limites

O que custa rodar

Cota de API: Free — local execution
Tokens por chamada: Screenshots aren't tokens; selectors/strings are small (~100 tokens per call)
Monetário: Free
Dica: Use puppeteer_evaluate to extract exactly what you need as JSON — don't screenshot then OCR

Segurança

Permissões, segredos, alcance

Armazenamento de credenciais: Never put real-user credentials in prompts — use dedicated QA accounts

Saída de dados: Browser goes wherever you navigate it; nothing to the MCP publisher

Repo is archived — no new features or security fixes. Consider migrating to playwright MCP for anything production-adjacent.

Solução de problemas

Erros comuns e correções

Error: Element not found

Element hasn't rendered yet. Add a short wait via puppeteer_evaluate('await new Promise(r => setTimeout(r, 1000))') or use a more specific selector that waits implicitly.

Chromium fails to launch on Linux/Docker

Install dependencies: apt-get install -y chromium-browser or use the Playwright MCP image which has everything pre-installed.

Screenshots are blank

Page hasn't loaded. After navigate, wait for a known element: puppeteer_evaluate("document.querySelector('.main') !== null") in a poll loop before screenshotting.

Alternativas

Puppeteer vs. outros

Alternativa	Quando usar	Troca
Playwright MCP	Any serious browser automation — the strictly-better option	Slightly larger install, but better reliability via accessibility tree
Firecrawl MCP	You only need content extraction, not interaction	Hosted, costs credits, but handles anti-bot better
browser-tools MCP	You want to inspect YOUR real Chrome (with logged-in sessions, extensions)	Requires a Chrome extension; different use case entirely

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills