Puppeteer MCP Server: Complete 2026 Setup Guide for Claude Desktop & Claude Code

Table of Contents

1. What Is the Puppeteer MCP Server?
2. Puppeteer MCP vs Playwright MCP
3. Installing Puppeteer MCP
4. Your First Puppeteer Task
5. Real Workflows Worth Using
6. Comparison: Puppeteer MCP vs Alternatives
7. Performance & Memory Footprint
8. Security Considerations
9. Troubleshooting
10. Frequently Asked Questions

What Is the Puppeteer MCP Server?

The Puppeteer MCP server is a Model Context Protocol server published by modelcontextprotocol/servers that wraps Google's Puppeteer library. Once installed, it gives Claude (or any MCP client) a set of browser-control tools:

• puppeteer_navigate — load a URL
• puppeteer_click — click an element by selector
• puppeteer_fill — fill a form field
• puppeteer_select — choose from a dropdown
• puppeteer_screenshot — capture the current page
• puppeteer_evaluate — run arbitrary JavaScript in page context

In conversation, Claude composes these primitives into multi-step workflows. You ask "go to news.ycombinator.com and tell me the top 5 stories" and Claude calls puppeteer_navigate, then puppeteer_evaluate with a small DOM-querying script, then summarizes the result. You never see the Puppeteer code — only the answer.

This puts Puppeteer MCP in the same category as the Playwright MCP server and browser-use MCP. Different libraries, similar capability surface, slightly different tradeoffs.

Puppeteer MCP vs Playwright MCP

The two most popular browser MCPs are direct competitors. Here's how they actually differ in 2026:

• Browser support. Puppeteer = Chromium only. Playwright = Chromium, Firefox, WebKit. If you need cross-browser testing, Playwright wins by default.
• Install size. Puppeteer's bundled Chromium is ~150-200MB. Playwright bundles all three browsers and clocks in around 600-900MB. For one-off browser tasks, Puppeteer is significantly leaner.
• Auto-waits. Playwright has more aggressive built-in auto-waits — it'll wait for elements to be actionable before clicking. Puppeteer requires more explicit waits, which Claude usually handles correctly but sometimes flubs.
• Selector engine. Playwright supports its own custom selector syntax (text=, role=) on top of CSS. Puppeteer is pure CSS + XPath. Playwright's selectors tend to be more robust to layout changes.
• Memory footprint per session. Puppeteer = ~200-300MB per browser session. Playwright = ~250-400MB.
• Stealth. Both are detectable by anti-bot services out of the box. Both have community stealth plugins that close the gap somewhat.

For most Claude Desktop users who want quick browser automation without thinking about it, Puppeteer MCP is the simpler choice. If you're building a coding workflow that needs cross-browser testing, switch to Playwright MCP.

Installing Puppeteer MCP

The install is two lines of JSON for Claude Desktop or one shell command for Claude Code.

Claude Desktop Config

Open your config at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Add the Puppeteer server to the mcpServers object:

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

Save the file. Fully quit Claude Desktop (Cmd-Q on macOS), then relaunch. The first launch downloads a bundled Chromium binary — expect 30-60 seconds of background activity. Subsequent launches are instant.

If you need step-by-step setup help for Claude Desktop generally, see our full Claude Desktop MCP setup guide.

Claude Code Config

Claude Code's CLI is simpler — one command does the whole install:

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

Restart Claude Code (/exit then relaunch) and Puppeteer tools appear. Verify with claude mcp list — puppeteer should be in the output.

Your First Puppeteer Task

Open a fresh Claude Desktop conversation and try:

"Use Puppeteer to navigate to news.ycombinator.com and tell me the top 5 story titles."

Claude will:

1. Call puppeteer_navigate with https://news.ycombinator.com.
2. Wait for the page to render.
3. Call puppeteer_evaluate with a small script that pulls the top 5 story titles from the DOM.
4. Summarize the result in the chat.

The whole flow takes 3-5 seconds. You'll often see a "Used Puppeteer" indicator in the response — that's confirmation the MCP fired.

If it works, you have a working Puppeteer MCP install. If Claude says it can't access the web or doesn't have a browser tool, the MCP didn't load — check the troubleshooting section below.

Real Workflows Worth Using

The four workflows where Puppeteer MCP pays for itself daily:

• Live web research. "Search this term on Reddit and summarize the top 5 threads from the last week." Claude navigates, paginates, and reads results — faster than opening the browser yourself.
• Form-filling for repetitive tasks. "Open my project at app.linear.app, create a new issue titled X with body Y, assign to Z." Claude can replace 30 seconds of clicking with a 5-second prompt.
• Visual QA on your own apps. "Go to localhost:3000 and screenshot the homepage in dark mode at 1440px." Useful during development when you want a quick rendered check.
• Lightweight scraping with structured output. "Go to this product page and extract the price, review count, and rating into a JSON object." Pair with Filesystem MCP to dump the result to disk.

Heavier scraping (1000+ pages, anti-bot evasion) is better served by purpose-built scraping tools — but Puppeteer MCP excels at the conversational, one-off browser tasks that are too slow to do manually but too small to script.

Comparison: Puppeteer MCP vs Alternatives

Performance & Memory Footprint

Puppeteer MCP idles at near-zero — a Node process consuming ~50MB of RAM. When Claude invokes a browser task, the footprint spikes:

• First launch: 30-60s to download Chromium (cached after).
• Subsequent browser launches: ~1-3s to spawn a headless Chromium instance.
• Active browser session: 200-300MB RAM per browser, 5-15% CPU during active page rendering.
• Idle between tasks: Browser shuts down within ~5s of last interaction, dropping back to ~50MB.

