Puppeteer MCP — Use Cases, Install & Live Demo

Why use it

Key features

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

Live Demo

What it looks like in practice

puppeteer.replay ▶ ready

0/0

Install

Pick your client

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

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

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

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

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

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

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

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

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

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

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

Add to context_servers. Zed hot-reloads on save.

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

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Puppeteer

Screenshot a list of URLs for a visual audit

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

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

Flow

Navigate and capture

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

→ 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.✓ Copied

→ Changed-page list
Summarize findings

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

→ Quick status you can paste into a PR description

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

Pitfalls

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

Combine with: filesystem

Fill a form repeatedly with test data

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

When to use: You need to exercise a form with 20 variations of input to verify validation.

Prerequisites

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

Flow

Navigate to the form

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

→ 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.✓ Copied

→ Per-case actual vs expected
Report mismatches

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

→ Test report with evidence

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

Pitfalls

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

When to use: Post-migration or after a CMS change — broken images are common and embarrassing.

Flow

Load the page

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

→ 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.✓ Copied

→ List of broken image sources
Repeat across the site

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

→ Actionable CSV

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

Pitfalls

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 with: filesystem

Combinations

Pair with other MCPs for X10 leverage

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.✓ Copied

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.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
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

Cost & Limits

What this costs to run

API quota: Free — local execution
Tokens per call: Screenshots aren't tokens; selectors/strings are small (~100 tokens per call)
Monetary: Free
Tip: Use puppeteer_evaluate to extract exactly what you need as JSON — don't screenshot then OCR

Security

Permissions, secrets, blast radius

Credential storage: Never put real-user credentials in prompts — use dedicated QA accounts

Data egress: 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.

Troubleshooting

Common errors and fixes

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.

Alternatives

Puppeteer vs others

Alternative	When to use it instead	Tradeoff
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

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills