Home / MCP / Puppeteer-Extra MCP Server

Puppeteer-Extra MCP Server

MCP server for browser automation using puppeteer-extra and puppeteer-extra-plugin-stealth

TypeScript

2stars

View on GitHub

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
    "mcpServers": {
        "puppeteer": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "--init",
                "-e",
                "DOCKER_CONTAINER=true",
                "mcp/puppeteer-extra"
            ],
            "env": {
                "DOCKER_CONTAINER": "true"
            }
        }
    }
}

This MCP server enables enhanced browser automation through Puppeteer-Extra with Stealth capabilities, giving you browser interactions that resemble human activity. It exposes a set of tools for navigating pages, taking screenshots, clicking, filling forms, and evaluating scripts, with options to log console output and run in both headless and non-headless modes.

How to use

You interact with the Puppeteer-Extra MCP server through an MCP client by selecting a tool and providing the required inputs. Common workflows include navigating to a URL, taking full-page or element screenshots, clicking or hovering over elements, filling input fields, selecting options, and evaluating JavaScript in the page context. Use console logs to inspect browser messages and retrieve screenshots from the dedicated screenshot resources.

How to install

Prerequisites you need before running the server include Node.js and Docker. Ensure you have a working Node environment and Docker installed on your machine.

Step 1: Clone the project and navigate to its directory.

git clone <repository-url>
cd puppeteer_extra

Step 2: Install dependencies locally.

npm install

Step 3: Copy the environment file for development settings.

cp .env.example .env.development

Step 4: Run in development mode (non-headless browser) or production mode (headless browser) as needed.

npm run dev
# or
npm run prod

Step 5: Build the project for production if you plan to publish the container image.

npm run build

Running with Docker

If you prefer running the MCP server inside Docker, build and run the image with Docker using the following commands.

docker build -t mcp/puppeteer-extra .
```
```
docker run -i --rm --init -e DOCKER_CONTAINER=true mcp/puppeteer-extra

Configuration for Claude Desktop

You can configure a Claude Desktop MPC client to connect to the server using either Docker-based or NPX-based commands.

{
  "mcpServers": {
    "puppeteer": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "mcp/puppeteer-extra"]
    }
  }
}

NPX configuration

Alternatively, you can run the server via NPX if you prefer not to build a Docker image.

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "MCP_puppeteer_extra"]
    }
  }
}

Available tools

puppeteer_navigate

Navigate to a URL in the browser context.

puppeteer_screenshot

Capture a screenshot of the full page or a specific element, with optional width and height.

puppeteer_click

Click an element identified by a CSS selector.

puppeteer_hover

Hover over an element identified by a CSS selector.

puppeteer_fill

Fill an input field identified by a CSS selector with a value.

puppeteer_select

Select an option in a SELECT tag by value.

puppeteer_evaluate

Execute JavaScript in the browser console context.