Puppeteer MCP Server

What Is It?

Puppeteer MCP is a Model Context Protocol server that gives Claude and other AI assistants direct control over a Chromium-based browser through natural language. Instead of writing browser automation scripts, you ask Claude to navigate, fill forms, take screenshots, or extract data—and it happens automatically.

The official Anthropic package is archived (as of 2025), but the MCP ecosystem is thriving with several actively maintained community implementations. This means Puppeteer MCP is deprecated from an official standpoint, but it’s far from dead—it’s the preferred choice for many Chromium-only automation workflows.

Who originally built it: Anthropic. Who maintains it now: Community developers like Xandon, jaenster, and merajmehrabi have kept active forks with improvements and bug fixes.

How It Works

The MCP wrapper sits between Claude and Puppeteer (a Node.js library that controls Chrome). You configure it in Claude Code or Claude Desktop, and Claude gets access to approximately 20 core browser automation tools (navigate, screenshot, fill, click, evaluate, etc.) depending on which community fork you use.

When you ask Claude to “navigate to amazon.com and take a screenshot,” the request flows like this:

1. Claude → MCP protocol → Puppeteer MCP server
2. Puppeteer launches a headless Chromium instance (or connects to an existing one)
3. Browser performs the action (navigate, click, fill, screenshot)
4. Result (image, text, JSON) → back to Claude

No code required. Claude handles the browser logic.

Getting Started

Installation

Option 1: Official package (deprecated but works)

npx -y @modelcontextprotocol/server-puppeteer

This uses the archived official package from Anthropic. It still works, but gets no updates.

Option 2: Community fork (recommended for production)

Pick one of the active forks:

npm install @xandon/puppeteer-mcp-server
# or
npm install jaenster/puppeteer-mcp-claude
# or another maintained fork

Option 3: Docker (no local dependencies)

If you want to avoid local dependencies, a community Docker image is available:

docker run -i --rm --init -e DOCKER_CONTAINER=true mcp/puppeteer

(This image is maintained by the community and may lag behind the latest fork updates.)

Configuration

Add to your Claude Code settings.json or Claude Desktop config:

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

Note: This example uses the official (archived) package for simplicity. For production, consider using @xandon/puppeteer-mcp-server or another active community fork listed in the Installation section above.

Requirements

• Node.js >= 18.0.0
• npm >= 8.0.0
• ~1 GB RAM per instance
• Linux/macOS/Windows (Linux requires system dependencies: X11 libs, fontconfig, etc.)

Puppeteer downloads Chromium automatically (~170–280 MB depending on OS).

Puppeteer MCP vs Playwright MCP

This is the decision you’ll face. Both are open-source, MCP-integrated browser automation servers. Here’s the honest breakdown:

Feature	Puppeteer MCP	Playwright MCP	Decision
Browser support	Chromium only	Chrome, Firefox, Safari, Edge	Playwright wins for cross-browser testing
LLM-friendly output	Screenshots (needs vision)	Accessibility trees (lower token cost)	Playwright wins for efficiency
Maintenance status	Deprecated (community-maintained)	Actively maintained by Microsoft	Playwright wins for stability
Setup difficulty	Simple (npx)	Simple (npx)	Tie
Performance	Fast (Chromium-only)	Fast (but slower on multi-browser)	Puppeteer slightly faster
Use Puppeteer if:	You only need Chrome/Chromium, screenshots are fine, you want simplicity	You need Firefox/Safari, want accessibility trees, need official support	—

The real question: Do you need screenshots or accessibility trees? If Claude can work with the DOM accessibility tree (what Playwright provides), you’ll save tokens and get more reliable results. But if the visual appearance matters or you’re testing visual UI, Puppeteer screenshots are simpler.

Recommendation: New projects should start with Playwright MCP. Puppeteer MCP remains viable for Chromium-only automation where the community forks stay active.

Real-World Use Cases

Screenshot Automation

Capture full-page or element-specific screenshots for visual testing, design QA, or monitoring layout changes.

@puppeteer Navigate to example.com, wait 2 seconds,
take a screenshot of the header element, and tell me
if the logo is visible.

