Puppeteer MCP ServerFeatured

What is Puppeteer MCP Server?

Puppeteer MCP Server is the original Model Context Protocol reference server that lets an AI assistant drive a real Chromium browser with Puppeteer: navigate pages, click, fill forms, take screenshots and run JavaScript. It is now archived and its npm package is marked unsupported.

The server was published by the Model Context Protocol project as @modelcontextprotocol/server-puppeteer and lived in the modelcontextprotocol/servers repository. It has since been moved to modelcontextprotocol/servers-archived, which states that the archived servers are no longer maintained and come with no security guarantees. The package still installs and runs, so many existing setups and tutorials use it, but for new projects an actively maintained browser server is usually the better choice (see the alternatives below).

How to use Puppeteer MCP Server?

Prerequisites: Node.js (for npx) or Docker. No API key or account is needed; the browser runs on your own machine.

The README documents two ways to run the Puppeteer MCP server:

• NPX opens a visible browser window on your desktop.
• Docker (mcp/puppeteer image) runs headless Chromium inside a container.

NPX configuration (the same block shown on this page):

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

Docker configuration:

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

Claude Code

Register the stdio server with the Claude Code CLI:

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

Claude Desktop

Add either JSON block above to claude_desktop_config.json under mcpServers, then restart Claude Desktop.

Cursor

Cursor reads the same mcpServers format. Put the NPX block in ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project).

VS Code

The README provides one-click install links for NPX and Docker. For manual setup, add the server to .vscode/mcp.json in your workspace (no outer mcp key needed there):

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

Launch options

You can customize the browser with the PUPPETEER_LAUNCH_OPTIONS environment variable (a JSON string), or by passing launchOptions to the puppeteer_navigate tool. Options that weaken security, such as --no-sandbox or --disable-web-security, are rejected unless ALLOW_DANGEROUS is "true" (or allowDangerous: true on the tool call):

"env": {
  "PUPPETEER_LAUNCH_OPTIONS": "{ \"headless\": false, \"executablePath\": \"C:/Program Files/Google/Chrome/Application/chrome.exe\", \"args\": [] }",
  "ALLOW_DANGEROUS": "true"
}

Key features of Puppeteer MCP Server

• Real browser automation through Puppeteer, controlled by natural-language requests to your AI client.
• Seven tools covering navigation, clicking, hovering, form filling, <select> choices, screenshots and JavaScript execution.
• Screenshots of the full page or a single element (by CSS selector), with configurable width and height and an optional base64 output.
• Browser console output exposed as an MCP resource at console://logs.
• Captured screenshots exposed as resources at screenshot://<name>.
• Customizable launch options, with a guard against dangerous Chromium flags.
• Runs locally with no API key, either as a visible browser (NPX) or headless in Docker.

Puppeteer MCP Server tools

The server exposes seven tools in three groups:

• Navigation and page state: puppeteer_navigate opens a URL and can restart the browser with new launchOptions.
• Interaction: puppeteer_click, puppeteer_hover, puppeteer_fill and puppeteer_select act on elements identified by CSS selectors, which covers most login forms, search boxes and dropdowns.
• Inspection: puppeteer_screenshot captures the page or one element, and puppeteer_evaluate runs arbitrary JavaScript in the page, which is handy for reading DOM values or scraping text the other tools cannot reach.

Use cases of Puppeteer MCP Server

• Visual checks while coding: "Open http://localhost:3000, take a screenshot of the header and tell me if the logo is misaligned."
• Form testing: "Go to the sign-up page, fill the email and password fields, click submit and report any error message."
• Light web scraping: "Navigate to this product page and use JavaScript to return the price and title."
• Debugging front-end errors: ask the assistant to load a page and read the console://logs resource to find JavaScript errors.
• Reproducing a bug report: step through a sequence of clicks and dropdown selections and capture a screenshot at each step.

Puppeteer MCP Server vs alternatives

Because the Puppeteer MCP server is archived, it helps to know the maintained options:

• Playwright MCP Server from Microsoft works from the page's accessibility snapshot rather than screenshots and CSS selectors, supports several browsers and is actively developed. It is the most common replacement.
• Chrome DevTools MCP from the Chrome DevTools team uses Puppeteer under the hood and adds performance traces, network inspection and console messages with source-mapped stack traces.
• BrowserTools MCP Server connects to your existing Chrome through an extension, useful when you want logs and audits from the browser you already have open.

Choose the original Puppeteer server mainly when an existing workflow depends on its exact tool names or on a minimal seven-tool surface.

Troubleshooting Puppeteer MCP Server

• npm shows "Package no longer supported": this is expected. The package is deprecated because the server was archived; it still runs, but you may prefer an alternative above.
• No browser window appears: the Docker image runs headless Chromium. Use the NPX configuration if you want to watch the browser, or set "headless": false in PUPPETEER_LAUNCH_OPTIONS.
• "Dangerous" launch arguments throw errors: flags like --no-sandbox are blocked by default. Set ALLOW_DANGEROUS to "true" or pass allowDangerous: true, understanding that it lowers browser security.
• Wrong or missing Chrome: point executablePath in PUPPETEER_LAUNCH_OPTIONS at your installed Chrome.
• Tools not showing in VS Code: in .vscode/mcp.json use a top-level servers key; the extra mcp wrapper is only for the user settings file.