Puppeteer MCP
About
MCP server for browser automation via Puppeteer. Executes arbitrary JavaScript with direct access to Puppeteer Browser instance. Single "execute" tool runs your code in a sandboxed Node.js VM with a browser global - full Puppeteer API access in one call.
Details
- Author
- iatsiuk
- Downloads
- 439
- Categories
- Developer Tools, Automation, Other, Web Scraping
Jump to
- 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.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Puppeteer MCPCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
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.
execute
Execute JS with Puppeteer 24.43.1. Globals: browser. Use 'return' for result. Use Puppeteer selectors: CSS, text/, aria/, xpath/, pierce/. Response includes screenshots (path, url) for each open tab.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"puppeteer mcp": {
"puppeteer": {
"command": "npx",
"args": [
"pptr-mcp"
]
}
}
}
}McpServers
{
"puppeteer": {
"command": "npx",
"args": [
"pptr-mcp"
]
}
}pptr-mcp
MCP server for browser automation via Puppeteer. Unlike other browser MCPs that expose fixed tools (navigate, click, screenshot), this server executes arbitrary JavaScript code with direct access to the Puppeteer Browser instance.Key Difference
Most browser MCP servers provide a limited set of predefined actions. This approach requires multiple round-trips for complex workflows and can't handle edge cases. pptr-mcp takes a different approach: it exposes a singleexecute tool that runs your JavaScript code in a sandboxed Node.js VM with a browser global. You write Puppeteer code directly, getting full API access in one call.
``
Traditional MCP (5 round-trips) pptr-mcp (1 round-trip)
================================ ================================
Agent Server Agent Server
| | | |
|-- navigate --->| |-- execute ---->|
|<-- ok ---------| | |
| | | +------------------------+
|-- waitFor ---->| | | const page = await |
|<-- ok ---------| | | browser.newPage(); |
| | | | await page.goto(url); |
|-- click ------>| | | await page.click(s); |
|<-- ok ---------| | | await page.type(i, t); |
| | | | return await |
|-- type ------->| | | page.screenshot(); |
|<-- ok ---------| | +------------------------+
| | | |
|-- screenshot ->| |<-- result -----|
|<-- image ------| | |
| | | |
`
Installation
`bash
npm install -g pptr-mcp
`
MCP Configuration
Add to your MCP client config (e.g., Claude Desktop):
`json
{
"mcpServers": {
"puppeteer": {
"command": "npx",
"args": ["pptr-mcp"]
}
}
}
`
With custom Chrome flags:
`json
{
"mcpServers": {
"puppeteer": {
"command": "npx",
"args": [
"pptr-mcp",
"--window-size=1920,1080",
"--proxy-server=http://proxy:8080"
]
}
}
}
`
Claude Code Plugin
Install as a Claude Code plugin:
`bash
/plugin marketplace add iatsiuk/pptr-mcp
/plugin install pptr-mcp@pptr-mcp
`
Environment Variables
| Variable | Description |
| --------------------------- | ---------------------------------------- |
| CHROME_PATH | Path to Chrome executable |
| PUPPETEER_EXECUTABLE_PATH | Alternative to CHROME_PATH |
| PPTR_MCP_TIMEOUT | Execution timeout in ms (default: 30000) |
Tool: execute
Executes JavaScript code with access to Puppeteer browser.
Parameters
| Name | Type | Default | Description |
| ------------ | ------- | -------- | ---------------------------------- |
| code | string | required | JavaScript code to execute |
| persistent | boolean | true | Reuse browser session across calls |
Security
This server is designed for trusted local development with LLM assistants (Claude Code, Cursor, etc.). The executing code comes from the LLM at your request.
What this means
- Not a sandbox: The Node.js VM isolates code for convenience, not security. It is not designed to run untrusted code.
- Full browser control: Executed code can navigate to any URL, read page content, take screenshots, and interact with web applications.
- Chrome runs without sandbox: --no-sandbox flag is used for Docker/container compatibility.
- Persistent sessions: With persistent: true (default), cookies and browser state are preserved across calls. Use persistent: false` for isolation.
Not designed for
- Multi-tenant or shared server deployments - Executing untrusted code from external sources - Building web services that accept arbitrary user inputLicense
WTFPLSign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