Form Filling & Multi-step Workflows

Automate sign-ups, login sequences, checkout flows, or data entry—then capture confirmation pages.

@puppeteer Go to the contact form at example.com/contact,
fill in name="John", email="john@example.com",
message="Hello", click submit, wait for confirmation,
and extract the confirmation message.

JavaScript-Heavy Content Extraction

Wait for lazy-loaded content, execute JavaScript, and return structured data. Useful for SPAs, infinite-scroll feeds, and dynamic content.

@puppeteer Navigate to google.com, search for "AI tools",
scroll to load 10 results, execute JavaScript to extract
all titles and URLs, return as JSON.

Session Reuse & Authentication

Save login cookies, reuse them across tasks, avoid repeated authentication.

@puppeteer Use saved login cookies to navigate to
my.example.com/dashboard, extract today's analytics,
and return as JSON.

Limitations & Trade-offs

What doesn’t work:

• Cross-browser testing: Chrome/Chromium only. For Firefox/Safari, use Playwright MCP.
• Anti-bot detection: Headless Chrome can be flagged by Cloudflare, Instagram, LinkedIn. For protected sites, use Apify MCP or Firecrawl instead.
• CAPTCHA: No built-in solving. You’ll need external services or manual intervention.
• Vision dependency: Visual tasks (“click the red button”) often require Claude’s vision model, adding latency and token cost.
• Large-scale scraping: Each instance is a heavy process. Hundreds of concurrent pages will exhaust resources. Firecrawl or Apify are better for bulk scraping.

Known gotchas:

1. Stack size errors: Large base64 screenshots can crash the MCP connection.
2. Cloud platform timeouts: Render, Heroku time out long-running MCP requests (60–120 seconds). Intensive automation may fail.
3. Memory leaks: If browser instances aren’t properly closed, memory creeps up. Pin versions and monitor cleanup.
4. Deprecated status: The official package is archived. Community forks are active, but you depend on volunteer maintenance. Evaluate your risk tolerance before production use.

When to Use / When NOT to Use

Use Puppeteer MCP when:

• You only need to automate Chromium-based browsers (Chrome, Edge, Brave)
• Screenshots or visual inspection matter
• You want the simplest setup (npx install)
• You’re building MVP automation and willing to accept community-maintained code
• Headless automation is fine (no GUI needed)

Don’t use Puppeteer MCP when:

• You need Firefox/Safari support → use Playwright MCP
• Large-scale scraping (1000s of pages) → use Firecrawl or Apify
• Anti-bot-protected sites (Instagram, LinkedIn, Twitter) → use Apify MCP
• You need official, guaranteed long-term maintenance → use Playwright MCP
• Token efficiency is critical (accessibility trees beat screenshots) → use Playwright MCP

Similar Tools in the MCP Ecosystem

• Playwright MCP — Actively maintained by Microsoft. Multi-browser, accessibility trees, recommended for new projects.
• Apify MCP — Specialized scrapers for protected sites. High reliability, commercial support.
• Firecrawl — Modern web scraping platform. Returns markdown/JSON. LLM-optimized.
• Selenium MCP — Legacy enterprise choice. Limited MCP support.

Integration with Claude Code

1. Install via npx or community fork
2. Add to settings.json (see Configuration section above)
3. Restart Claude Code
4. Test: @puppeteer navigate to google.com and take a screenshot
5. Deploy in agent workflows or use interactively

The tool shows up as puppeteer_navigate, puppeteer_screenshot, puppeteer_fill, etc. Claude understands what each does.

The Deprecation Context

The official Anthropic package is archived, but this isn’t abandonment—it’s a statement: “The core MCP spec is stable enough that community can maintain this.” Dozens of teams run Puppeteer MCP in production without issues. The community forks are well-maintained and actively improved.

If you’re starting a new browser automation project:

• Chromium-only automation → Use Puppeteer MCP via active community fork
• Cross-browser or accessibility-first → Use Playwright MCP
• Protected sites or bulk scraping → Use Apify or Firecrawl

Puppeteer MCP is deprecated, not broken. Know the trade-offs, pick an active community fork, and you’re good to go.