For users running multiple MCPs simultaneously (Filesystem + GitHub + Slack + Puppeteer), the system stays responsive. The bottleneck under heavy use is your machine's RAM, not the MCP overhead.

If you run Claude Desktop on a 16GB machine and have 8+ MCPs configured, monitor Activity Monitor (macOS) or Task Manager (Windows). The browser-MCP processes are the most resource-hungry; everything else is negligible.

Security Considerations

Three real security concerns when running Puppeteer MCP:

1. Claude can navigate anywhere. There is no domain allowlist in the default config. If you ask Claude to browse to a sketchy URL, it will. Consider this when sharing the conversation context — links you don't expect to be visited may be visited.
2. The browser executes JavaScript. That includes any malicious scripts on visited pages. Puppeteer's headless mode reduces risk versus a full browser, but it's not a sandbox. Don't authenticate the browser to sensitive services unless you trust the workflow.
3. Screenshots can include sensitive data. If Claude takes a screenshot of a logged-in page, that screenshot ends up in the conversation. The image is sent through your AI provider and may be logged on their side. Avoid screenshot tasks on pages with PII unless you've reviewed your provider's data retention policy.

A safer setup: use Puppeteer MCP for public-internet research only, and don't authenticate the embedded browser to any service you care about. For authenticated workflows, use a separate browser instance you control directly.

Troubleshooting

Common errors and fixes:

• "Claude says it doesn't have browser access." The MCP didn't load. Check JSON syntax, fully quit Claude Desktop, restart. On Windows, verify npx is on the PATH.
• "Error: Failed to launch the browser process." Puppeteer can't find or download Chromium. On Linux, install Chromium dependencies (apt install libnss3 libatk-bridge2.0-0). On corporate networks, the Chromium download may be blocked — try setting PUPPETEER_EXECUTABLE_PATH to a system Chromium.
• First navigation hangs. Initial Chromium download takes 30-60s. Watch ~/.cache/puppeteer/chrome/ on macOS/Linux or %LOCALAPPDATA%\puppeteer\chrome on Windows for download progress.
• "Page never loaded." Some sites block headless browsers via Cloudflare or similar. The vanilla Puppeteer MCP doesn't include stealth — switch to a stealth-plugin variant or accept that protected sites are out of scope.
• High memory use over time. Browser processes occasionally leak when sessions aren't cleanly closed. Restart Claude Desktop every few days to clear them.

Most issues are config or network-related. The MCP itself is stable and well-maintained.

Frequently Asked Questions

What is the Puppeteer MCP server?

The Puppeteer MCP server is a Model Context Protocol server that wraps Google's Puppeteer browser automation library. It lets Claude Desktop, Claude Code, and other MCP clients control a headless (or headful) Chromium browser — navigating pages, clicking elements, filling forms, taking screenshots, and scraping content. It's published by the modelcontextprotocol organization on GitHub and ships as an npm package.

Is Puppeteer MCP better than Playwright MCP?

They overlap heavily, but each has strengths. Puppeteer MCP has a smaller footprint, faster install, and is excellent for Chromium-only workflows. Playwright MCP supports Chromium, Firefox, and WebKit; ships with stronger auto-waits and more robust selector handling; and has slightly better long-running session stability. For most users, either one works fine — pick Puppeteer if you want the lighter install, Playwright if you need cross-browser testing.

Does Puppeteer MCP need extra setup beyond npm install?

Minimal extra setup. The first time you run it, Puppeteer downloads a bundled Chromium binary (~150-200MB) into your npm cache. That happens automatically during the first MCP invocation. Subsequent restarts skip the download. No system-wide Chromium installation is required — Puppeteer ships its own.

Can Puppeteer MCP solve CAPTCHAs?

Not natively. The Puppeteer MCP exposes the browser primitives — navigate, click, type, screenshot — but doesn't include a CAPTCHA solver. For sites with reCAPTCHA, hCaptcha, or Cloudflare Turnstile, you'd need to layer a third-party solver service or use a stealth-mode wrapper like puppeteer-extra-plugin-stealth. The vanilla Puppeteer MCP will get blocked on heavily protected sites.

How is Puppeteer MCP different from a regular Puppeteer script?

A Puppeteer script is code you write and run yourself; the Puppeteer MCP is a JSON-RPC interface that lets an AI write and run those scripts on demand. The MCP exposes high-level tools like 'puppeteer_navigate', 'puppeteer_click', 'puppeteer_screenshot' — Claude calls those tools mid-conversation. You never write Puppeteer code; Claude composes the operations dynamically.

Will Puppeteer MCP slow down my computer?

Only when actively running a browser task. The MCP server itself idles at near-zero CPU. When you ask Claude to navigate or scrape, a headless Chromium process spawns and uses 200-500MB of RAM plus some CPU. The browser shuts down when the conversation moves on. Heavy parallel browser sessions are where you'd notice — but most conversational use is fine.

Can I use Puppeteer MCP in Claude Code?

Yes. Claude Code supports the same MCP spec as Claude Desktop. Install it with 'claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer' and restart Claude Code. The same browser tools become available to coding workflows — useful for testing your own apps, scraping API docs, or auditing rendered output.

Where can I find related browser-automation MCPs?

Skiln indexes all browser-automation MCPs in one place. Browse /mcps and filter by 'browser' or 'automation' tags. We track Puppeteer MCP, Playwright MCP, browser-use MCP, Selenium MCP, and several stealth variants — all with current install commands and trust scores.

Last updated: June 07, 2026 · Skiln tracks browser-automation MCPs across 13 source registries.