⚠️ UNDER MAINTENANCE - This project is still being actively developed. Some features may be incomplete or change without notice.

Puppeteer Real Browser MCP Server

Provides AI assistants with powerful, detection-resistant browser automation capabilities built on ZFC Digital's puppeteer-real-browser package.

Table of Contents

1. Quick Start for Beginners
2. Introduction
3. Features
4. Prerequisites
5. Installation
6. Usage
   • With Claude Desktop
   • With Claude Code CLI
   • With Cursor IDE
   • With Other AI Assistants
7. Available Tools
8. Advanced Features
9. Configuration
10. Troubleshooting
11. Development
12. Testing
13. Contributing
14. License

Quick Start for Beginners

What is this?

This is an MCP (Model Context Protocol) server that lets AI assistants like Claude control a real web browser. Think of it as giving Claude "hands" to interact with websites - it can click buttons, fill forms, extract content, and much more, all while avoiding bot detection.

Important: You DON'T Need to Install This Package!

If you're just using this MCP server (not developing it), you don't need to run npm install. The npx command in the configuration will automatically download and run the latest version for you. Installation is only required for development purposes.

Step-by-Step Setup

1. Install Node.js (Required)

• Go to nodejs.org
• Download and install Node.js (version 18 or higher)
• Verify installation by opening terminal/command prompt and typing: node --version

2. Configure Claude Desktop

For Windows:

1. Open File Explorer and navigate to: %APPDATA%\Claude\
2. Open (or create) claude_desktop_config.json
3. Add this configuration:

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

For Mac:

1. Open Finder and press Cmd+Shift+G
2. Go to: ~/Library/Application Support/Claude/
3. Open (or create) claude_desktop_config.json
4. Add the same configuration as above

For Linux:

1. Navigate to: ~/.config/Claude/
2. Open (or create) claude_desktop_config.json
3. Add the same configuration as above

Why @latest? The @latest tag ensures you always get the most recent version with bug fixes and improvements. The npx command automatically downloads and runs it without installing anything permanently on your system.

3. Restart Claude Desktop

Close and reopen Claude Desktop completely.

4. Test It Works

In Claude Desktop, try saying:

"Initialize a browser and navigate to google.com, then get the page content"

If everything is working, Claude should be able to:

• Start a browser
• Navigate to Google
• Extract and show you the page content

What Can You Do With It?

Once set up, you can ask Claude to:

• Browse websites: "Go to amazon.com and search for laptops"
• Fill forms: "Fill out this contact form with my details"
• Extract data: "Get all the product prices from this page"
• Automate tasks: "Log into my account and download my invoice"
• Solve captchas: "Handle any captchas that appear"

Safety Notes

• Claude will show you what it's doing - you can see the browser window
• Always review what Claude does before approving sensitive actions
• Use headless mode (headless: true) if you don't want to see the browser window
• Be respectful of websites' terms of service

Introduction

The Puppeteer Real Browser MCP Server acts as a bridge between AI assistants and browser automation. It leverages puppeteer-real-browser to provide stealth browsing capabilities that can bypass common bot detection mechanisms.

This server implements the Model Context Protocol (MCP), allowing AI assistants to control a real browser, extract content, and more.

Features

• Stealth by default: All browser instances use anti-detection features
• Enhanced Windows support: Comprehensive Chrome detection and ECONNREFUSED error fixes (v1.3.0)
• Smart Chrome detection: Registry-based detection + 15+ installation paths (Windows)
• Connection resilience: Automatic localhost/127.0.0.1 fallback with port management
• Multiple retry strategies: 5 different connection approaches with progressive fallback
• Advanced configuration: Full support for all puppeteer-real-browser options
• Dynamic selector discovery: Intelligent element finding without hardcoded selectors
• Random scrolling: Tools for natural scrolling to avoid detection
• Comprehensive toolset: 11 tools covering all browser automation needs
• Proxy support: Built-in proxy configuration for enhanced privacy
• Captcha handling: Support for solving reCAPTCHA, hCaptcha, and Turnstile
• Robust error handling: Advanced error recovery with circuit breaker pattern
• Stack overflow protection: Comprehensive protection against infinite recursion
• Timeout controls: Automatic timeout mechanisms prevent hanging operations
• Platform optimization: Windows-specific flags and longer timeouts for better compatibility

Prerequisites

• Node.js >= 18.0.0
• npm or yarn
• Google Chrome or Chromium browser installed
• Basic understanding of TypeScript/JavaScript (for development)

Platform-Specific Requirements

Windows:

• Google Chrome installation (automatic detection in v1.3.0+ includes):
  • Standard installations: C:\Program Files\Google\Chrome\Application\chrome.exe
  • 32-bit installations: C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
  • User installations: %LOCALAPPDATA%\Google\Chrome\Application\chrome.exe
  • Chrome Canary: %LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe
  • Portable installations and Registry-detected paths
  • Manual path specification: Use CHROME_PATH environment variable

macOS:

• Google Chrome or Chromium must be installed in /Applications/

Linux:

• Install Chrome/Chromium: sudo apt-get install -y google-chrome-stable or sudo apt-get install -y chromium-browser
• Install xvfb for headless operation: sudo apt-get install -y xvfb

Installation for Developers

Note for Claude Desktop Users: You don't need to install anything! The npx command in your configuration automatically handles everything. Skip to the Usage section.

This section is for developers who want to:

• Contribute to the project
• Run the server locally for development
• Create custom modifications

Global Installation (For Command Line Usage)

If you want to run the server directly from the command line without using npx:

npm install -g puppeteer-real-browser-mcp-server@latest

After global installation, you can run:

puppeteer-real-browser-mcp-server

Development Setup (For Contributors)

# Clone the repository
git clone https://github.com/withLinda/puppeteer-real-browser-mcp-server.git
cd puppeteer-real-browser-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Usage

With Claude Desktop

The configuration below uses npx to automatically download and run the latest version. No installation required!

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

What does npx do? The npx command downloads and runs the package without permanently installing it. The @latest ensures you always get the newest version with all bug fixes and improvements.

With Claude Code CLI

Claude Code CLI offers multiple convenient methods to add the puppeteer-real-browser MCP server. Choose the method that best fits your workflow:

Method 1: Quick Setup (Recommended)

The fastest way to get started is using the claude mcp add command:

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

This command:

• Adds the server to your local scope (available only to you in current project)
• Uses npx to automatically download and run the latest version
• No installation required - everything is handled automatically

Method 2: Add with Environment Variables

If you need to configure proxy settings or custom Chrome paths:

claude mcp add puppeteer-real-browser \
  -e CHROME_PATH="/path/to/chrome" \
  -e PROXY_URL="http://proxy:8080" \
  -- npx puppeteer-real-browser-mcp-server@latest

Method 3: Scoped Configuration

For User-Wide Access (Available Across All Projects):

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

For Project-Wide Access (Shared with Team via .mcp.json):

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

Method 4: JSON Configuration

For advanced users who want precise control:

claude mcp add-json puppeteer-real-browser '{
  "type": "stdio",
  "command": "npx",
  "args": ["puppeteer-real-browser-mcp-server@latest"],
  "env": {
    "CHROME_PATH": "/path/to/chrome",
    "PROXY_URL": "http://proxy:8080"
  }
}'

Verification and Testing

After adding the server:

1. Check MCP Server Status:

   /mcp
   

   This command in Claude Code shows all active MCP servers.

2. Test the Server: In Claude Code, try:

   "Initialize a browser and navigate to google.com, then get the page content"

   If working correctly, you should see:

---