Setup MCP Puppeteer Server: Browser Automation with Claude 2026

Problem: Claude Can't Interact with Live Web Pages Without a Browser MCP

MCP Puppeteer server gives Claude the ability to navigate URLs, click elements, fill forms, take screenshots, and execute JavaScript in a real browser — without writing a single line of Puppeteer code yourself. If you've tried asking Claude to scrape a dynamic page or automate a multi-step web workflow and got nothing useful back, this is the missing piece.

You'll learn:

• Which Puppeteer MCP package to use in 2026 (the official one is deprecated)
• How to configure it for Claude Desktop, Claude Code CLI, and Cursor
• How to run your first browser automation task with natural language
• When to switch to Playwright MCP instead

Time: 20 min | Difficulty: Intermediate

Why the Official Package No Longer Works

The original @modelcontextprotocol/server-puppeteer package published by Anthropic has been deprecated and archived. The npm registry marks it as unsupported. If you find tutorials pointing there, they're outdated.

Two actively maintained replacements exist in 2026:

For most developers in 2026, Playwright MCP is the better long-term pick — it's actively maintained by Microsoft, supports all major browsers, and Claude Code documentation lists it first. This tutorial covers Puppeteer because you may need it for Chrome-specific workflows or stealth scraping, but the Playwright migration path is covered at the end.

Solution

Step 1: Verify Node.js Version

node --version

Expected: v18.0.0 or higher. Both Puppeteer MCP packages require Node 18+.

If it fails:

• command not found → Install Node.js from nodejs.org or via nvm install 20
• v16.x → Run nvm install 20 && nvm use 20

Step 2: Choose Your MCP Package

Pick based on your use case:

Option A — puppeteer-mcp-server (simple, no install required):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {}
    }
  }
}

Option B — puppeteer-mcp-claude (one-command installer for Claude Desktop + Claude Code):

# Installs and configures both Claude Desktop and Claude Code automatically
npx puppeteer-mcp-claude install

This detects your Claude apps, writes config files, and verifies the connection. Restart Claude after running.

Step 3: Configure Claude Desktop

Open your Claude Desktop config file:

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

Add the puppeteer server block. If mcpServers already exists, append inside it:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {
        "PUPPETEER_LAUNCH_OPTIONS": "{\"headless\": true}"
      }
    }
  }
}

Save the file, then fully quit and reopen Claude Desktop — the menu bar app icon must close, not just the window.

To run with a visible browser window (useful for debugging):

"PUPPETEER_LAUNCH_OPTIONS": "{\"headless\": false}"

Step 4: Configure Claude Code CLI

# Add puppeteer MCP server to Claude Code
claude mcp add puppeteer -- npx -y puppeteer-mcp-server

# Verify it's registered
claude mcp list

Expected output:

✓ puppeteer  connected

If it shows failed:

• Run claude mcp remove puppeteer then re-add
• Check that npx is on your PATH: which npx

Step 5: Configure Cursor

Go to Settings → MCP and paste:

{
  "puppeteer": {
    "command": "npx",
    "args": ["-y", "puppeteer-mcp-server"],
    "env": {}
  }
}

Verification

Restart your Claude client, then run these test prompts to confirm the tools are loaded:

Basic navigation and screenshot:

"Use the puppeteer tools to navigate to example.com and take a screenshot"

Form interaction:

"Open a browser, go to google.com, type 'Claude MCP' into the search box, and tell me the first 3 result titles"

JavaScript execution:

"Navigate to example.com and run document.querySelectorAll('a').length — how many links are on the page?"

You should see: Claude describe the browser opening, navigating, and returning real data from the live page. If you get a tool-not-found error, the server isn't connected — recheck Step 3 and fully restart the app.

Available Tools After Setup

Once connected, Claude has access to these Puppeteer MCP tools:

