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)

```bash