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 single execute 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

npm install -g pptr-mcp

MCP Configuration

Add to your MCP client config (e.g., Claude Desktop):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp"]
    }
  }
}

With custom Chrome flags:

{
  "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:

/plugin marketplace add iatsiuk/pptr-mcp
/plugin install pptr-mcp@pptr-mcp

Environment Variables

Tool: execute

Executes JavaScript code with access to Puppeteer browser.

Parameters

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 input

License

WTFPL