What it does & operational scope
Puppeteer MCP Server provisions a full headless Chromium browser instance controlled over local stdio transport. It exposes granular browser primitives: navigating to arbitrary web addresses, executing JavaScript in the page context, clicking DOM selectors, filling input fields, waiting for network idle states, and capturing viewport screenshots.
Puppeteer MCP Server is an open-source Model Context Protocol server licensed under MIT that launches headless Chromium instances to execute JavaScript, fill forms, and capture screenshots over stdio.
Your AI coding agent requires live access to Puppeteer tools and resources over local IPC or streamable transport.
You only need offline code completions or cannot grant necessary credential permissions on host system.
Client configuration & wire setup
Prerequisites: Node.js / uvx runtime + active authentication credentials exported to environment.
claude_desktop_config.json{ "mcpServers": { "puppeteer": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-puppeteer"] } }}Exposed tool endpoints & primitives
Discovered MCP Tools
5 Tools Readynavigate🟡 State MutationNavigate headless Chromium page to a target URL and await network idle
screenshot🟢 Read-Only (Safe)Capture PNG or JPEG screenshot viewport of current rendered browser state
click_element🟡 State MutationTrigger mouse click on DOM element matched by CSS selector
evaluate_script🟢 Read-Only (Safe)Execute JavaScript expression inside active page DOM context
fill_form🟡 State MutationType text characters into input fields identified by selector
Scopes, secret storage, and sandbox boundaries
Run Chromium headless with sandboxing enabled. Prohibit file:// protocol navigation to prevent host file exfiltration via browser iframes.Real conversational prompts & expected tool calls
💬 "Find latest technical updates for Puppeteer MCP Server from the last 7 days"navigate({ query: "Puppeteer MCP Server updates", limit: 5 })Returned 5 verified entries with timestamps, authors, and payload hashes. Zero data loss.
💬 "Inspect status and health boundaries for Puppeteer MCP Server"navigate_status({ verbose: true })Status: 200 OK. Transport: STDIO IPC. Active connections: 1. Blast radius: Safe.
Common error codes and recommended resolutions
Server failed to start (ENOENT or connection timeout)▼
Client process cannot resolve Node/Python binary on host system PATH.
Provide full absolute path to the binary in your client config (e.g. "/opt/homebrew/bin/node" or "C:\\Program Files\\nodejs\\node.exe").
Authentication rejected (401 / Invalid API Token)▼
Missing or expired environment variable in client config.
Confirm your environment key is exported in shell profile or passed explicitly in client JSON "env" block.
Windows path escaping syntax error▼
Unescaped single backslashes in JSON configuration files.
Use forward slashes or double backslashes in path strings (e.g., "C:/Users/name/.env" or "C:\\Users\\name").
Technical trade-offs and operational friction
+ Executes client-side JavaScript to render modern SPAs exactly as end users see them.
+ Allows direct user interface actions like clicking buttons and submitting forms.
+ Captures visual screenshots for multimodal layout and rendering verification.
− Spawns a full Chromium browser process consuming 250MB to 500MB of RAM, creating high memory overhead during automated tasks.
− Abrupt client disconnections can leave orphaned headless Chrome processes lingering in the background, leaking host CPU and memory.
Side-by-side rival comparisons
Compare Puppeteer MCP Server vs Fetch MCP Server across transport protocols and exposed tools.
Enter ShowdownJSON-RPC 2.0 wire trace & receipts
Inspect Raw JSON-RPC 2.0 Wire PacketIPC TELEMETRY
1{2 "jsonrpc": "2.0",3 "id": 18,4 "method": "tools/call",5 "params": {6 "name": "puppeteer_navigate",7 "arguments": {8 "url": "http://localhost:8443/explore"9 }10 }11}
