home / mcp / puppeteer real browser mcp server

Puppeteer Real Browser MCP Server

Provides AI assistants with stealth browser automation capabilities powered by puppeteer-real-browser.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "withlinda-puppeteer-real-browser-mcp-server": {
      "command": "npx",
      "args": [
        "puppeteer-real-browser-mcp-server@latest"
      ],
      "env": {
        "PROXY_URL": "http://proxy.example.com:8080",
        "CHROME_PATH": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
      }
    }
  }
}

You can empower AI assistants to control a real web browser through an MCP server. This setup lets Claude-style agents open websites, interact with pages, fill forms, extract content, and automate tasks while leveraging stealth browser automation features for safer web interactions.

How to use

You can connect an MCP client to the Puppeteer Real Browser MCP Server to enable browser automation capabilities for AI assistants. The server supports multiple clients and interaction tools to navigate pages, fill forms, click elements, read content, and handle common automation needs such as captcha handling and data extraction. Use this to enable tasks like browsing product pages, submitting forms, and collecting data from websites.

How to install

Prerequisites: install Node.js version 18 or higher, have npm or yarn available, and ensure Google Chrome or Chromium is installed on your system.

Step 1: Install Node.js and verify the installation.

node --version
npm --version

Step 2: Set up the MCP server with a client configuration. You do not need a permanent install for Claude Desktop usage; you use npx to run the MCP server when you start the client.

For Claude Desktop, configure your client to reference the MCP server using a one-line JSON config in the appropriate client settings file.

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": ["puppeteer-real-browser-mcp-server@latest"]
    }
  }
}

With Claude Desktop

Create or edit the Claude Desktop config file to point to the MCP server using npx. The example below assumes you are on Windows, Mac, or Linux with a similar path.

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": ["puppeteer-real-browser-mcp-server@latest"]
    }
  }
}

With Claude Code CLI

Add the MCP server to your project with the quick setup. This uses npx to fetch the latest MCP server version automatically.

claude mcp add puppeteer-real-browser -- npx puppeteer-real-browser-mcp-server@latest

With Cursor IDE

Cursor IDE can use the same npx approach or a JSON configuration file. One-click installation is available, or you can place a config file in the project or global Cursor settings.

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": ["puppeteer-real-browser-mcp-server@latest"]
    }
  }
}

Configuration

Automatic Chrome path detection improves reliability. If automatic detection fails, you can specify a custom Chrome path via CHROME_PATH or via browser initialization options. For example, you can override the Chrome path to a known location and pass browser options when initializing the browser.

{
  "customConfig": {
    "chromePath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
  }
}

Notes on browser options and init

Browser-specific options are provided when you initialize the browser through the browser_init tool. Do not set these in the MCP config file. You can enable headless mode, set proxies, and adjust timeouts at initialization time.

{
  "headless": true,
  "connectOption": {
    "timeout": 30000
  },
  "proxy": "https://proxy.example.com:8080"
}

Troubleshooting

If you encounter ECONNREFUSED or browser launch issues, try configuring CHROME_PATH explicitly, ensure the Chrome process can start, and verify network access to localhost. Restart the client after changes.

Security and safety notes

The server provides stealth browser capabilities but always review automated actions before proceeding with sensitive operations. Use headless mode for background tasks and respect websites’ terms of service.

Development and testing

Development workflows are available for contributors. Run tests and builds as described in the project’s testing section, and ensure you are using Node.js 18+.

Available tools

browser_init

Initialize stealth browser with advanced options such as headless mode, proxy, plugins, and connection options

navigate

Navigate the browser to a specified URL with optional wait behavior

get_content

Extract page content or text from the current page, with optional selectors

browser_close

Close the active browser instance to free resources

click

Click on a page element using a CSS selector with optional navigation wait

type

Type text into an input field identified by a CSS selector with optional delay

wait

Wait for conditions such as selectors, navigation, or timeouts

find_selector

Find a CSS selector for an element containing specific text, with optional element type and exact matching

random_scroll

Perform natural, randomized scrolling to mimic human browsing behavior

save_content_as_markdown

Extract page content and save it as a markdown file to a specified path

solve_captcha

Attempt to solve common captcha challenges such as reCAPTCHA, hCaptcha, and Turnstile