# Puppeteer

> Full browser automation: navigate, click, screenshot, and scrape.

[Canonical HTML page](https://top-mcps.com/mcp/puppeteer) · [server.json](https://top-mcps.com/mcp/puppeteer.json) · [methodology](https://top-mcps.com/about/methodology)

## Install

### Claude Desktop — `claude_desktop_config.json`

Paste under mcpServers. Fully quit and reopen Claude after editing.

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

### Claude Code — `CLI or .mcp.json`

Run from your repo. Commit .mcp.json to share with your team.

```shell
claude mcp add puppeteer -- npx -y @hisma/server-puppeteer
```

### Cursor — `.cursor/mcp.json`

Global path: ~/.cursor/mcp.json. Reload window after editing.

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

### VS Code — `.vscode/mcp.json`

VS Code uses the "servers" key (not "mcpServers").

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

### Windsurf — `~/.codeium/windsurf/mcp_config.json`

Open via Cascade → hammer icon → Configure.

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

### Cline — `cline_mcp_settings.json`

Open via the Cline sidebar → MCP Servers → Edit.

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

### Continue — `~/.continue/config.json`

Continue uses modelContextProtocolServers with a transport block.

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "-y",
            "@hisma/server-puppeteer"
          ]
        }
      }
    ]
  }
}
```

### Codex CLI — `~/.codex/config.toml`

Codex uses TOML. Each server is a [mcp_servers.<name>] subtable.

```shell
# ~/.codex/config.toml
[mcp_servers.puppeteer]
command = "npx"
args = [
  "-y",
  "@hisma/server-puppeteer",
]
```

### Zed — `~/.config/zed/settings.json`

Zed calls them "context_servers". Settings live-reload on save.

```jsonc
{
  "context_servers": {
    "puppeteer": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@hisma/server-puppeteer"
        ]
      }
    }
  }
}
```

### ChatGPT — `ChatGPT → Apps directory`

Puppeteer doesn't ship a hosted HTTPS endpoint today. ChatGPT supports remote MCP servers only — to use this server in ChatGPT you'll need to deploy it to a public HTTPS URL first (e.g. via Cloudflare Workers or Vercel) or wait for an official remote build.

```none

```

## At a glance

- **Maintainer:** Community (Hisma — fork of archived Anthropic reference)
- **Transport:** stdio
- **Auth model:** None
- **Required secrets:** None
- **Supported clients:** Claude, Cursor, Any MCP-compatible client, Chrome/Chromium
- **License:** MIT
- **Language:** TypeScript
- **Latest version:** latest
- **Last verified:** 2026-05-31
- **GitHub stars:** 1 (fetched 2026-06-02T11:55:51.694Z)
- **Score:** 48/100 (rubric 2026-04 — see https://top-mcps.com/about/methodology)
- **Source:** https://github.com/Hisma/servers-archived

## Tools & permissions

| Tool | Description | Args | Side effects |
|------|-------------|------|--------------|
| `puppeteer_navigate` | Navigate the browser to a URL. | `url: string` | network |
| `puppeteer_screenshot` | Take a screenshot of the current page or a selector. | `name: string, selector?: string, width?: number, height?: number` | read |
| `puppeteer_click` | Click an element by CSS selector. | `selector: string` | exec |
| `puppeteer_fill` | Fill an input element. | `selector: string, value: string` | exec |
| `puppeteer_select` | Select an option from a dropdown. | `selector: string, value: string` | exec |
| `puppeteer_hover` | Hover over an element. | `selector: string` | exec |
| `puppeteer_evaluate` | Run a JavaScript expression in the page context. | `script: string` | exec |

## Security & scope

- **Access scope:** exec
- **Sandbox:** Launches a headless Chromium process under the user account running the MCP. The browser has the same network and filesystem access the user has.
- **Gotchas:**
  - Chromium can execute arbitrary JavaScript on pages it visits — treat it like a browsing agent running with your credentials.
  - Downloaded files land in the user home directory unless `downloadPath` is configured.
  - Heavy memory footprint — one Chromium process per MCP launch, not reused across tool calls by default.

## Quick answer

**What it does.** Controls a headless Chromium browser via Puppeteer, enabling navigation, DOM interaction, form filling, screenshot capture, and JavaScript execution.

**Best for:**
- Web scraping with JavaScript
- Form automation
- Screenshot capture
- End-to-end testing
- SPA interaction
- UI testing

**Not for:**
- Simple page reading
- High-speed bulk scraping
- Resource-constrained environments

## Recipes

### Screenshot a page and extract its headlines

```
Open https://news.ycombinator.com, take a full-page screenshot named `hn.png`, then return the top 5 headlines with their score and number of comments.
```

_Tested with: Claude Desktop, Cursor_

## Description

The Puppeteer MCP provides AI models with a full Chromium browser instance. Navigate URLs, click elements, fill forms, take screenshots, and extract content from JavaScript-rendered pages. The most capable browser automation option for AI agents.

## Why it matters

Many modern pages require JavaScript to render. Puppeteer is the only reliable way to interact with SPAs, dashboards, and login-gated pages.

## Key features

- Full Chromium browser
- JavaScript execution
- Screenshot capture
- Form interaction
- Cookie management
- Multi-tab support

## FAQ

### Does it require Chrome to be installed?

No. Puppeteer downloads its own bundled Chromium on first run (~150 MB). That keeps the version pinned and your system browser untouched.

### Can it take screenshots?

Yes. The server exposes `screenshot` as a first-class tool: full-page, viewport, or a specific selector. The model gets the image back as a base64 payload it can describe or reason over.

### Can the agent fill forms and click buttons?

Yes. Alongside navigate and screenshot, the server exposes `click`, `fill`, `select`, `evaluate` (run arbitrary JS), and `wait_for_selector`. That is enough to drive most web flows end-to-end.

### Does it run headless or with a visible browser?

Headless by default, which is right for servers and CI. If you want to watch the agent drive, set `PUPPETEER_HEADLESS=false` in the `env` block of your MCP config.

### Will it work inside Docker?

Yes, but you need a base image with the Puppeteer system libraries (or use `ghcr.io/puppeteer/puppeteer`). On Alpine you will need `chromium` from the community repo plus `PUPPETEER_EXECUTABLE_PATH` pointing at it.

### When should I prefer the Fetch MCP instead?

Whenever the content is served as static HTML. Fetch is an order of magnitude faster and cheaper. Reserve Puppeteer for sites that depend on JS, sessions, or user interaction — pricing calculators, dashboards, auth-gated docs.

## Changelog

- **2026-05-31** — Refreshed install snippets and fact sheet; verified for 2026.
- **2024-11-25** — Initial directory listing.