Traditional MCP (5 round-trips)         pptr-mcp (1 round-trip)
================================        ================================

  Agent           Server                  Agent           Server
    |                |                      |                |
    |-- navigate --->|                      |-- execute ---->|
    ||                      |   | const page = await     |
    ||                      |   | await page.click(s);   |
    ||                      |   |   page.screenshot();   |
    ||                      |= 20

## Installation

## MCP Configuration

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

With CLI options:

With custom Chrome flags (after `--`):

## CLI Options

| Option             | Description                                  |
| ------------------ | -------------------------------------------- |
| `--no-headless`    | Run with visible browser window              |
| `--viewport=VALUE` | Set viewport size (e.g., 1920x1080 or 1080p) |
| `--help, -h`       | Show help                                    |
| `-- [args]`        | Pass remaining args to Chrome                |

Unknown options before `--` are also passed to Chrome.

## Claude Code Plugin

Install as a Claude Code plugin:

## Environment Variables

| Variable                    | Description                              |
| --------------------------- | ---------------------------------------- |
| `CHROME_PATH`               | Path to Chrome executable                |
| `PUPPETEER_EXECUTABLE_PATH` | Alternative to CHROME_PATH               |
| `PUPPETEER_CACHE_DIR`       | Browser download cache directory         |
| `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 |

## Recipes

### Disable headless mode

Show browser window during execution:

### Custom Chrome profile directory

Use your own Chrome profile with saved logins and cookies:

### Use system Chrome instead of downloaded

By default, pptr-mcp downloads Chrome for Testing - a version optimized and tested for the bundled Puppeteer. To use your system Chrome instead:

## 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](LICENSE.md)