How to Use Puppeteer MCP Server for Browser Automation

A step-by-step guide to installing, configuring, and using puppeteer-mcp-server (Puppeteer MCP) for browser automation and debugging.

Ivan Muñoz Jun 26, 2025

Puppeteer

Puppeteer MCP Server (puppeteer-mcp-server) is a powerful tool that exposes browser automation capabilities via Puppeteer, allowing you to control Chrome programmatically or connect to existing Chrome windows. This guide will walk you through installation, configuration, and common use cases.

What is Puppeteer MCP Server?

Puppeteer MCP Server is an open-source server that provides browser automation through Puppeteer, supporting both new browser instances and existing Chrome tabs. It is especially useful for debugging, testing, and integrating with tools like Claude or VSCode extensions.

Installation

You can install Puppeteer MCP Server globally using npm:

npm install -g puppeteer-mcp-server

Or run it directly with npx (no install required):

npx puppeteer-mcp-server

To install from source:

git clone https://github.com/merajmehrabi/puppeteer-mcp-server.git
cd puppeteer-mcp-server
npm install
npm run build
npm start

Basic Usage

By default, the server launches a new browser instance. You can interact with it using supported tools (see below) or integrate it with automation platforms.

Connecting to an Existing Chrome Instance

To connect to an already open Chrome window (“Active Tab Mode”), follow these steps:

1. Close all Chrome windows.

2. Start Chrome with remote debugging enabled:

   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
   

3. Navigate to your desired page in Chrome.

4. Connect using the puppeteer_connect_active_tab tool:

   {
     "targetUrl": "https://example.com", // Optional: specific tab URL
     "debugPort": 9222 // Optional: defaults to 9222
   }
   

The server will detect and connect to the Chrome instance, preserving your session and tabs.

Available Tools

• puppeteer_connect_active_tab: Connect to an existing Chrome instance.
• puppeteer_navigate: Navigate to a URL.
• puppeteer_screenshot: Take a screenshot of the page or an element.
• puppeteer_click: Click an element by selector.
• puppeteer_fill: Fill an input field.
• puppeteer_select: Select an option from a dropdown.
• puppeteer_hover: Hover over an element.
• puppeteer_evaluate: Run JavaScript in the browser context.

Each tool returns a success/failure status and detailed error messages if something goes wrong.

Example: Take a Screenshot

{
  "tool": "puppeteer_screenshot",
  "name": "homepage",
  "selector": "#main-content",
  "width": 1200,
  "height": 800
}

Security Tips

• Only enable remote debugging on trusted networks.
• Use a unique debugging port.
• Close the debugging port when not in use.
• Never expose the debugging port to public networks.

Logging and Debugging

Puppeteer MCP Server logs all operations to the logs/ directory, including errors, browser actions, and server events. Log files are rotated daily and retained for 14 days.

Troubleshooting

If you encounter issues, check the logs for detailed error messages. For persistent problems, consult the official repository for updates and open issues.

Visual Debugging with Buglesstack

For advanced debugging and error reporting, you can use a visual testing tool like Buglesstack to capture screenshots, HTML, and error details during automation.

import axios from 'axios';
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();

try {
	await page.goto('https://www.google.com/search?q=puppeteer');		
	await page.waitForSelector('[name="q"]');
    await page.close();
    await browser.close();
}
catch (error) {
	// Prepare buglesstack data
	const buglesstackData = {
		url: page.url(),
		screenshot: await page.screenshot({ encoding: 'base64' }),
		html: await page.content(),
		metadata: {},
		message: error.message,
		stack: error.stack
	};

	// Get your access token from https://app.buglesstack.com
	const ACCESS_TOKEN = 'HERE_YOUR_ACCESS_TOKEN';

	// Send error to buglesstack
	await axios.post('https://app.buglesstack.com/api/v1/crashes', buglesstackData, {
		headers: {
			Authorization: `Bearer ${ACCESS_TOKEN}`,
			'Content-Type': 'application/json'
		}
	});
		
	// Re-throw the error to propagate it
	throw error;
}

By following this guide, you can leverage Puppeteer MCP Server for robust browser automation, testing, and debugging in your projects.