puppeteer_navigate       — Go to a URL
puppeteer_screenshot     — Capture the current page
puppeteer_click          — Click an element by CSS selector
puppeteer_type           — Type text into an input field
puppeteer_evaluate       — Execute JavaScript in browser context
puppeteer_get_text       — Extract text from a selector
puppeteer_wait_for_selector — Wait for an element to appear
puppeteer_scroll         — Scroll the page
puppeteer_new_page       — Open a new browser tab
puppeteer_close_page     — Close a tab
puppeteer_launch         — Launch a browser instance

Example of what Claude generates internally when you ask it to scrape pricing data:

// Navigate to the target page
await puppeteer_navigate({ pageId: "main", url: "https://example.com/pricing" });

// Wait for the pricing table to render (handles SPAs and lazy-loaded content)
await puppeteer_wait_for_selector({
  pageId: "main",
  selector: ".pricing-table"
});

// Extract the text content
const price = await puppeteer_get_text({
  pageId: "main",
  selector: ".pricing-table .price"
});

You never write this — Claude generates and executes it when you describe the task in plain English.

Running in Docker

For CI pipelines or server environments without a display:

{
  "mcpServers": {
    "puppeteer": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "-e", "DOCKER_CONTAINER=true",
        "ghcr.io/puppeteer/puppeteer:latest"
      ]
    }
  }
}

The DOCKER_CONTAINER=true flag disables the Chrome sandbox — required inside containers. Always pair it with:

"PUPPETEER_LAUNCH_OPTIONS": "{\"headless\": true, \"args\": [\"--no-sandbox\", \"--disable-setuid-sandbox\"]}"

Puppeteer MCP vs Playwright MCP

Migrate to Playwright MCP with one config swap:

# Claude Code CLI
claude mcp remove puppeteer
claude mcp add playwright -- npx @playwright/mcp@latest

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Playwright MCP reads the browser's accessibility tree instead of relying on CSS selectors — this makes it significantly more resilient when a site's markup changes.

What You Learned

• The official @modelcontextprotocol/server-puppeteer is deprecated — use puppeteer-mcp-server or puppeteer-mcp-claude instead
• npx puppeteer-mcp-claude install is the fastest path to configure both Claude Desktop and Claude Code at once
• PUPPETEER_LAUNCH_OPTIONS controls headless mode, sandbox flags, and custom Chrome paths
• For new projects, Playwright MCP is the better long-term choice — cross-browser support and active Microsoft maintenance

When NOT to use Puppeteer MCP: If you need Firefox or Safari coverage, or you're building E2E tests in CI on multiple browsers, use @playwright/mcp instead.

Tested on puppeteer-mcp-server 1.x, Node.js 20, macOS Sequoia 15 and Ubuntu 24.04

FAQ

Q: Does Puppeteer MCP work on Windows? A: Yes. The npx config works on Windows with no changes. For visible browser mode, set "headless": false in PUPPETEER_LAUNCH_OPTIONS. Use PowerShell or Windows Terminal — CMD can mishandle the JSON env string.

Q: What is the difference between puppeteer-mcp-server and puppeteer-mcp-claude? A: puppeteer-mcp-server is a standalone server you add manually to your config. puppeteer-mcp-claude includes an auto-installer (npx puppeteer-mcp-claude install) that detects Claude Desktop and Claude Code on your machine and writes both configs. puppeteer-mcp-claude also exposes 11 tools by default.

Q: How much RAM does the Puppeteer MCP server use? A: A headless Chromium instance typically uses 150–300MB RAM at rest. Each open page adds roughly 50–100MB. On a 4GB development machine it's manageable, but close other browser windows first.

Q: Can I use Puppeteer MCP and Playwright MCP at the same time? A: Yes. Add both under separate keys in mcpServers. Claude has access to both tool sets and picks the right one based on your request — useful if you want Puppeteer's Chrome stealth features alongside Playwright's cross-browser tools.

Q: Does this work with the free Claude.ai plan? A: MCP servers are a local config feature — they run on your machine and connect to Claude Desktop or Claude Code. They're not available inside the claude.ai web chat interface, regardless of plan tier.

Both packages are free and open source. Claude Desktop is free; Claude Code is included with Claude Pro at $20/month.