Puppeteer Real Browser MCP Server

Give an MCP-compatible AI assistant a local Chrome browser that it can open, navigate, read, and control.

Under maintenance: This project is still changing. The main branch may be newer than the package published on npm. The npm badge above shows the published version used by @latest.

What it does

This package runs as a local Model Context Protocol (MCP) server. Your MCP client starts the server, and the server starts one Chrome process for browser automation.

Main features:

• Opens a visible browser by default, with optional headless mode
• Navigates pages and reads HTML or text
• Finds elements, clicks, types, waits, and scrolls
• Uses rebrowser-puppeteer-core and a small set of anti-detection settings
• Detects Chrome on Windows, macOS, and Linux
• Supports a custom Chrome path, proxy, and dedicated automation profile
• Tracks the exact Chrome process it starts and closes only that process
• Enforces a content-first workflow before page interaction

No browser automation is invisible. Websites may still detect it or block it.

Safety and current limits

Please read this before using the server:

• Use it only on websites you are allowed to automate.
• Review tool calls before approving logins, forms, purchases, downloads, or other sensitive actions.
• The browser and file tools run with your normal user permissions.
• The server supports one browser session at a time.
• solve_captcha is currently a placeholder. It does not use a CAPTCHA-solving service. Browser startup only makes a best-effort click on detected Turnstile widgets.
• save_content_as_markdown is listed by the server, but the current workflow validator blocks it. This is a known code issue.

Requirements

• Node.js 18 or newer
• npm and npx (included with the normal Node.js installer)
• Google Chrome or Chromium
• An MCP client that can start a local stdio server

Claude Desktop is available on macOS and Windows. Other MCP clients can use this server on Linux.

Quick start

You do not need to install this package globally. npx can download and run the published package when your MCP client needs it.

The -y option prevents an npm install question from blocking the MCP server while it starts.

Claude Desktop

1. Open Claude Desktop → Settings → Developer → Edit Config.
2. Add this server inside mcpServers:

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

1. Save the file.
2. Fully quit Claude Desktop, then open it again.

Claude Desktop stores this file here:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

See the official local MCP server guide for the current Claude Desktop steps.

Claude Code

Run:

claude mcp add --transport stdio puppeteer-real-browser \
  -- npx -y puppeteer-real-browser-mcp-server@latest

Then check the connection:

claude mcp get puppeteer-real-browser

Inside Claude Code, /mcp also shows server status.

The default scope is local to the current project. Add --scope user before the server name if you want the server in all your projects. See the official Claude Code MCP guide for scope details.

Cursor

Create .cursor/mcp.json in one project, or ~/.cursor/mcp.json for all projects:

{
  "mc

... [View full README on GitHub](https://github.com/withLinda/puppeteer-real-browser-mcp-server#readme)