Content
# puppeteer-mcp-server
An [MCP](https://modelcontextprotocol.io) server that opens web pages with
[Puppeteer](https://pptr.dev/) and performs browser actions on the
instruction of an AI client. The AI inspects a page through a snapshot,
then calls the tools below to navigate, click, type, and read results.
## Requirements
- Node.js 18+
- Chromium is downloaded automatically by Puppeteer on `npm install`.
## Install
```bash
npm install
```
## Run
```bash
npm start
```
The server speaks the MCP protocol over **stdio**, so it is normally
launched by an MCP client rather than run by hand.
## Add it to an MCP client
Point your client at the server command. For a Claude Desktop-style
config (`mcpServers` block):
```json
{
"mcpServers": {
"puppeteer": {
"command": "node",
"args": ["/absolute/path/to/mcp-server/src/index.js"]
}
}
}
```
## Tools
| Tool | Purpose |
| --- | --- |
| `browser_navigate` | Open a URL. Returns the final URL, HTTP status, and title. |
| `browser_snapshot` | Return the page URL, title, visible text, and a numbered list of interactive elements. Each element gets a `ref`. |
| `browser_get_text` | Get the visible text of the page or of one CSS-selected element. |
| `browser_click` | Click an element by `ref` (from a snapshot) or CSS `selector`. |
| `browser_type` | Clear and type into an input/textarea by `ref` or `selector`, optionally pressing Enter. |
| `browser_press_key` | Press a single key (`Enter`, `Escape`, `ArrowDown`, ...). |
| `browser_wait_for` | Wait for a CSS `selector` or a piece of `text` to appear. |
| `browser_evaluate` | Evaluate a JavaScript expression in the page and return the result. |
| `browser_screenshot` | Return a PNG screenshot of the page (viewport or full page). |
| `browser_go_back` | Navigate back in history. |
| `browser_close` | Close the browser and free resources. |
### Typical flow
1. `browser_navigate` to a URL.
2. `browser_snapshot` to see the page text and the actionable elements
(each with a `ref`).
3. `browser_click` / `browser_type` using those refs.
4. `browser_snapshot` or `browser_get_text` again to read the result.
Because a single browser instance is reused across calls, cookies and
navigation state persist for the whole session until `browser_close`.
## Configuration
Set via environment variables:
| Variable | Default | Description |
| --- | --- | --- |
| `MCP_BROWSER_HEADLESS` | `true` | Set to `false` to watch the browser (useful for debugging). |
| `MCP_BROWSER_TIMEOUT_MS` | `30000` | Default navigation / wait timeout. |
| `MCP_BROWSER_WIDTH` | `1280` | Viewport width. |
| `MCP_BROWSER_HEIGHT` | `800` | Viewport height. |
## Security note
`browser_evaluate` runs arbitrary JavaScript in the page context, and the
server will navigate to any URL it is given. Run it only with clients and
instructions you trust.
## License
MIT
