Puppeteer MCP Server

How to use

You interact with the server through an MCP client. Start the server using one of the supported local (stdio) configurations, then issue tools to control the browser. The typical workflow includes starting a local MCP server, connecting to a browser (either a fresh instance or an existing one with remote debugging enabled), and chaining actions such as navigate, click, fill, and take screenshots. The server preserves your Chrome instance when you connect to an active tab and provides clear feedback for each operation.

How to install

Prerequisites you need before running the server:

• Node.js and npm installed on your system
• A supported MCP client if you plan to connect via MCP JSON-RPC
• Optional: Python or other tooling if you extend the workflow

Choose one of the available installation methods below and follow the exact commands.

Installation via npm or npx (stdio Configs)

Install and run the MCP server locally using npm or npx. The server is configured to run as a local process and exposes MCP endpoints for your client.

# Global npm install (optional for running as a global command)
npm install -g puppeteer-mcp-server

# Run directly with npx without installation
npx puppeteer-mcp-server

Installation from source (stdio Config)

If you prefer to run from source, you can install dependencies, build, and start the server using the following steps.

# Clone or download the source

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Configuring in your MCP client

Add a local (stdio) MCP entry for Puppeteer in your client’s MCP settings. Use one of the configurations shown here to connect a client to the local server.

Configuration examples

{
  "mcpServers": {
    "puppeteer": {
      "command": "puppeteer-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["path/to/puppeteer-mcp-server/dist/index.js"],
      "env": {
        "NODE_OPTIONS": "--experimental-modules"
      }
    }
  }
}

Security considerations

When using remote or local debugging features, enable access only on trusted networks and manage ports carefully. Close remote debugging ports when not in use and avoid exposing them to public networks.

Logging and debugging

The server records detailed activity to log files to help you monitor browser actions and diagnose issues.

Error handling

If a browser action fails, you receive a clear error message with context about the operation and the system logs the event for troubleshooting.

Notes and troubleshooting

- Ensure Chrome is started with remote debugging when you intend to connect to an existing tab. - If you encounter connection issues, verify the debugging port and that you are connecting to a non-extension tab. - Review logs in the designated log directory for detailed trace information.

Contributing

Contributions are welcome. Share improvements, fixes, or new automation capabilities that extend browser control via Puppeteer MCP Server.

License

MIT License - see the license file for details.

puppeteer_connect_active_tab

Connect to an existing Chrome instance with remote debugging enabled, preserving the current Chrome window and attaching to a non-extension tab.

puppeteer_navigate

Navigate the active page to a specified URL.

puppeteer_screenshot

Capture a screenshot of the current page or a specific element, with optional dimensions.

puppeteer_click

Click an element on the page using a CSS selector.

puppeteer_fill

Fill text into an input field identified by a CSS selector.

puppeteer_select

Choose an option from a select element by its value.

puppeteer_hover

Hover the cursor over a specified element.

puppeteer_evaluate

Execute JavaScript in the browser context and return the result.