Puppeteer MCP

What is Puppeteer MCP?

Puppeteer MCP is an MCP server for browser automation that exposes a single execute tool, which runs arbitrary JavaScript code with direct access to the Puppeteer Browser instance. It is designed for trusted local development with LLM assistants like Claude Code and Cursor.

How to use Puppeteer MCP?

Install globally via npm install -g pptr-mcp, then add the server to your MCP client configuration (e.g., Claude Desktop) using npx pptr-mcp as the command. Optionally pass custom Chrome flags or set environment variables like CHROME_PATH, PUPPETEER_EXECUTABLE_PATH, and PPTR_MCP_TIMEOUT. Use the execute tool with a code parameter (JavaScript string) and optional persistent boolean (default true) to reuse the browser session.

Key features of Puppeteer MCP

• Single execute tool runs arbitrary Puppeteer JavaScript code.
• Full Puppeteer API access within one round-trip call.
• Persistent browser session across calls (configurable).
• Supports custom Chrome flags (window size, proxy, etc.).
• Works as a Claude Code plugin via /plugin add.

Use cases of Puppeteer MCP

• Automating complex multi-step browser workflows in one call.
• Taking screenshots, scraping content, or filling forms with custom logic.
• Testing web applications by executing Puppeteer scripts from an LLM.
• Debugging and interacting with pages that require custom navigation or state.

FAQ from Puppeteer MCP

How is Puppeteer MCP different from other browser MCP servers?

Most browser MCP servers expose fixed tools (navigate, click, screenshot) requiring multiple round-trips. Puppeteer MCP uses a single execute tool that runs your own Puppeteer code, handling complex workflows in one call.

What are the security considerations?

This server is for trusted local development only. The Node.js VM isolates code for convenience, not security. Executed code has full browser control, Chrome runs with --no-sandbox for Docker compatibility, and persistent sessions preserve state across calls. Do not use in multi-tenant or untrusted environments.

What dependencies are required?

Puppeteer and a Chrome browser. The server will use the default Puppeteer-bundled Chromium unless CHROME_PATH or PUPPETEER_EXECUTABLE_PATH environment variables are set.

Can I reuse browser sessions across calls?

Yes. The persistent parameter defaults to true, preserving cookies and state across calls. Set persistent: false for session isolation.

What transport and authentication does it use?

The server communicates over stdio via the MCP protocol, as configured in the MCP client. No authentication is built in; it is intended for local use with trusted clients.