Supports handling Cloudflare Turnstile captchas through the solve_captcha tool.
Supports browsing Google websites and handling reCAPTCHA challenges through dedicated captcha solving capabilities.
Leverages Puppeteer for browser automation with enhanced stealth capabilities, including realClick and realCursor methods to avoid detection.
⚠️ 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
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:
Open File Explorer and navigate to:
%APPDATA%\Claude\
Open (or create)
claude_desktop_config.json
Add this configuration:
For Mac:
Open Finder and press
Cmd+Shift+G
Go to:
~/Library/Application Support/Claude/
Open (or create)
claude_desktop_config.json
Add the same configuration as above
For Linux:
Navigate to:
~/.config/Claude/
Open (or create)
claude_desktop_config.json
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 windowBe 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
orsudo 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:
After global installation, you can run:
Development Setup (For Contributors)
Usage
With Claude Desktop
The configuration below uses npx
to automatically download and run the latest version. No installation required!
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:
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:
Method 3: Scoped Configuration
For User-Wide Access (Available Across All Projects):
For Project-Wide Access (Shared with Team via .mcp.json):
Method 4: JSON Configuration
For advanced users who want precise control:
Verification and Testing
After adding the server:
Check MCP Server Status:
/mcpThis command in Claude Code shows all active MCP servers.
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:
Browser initialization
Navigation to Google
Page content extracted and displayed
Configuration Scopes Explained
Scope | Description | Config Location | Use Case |
local (default) | Available only to you in current project |
in project | Testing, project-specific |
project | Shared with entire team |
committed to repo | Team collaboration |
user | Available to you across all projects | User config directory | Personal productivity |
Benefits of Claude Code CLI
Automatic Updates: Using
@latest
ensures you get bug fixes and improvementsNo Installation: npx handles downloading and running automatically
Environment Variables: Easy configuration of proxies, Chrome paths, etc.
Scope Control: Choose where the server is available (local/project/user)
Team Sharing: Project scope allows sharing configurations with teammates
Status Monitoring: Built-in
/mcp
command for server health checks
With Cursor IDE
Cursor IDE uses the same npx approach - no installation needed! Here are the setup methods:
Method 1: One-Click Installation (Recommended)
Open Cursor IDE
Open Command Palette (
Ctrl+Shift+P
on Windows/Linux,Cmd+Shift+P
on Mac)Search for "Cursor Settings" and select it
Click on "MCP" in the sidebar
Browse curated MCP servers and install browser automation tools with one-click
OAuth authentication will be handled automatically
Method 2: Manual Configuration
Configuration File Location:
Project-specific: Create
.cursor/mcp.json
in your project directoryGlobal: Create
~/.cursor/mcp.json
in your home directory
Basic Configuration (No Installation Required):
Important: Just like Claude Desktop, Cursor will use
npx
to automatically download and run the server. You don't need to install anything with npm!
Windows-Specific Configuration (if experiencing Chrome path issues):
Note: Browser options like headless mode should be configured when initializing the browser through the
browser_init
tool, not via environment variables.
Advanced Configuration with Custom Chrome Path:
Note: Proxy settings and browser options should be configured when asking Claude to initialize the browser using the
browser_init
tool.
Platform-Specific Chrome Paths for Cursor IDE
If Chrome auto-detection fails, you can specify the Chrome path using the CHROME_PATH
environment variable:
Windows:
Alternative Windows paths:
"C:/Program Files (x86)/Google/Chrome/Application/chrome.exe"
"%LOCALAPPDATA%/Google/Chrome/Application/chrome.exe"
macOS:
Linux:
Alternative Linux paths: /usr/bin/chromium-browser
, /snap/bin/chromium
Testing Cursor IDE Setup
After configuration:
Restart Cursor IDE completely
Open a new chat
Test with: "Initialize a browser and navigate to google.com, then get the page content"
If successful, you should see:
Browser window opening
Navigation to Google
Page content extracted and displayed in the chat
Cursor IDE Troubleshooting
Common Issues:
"MCP server not found"
Verify config file location and JSON syntax
Use jsonlint.com to validate JSON
Ensure Node.js 18+ is installed
"Browser failed to launch" on Windows
Add explicit Chrome path in
executablePath
Try running Cursor IDE as Administrator
Check Windows Defender isn't blocking Chrome
"Permission denied"
Use
sudo npm install -g puppeteer-real-browser-mcp-server
on Linux/MacRun Command Prompt as Administrator on Windows
Configuration not loading
Ensure file is named exactly
mcp.json
(notmcp.json.txt
)Check file is in correct directory
Restart Cursor IDE after changes
With Other AI Assistants
Start the server:
Or if installed from source:
The server communicates via stdin/stdout using the MCP protocol.
Example Interactions
Basic Web Browsing
Form Automation
Data Extraction
Working with Proxies
Available Tools
Core Browser Tools
Tool Name | Description | Required Parameters | Optional Parameters |
| Initialize stealth browser with advanced options | None |
,
,
,
,
,
|
| Navigate to a URL |
|
|
| Get page content (HTML or text) | None |
,
|
| Close the browser instance | None | None |
Interaction Tools
Tool Name | Description | Required Parameters | Optional Parameters |
| Standard click on element |
|
|
| Type text into input field |
,
|
|
| Wait for various conditions |
,
|
|
| Find CSS selector for element containing specific text |
|
,
|
Behavior Tools
Tool Name | Description | Required Parameters | Optional Parameters |
| Perform random scrolling with natural timing | None | None |
Element Discovery Tools
Tool Name | Description | Required Parameters | Optional Parameters |
| Find CSS selector for element containing specific text |
|
,
|
Content Tools
Tool Name | Description | Required Parameters | Optional Parameters |
| Extract page content and save it as a formatted markdown file |
|
,
,
|
Anti-Detection Tools
Tool Name | Description | Required Parameters | Optional Parameters |
| Attempt to solve captchas |
| None |
Advanced Features
Dynamic Selector Discovery
The server includes intelligent element discovery capabilities through the find_selector
tool:
Text-based element finding: Automatically locates elements containing specific text
Smart CSS selector generation: Creates unique, robust CSS selectors similar to Chrome DevTools
Element type filtering: Optionally restrict search to specific HTML elements (e.g., buttons, links)
Exact or partial text matching: Choose between precise text matching or substring searches
Universal compatibility: Works across any website without hardcoded selectors
Example Usage:
This approach eliminates the need for manually crafted selectors and makes automation more reliable across different websites.
Natural Interactions
The server includes tools designed for natural browsing behavior:
Random scrolling: Performs scrolling with natural timing and variable distances
This feature helps avoid detection by sophisticated bot-detection systems that analyze user behavior patterns.
Captcha Handling
The server includes basic support for solving common captcha types:
reCAPTCHA
hCaptcha
Cloudflare Turnstile
Note that captcha solving capabilities depend on the underlying puppeteer-real-browser implementation.
Configuration
Automatic Chrome Path Detection (Enhanced in v1.3.0)
The server automatically detects Chrome installation paths across different operating systems with significantly improved Windows support:
Windows (v1.3.0+):
Registry-based detection for installed Chrome versions
Searches 15+ common installation directories including Program Files, user-specific locations, and portable installations
Support for Chrome Canary fallback
Environment variable detection (
CHROME_PATH
,PUPPETEER_EXECUTABLE_PATH
)Detailed troubleshooting guidance when Chrome is not found
macOS: Looks for Chrome in
/Applications/Google Chrome.app/
and Chrome Canary locationsLinux: Checks multiple locations including
/usr/bin/google-chrome
,/usr/bin/chromium-browser
, and snap installations
Windows Registry Detection (NEW in v1.3.0): The server now queries Windows Registry to find Chrome installations, making detection more reliable across different installation types.
If Chrome is not found automatically, you can specify a custom path using:
Environment variable:
set CHROME_PATH="C:\Your\Chrome\Path\chrome.exe"
Browser init option:
customConfig.chromePath
when initializing the browser
Configuring Custom Options (like headless mode)
Custom options like headless mode are not configured in the MCP config file. Instead, they're passed when initializing the browser using the browser_init
tool:
When you ask Claude to initialize a browser, you can specify options like:
Claude will then use the browser_init
tool with appropriate parameters:
Available Browser Options
When initializing with browser_init
, you can configure:
headless
: true/false (Set to true for headless operation)disableXvfb
: true/false (Disable X Virtual Framebuffer)ignoreAllFlags
: true/false (Ignore all Chrome flags)proxy
: "https://proxy:8080" (Proxy server URL)plugins
: ["plugin1", "plugin2"] (Array of plugins to load)connectOption
: Additional connection options like:slowMo
: 250 (Slow down operations by milliseconds)timeout
: 60,000 (Connection timeout)
The MCP config file only tells Claude where to find the server - all browser-specific options are configured through your conversations with Claude.
Browser Options Example
When initializing the browser with browser_init
, you can configure:
Advanced Configuration Examples
Specifying Custom Chrome Path
Using a Proxy
Stealth Mode with Custom Options
Server Configuration
For advanced users, you can modify the server behavior by editing the source code:
Change default viewport size in the
initializeBrowser
functionAdjust timeout values for various operations
Enable debug logging
Troubleshooting
Major Windows Connection Issues (Fixed in v1.3.0)
🔧 ECONNREFUSED Error Solutions
Version 1.3.0 includes comprehensive fixes for the connect ECONNREFUSED 127.0.0.1:60725
error commonly experienced on Windows systems:
Enhanced Chrome Path Detection:
Added Windows Registry-based Chrome detection
Expanded search to 15+ Windows installation locations including portable installations
Added support for Chrome Canary fallback
Environment variable support (
CHROME_PATH
,PUPPETEER_EXECUTABLE_PATH
)
Windows-Specific Launch Optimizations:
20+ Windows-specific Chrome flags for better compatibility
Multiple fallback strategies (5 different connection approaches)
Progressive retry logic with exponential backoff
Enhanced timeout handling (120s for Windows vs 90s for other platforms)
Connection Resilience Features:
Localhost vs 127.0.0.1 fallback handling (fixes known Puppeteer issue)
Port availability checking and automatic port assignment
Network connectivity testing before browser launch
Enhanced error categorization and automatic fallback strategies
If you're still experiencing ECONNREFUSED errors:
Environment Variables (Recommended):
set CHROME_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"Manual Chrome Path Configuration:
Ask Claude: "Initialize browser with custom Chrome path at C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"Network Troubleshooting:
# Test localhost resolution ping localhost # Should resolve to 127.0.0.1 # Check Windows hosts file notepad C:\Windows\System32\drivers\etc\hosts # Ensure: 127.0.0.1 localhostChrome Process Management:
# Kill existing Chrome processes taskkill /f /im chrome.exe
Common Issues
npx-Specific Issues
"spawn npx ENOENT" or "command not found" errors
Cause: npx is not in your system PATH or Node.js is not properly installed
Solutions:
Verify Node.js installation:
node --version
andnpm --version
Reinstall Node.js from nodejs.org
For NVM users, see the NVM-specific section below
"npx: command not found" in Claude Desktop/Cursor
Windows: Make sure to restart your IDE after installing Node.js
Mac/Linux: Add npm to PATH:
export PATH="$PATH:$(npm bin -g)"
Alternative: Use the full path to npx:
/usr/local/bin/npx
npx hangs or takes too long
npx downloads the package on first run, which can take 30-60 seconds
Ensure you have a stable internet connection
Try clearing npm cache:
npm cache clean --force
Using NVM (Node Version Manager)?
Standard npx commands may fail with NVM
Solution 1: Use absolute paths in your config:
{ "mcpServers": { "puppeteer-real-browser": { "command": "/Users/yourname/.nvm/versions/node/v20.0.0/bin/npx", "args": ["puppeteer-real-browser-mcp-server@latest"] } } }Solution 2: Set a default Node version:
nvm alias default 20.0.0
Permission denied errors with npx
Mac/Linux: Try with sudo:
sudo npx puppeteer-real-browser-mcp-server@latest
Better solution: Fix npm permissions:
npm config set prefix ~/.npm
Other Common Issues
"Maximum call stack size exceeded" errors
This was fixed in version 1.2.0 with comprehensive stack overflow protection
The server now includes circuit breaker patterns and recursion depth tracking
Timeout controls prevent hanging operations that could lead to stack overflow
If you encounter this error, ensure you're using the latest version:
npx puppeteer-real-browser-mcp-server@latest
"command not found" or "syntax error" when using npx
This was fixed in version 1.0.3 with the addition of a proper shebang line
Make sure you're using the latest version:
npx puppeteer-real-browser-mcp-server@latest
For global installation:
npm install -g puppeteer-real-browser-mcp-server@latest
If still having issues, install globally:
npm install -g puppeteer-real-browser-mcp-server
Check your PATH includes npm global binaries:
npm config get prefix
Browser won't start
Check if Chrome/Chromium is installed in standard locations
Windows specific troubleshooting:
Step 1: Verify Chrome Installation Paths Check these locations in order:
C:\Program Files\Google\Chrome\Application\chrome.exe
C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe
%PROGRAMFILES%\Google\Chrome\Application\chrome.exe
Step 2: Manual Path Configuration If Chrome is in a different location, specify it manually:
Ask Claude: "Initialize browser with custom Chrome path at C:\Your\Chrome\Path\chrome.exe"Step 3: Windows Launch Arguments For Windows compatibility, use these launch arguments:
Ask Claude: "Initialize browser with args --disable-gpu --disable-setuid-sandbox"Step 4: Windows-Specific Solutions
Run as Administrator: Try running your IDE/terminal as Administrator
Windows Defender: Add Chrome and Node.js to Windows Defender exclusions
Antivirus Software: Temporarily disable antivirus to test if it's blocking Chrome
User Account Control: Lower UAC settings temporarily for testing
Chrome Processes: Kill any existing Chrome processes in Task Manager
Step 5: Alternative Chrome Installation If Chrome detection still fails:
Download Chrome directly from google.com/chrome
Install to default location (
C:\Program Files\Google\Chrome\
)Restart your IDE after installation
Step 6: PowerShell vs Command Prompt Try switching between PowerShell and Command Prompt:
Test with
cmd.exe
instead of PowerShellTest with PowerShell instead of Command Prompt
Step 7: Node.js and npm Configuration
Ensure Node.js is added to PATH:
node --version
Clear npm cache:
npm cache clean --force
Reinstall global packages:
npm install -g puppeteer-real-browser-mcp-server@latest
Linux: Install dependencies:
sudo apt-get install -y google-chrome-stable
macOS: Ensure Chrome is in
/Applications/
Try with
headless: true
firstCheck console output for Chrome path detection messages
Claude doesn't see the MCP server
Verify
claude_desktop_config.json
is in the correct locationCheck JSON syntax is valid (use jsonlint.com)
Restart Claude Desktop completely
Check for any error messages in Claude Desktop
4a. Claude Code CLI doesn't see the MCP server
Installation Issues:
Verify
claude mcp add
command was successfulCheck command syntax:
claude mcp add puppeteer-real-browser -- npx puppeteer-real-browser-mcp-server@latest
Ensure you have the latest Claude Code CLI version
Scope and Configuration:
Check which scope you used: local (default), project, or user
For local scope: ensure you're in the correct project directory
For project scope: verify
.mcp.json
exists in project rootFor user scope: check user config directory
MCP Server Status:
Use
/mcp
command in Claude Code to check server statusLook for the "puppeteer-real-browser" server in the list
Check if server status shows "connected" or error messages
Environment Variables:
If using custom environment variables (Chrome path, proxy), verify they're correctly set
Test without environment variables first:
claude mcp add puppeteer-real-browser -- npx puppeteer-real-browser-mcp-server@latest
Node.js and npx Issues:
Verify Node.js version 18+:
node --version
Test npx directly:
npx puppeteer-real-browser-mcp-server@latest
Clear npm cache:
npm cache clean --force
Protocol Version Issues (Known Issue):
Claude CLI may show protocolVersion validation errors despite correct configuration
This is a known issue with internal validation in Claude CLI
Server may still work despite validation warnings
Re-adding Server:
# Remove and re-add if issues persist claude mcp remove puppeteer-real-browser claude mcp add puppeteer-real-browser -- npx puppeteer-real-browser-mcp-server@latest
4b. Cursor IDE doesn't see the MCP server
Config File Location Issues:
Verify
mcp.json
is in the correct location:Global:
~/.cursor/mcp.json
(%USERPROFILE%\.cursor\mcp.json
on Windows)Project:
.cursor/mcp.json
in your project root
Ensure filename is exactly
mcp.json
(notmcp.json.txt
)Check file permissions allow reading
JSON Syntax Validation:
Use jsonlint.com to validate JSON syntax
Common issues: missing commas, incorrect quotes, trailing commas
Ensure proper escaping of Windows paths:
"C:/Program Files/Google/Chrome/Application/chrome.exe"
Cursor IDE Restart Process:
Close Cursor IDE completely (check Task Manager on Windows)
Wait 5 seconds
Restart Cursor IDE
Open Command Palette and check MCP servers are listed
Environment Variables:
Verify Node.js is accessible:
node --version
Check PATH includes npm:
npm --version
Clear any conflicting environment variables
Cursor IDE Version Compatibility:
Ensure Cursor IDE version supports MCP (latest versions)
Update Cursor IDE if using an older version
Check Cursor IDE documentation for MCP requirements
Permission denied errors
On Linux/Mac: Try
sudo npm install -g puppeteer-real-browser-mcp-server
Or use nvm to manage Node.js without sudo
On Windows: Run command prompt as Administrator
Detection issues
Use appropriate delays between actions for better reliability
Add random delays with
random_scroll
Use proxy if needed:
proxy: "http://proxy.example.com:8080"
Memory leaks
Always close browser instances with
browser_close
when doneDon't initialize multiple browsers without closing previous ones
Check for uncaught exceptions that might prevent cleanup
Timeout errors
Increase timeout values:
{ "timeout": 60000 }
Use
wait
tool before interacting with elementsCheck network connectivity and website response times
Frequently Asked Questions
Q: When should I use npm install vs npx? A:
Use npx (recommended for most users): When using with Claude Desktop, Claude Code CLI, or Cursor IDE. The npx command in your config automatically downloads and runs the latest version without installation.
Use npm install -g: Only if you want to run the server directly from command line frequently, or if you're developing/contributing to the project.
Never needed: If you're just a Claude Desktop/Claude Code CLI user following the Quick Start guide - npx handles everything!
Q: Should I use Claude Desktop or Claude Code CLI? A: Both are excellent choices, depending on your needs:
Claude Desktop:
Best for: Simple web browsing automation, content extraction, basic form filling
Setup: Manual JSON config file editing
Sharing: Individual use only
Interface: Desktop GUI application
Authentication: None required
Claude Code CLI:
Best for: Development workflows, team collaboration, project-specific automation
Setup: Simple command-line setup (
claude mcp add
)Sharing: Supports team sharing via project scope
Interface: Command-line integration with IDEs
Authentication: OAuth support available
Advanced Features: Environment variables, scope control, server monitoring
Use Claude Code CLI if you:
Work in development teams
Need project-specific browser automation
Want environment variable configuration
Prefer command-line workflows
Need server health monitoring
Use Claude Desktop if you:
Want a simple GUI experience
Do individual browsing automation
Don't need team collaboration features
Prefer visual interfaces over command-line
Q: Why do we use @latest in the npx command?
A: The @latest
tag ensures you always get the newest version with bug fixes and security updates. Without it, npx might cache an older version. It's especially important for actively maintained projects.
Q: Does this work with headless browsers?
A: Yes, set headless: true
in browser_init options.
Q: Can I use multiple browsers at once? A: Currently supports one browser instance. Close the current one before starting a new one.
Q: What captchas can it solve? A: Supports reCAPTCHA, hCaptcha, and Cloudflare Turnstile through puppeteer-real-browser.
Q: Is this detectable by websites? A: puppeteer-real-browser includes anti-detection features, but no solution is 100% undetectable.
Q: Can I use custom Chrome extensions?
A: Yes, through the plugins
option in browser_init.
Q: Does it work on all operating systems? A: Yes, tested on Windows, macOS, and Linux. The server automatically detects Chrome installations on all platforms.
Q: What's the difference between Claude Desktop, Claude Code CLI, and Cursor IDE configurations? A: Here's a comparison:
Feature | Claude Desktop | Claude Code CLI | Cursor IDE |
Setup Method | Manual JSON editing | Command-line (
) | One-click install OR manual JSON |
Config Location |
|
(scoped) |
|
Team Sharing | No | Yes (project scope) | Yes |
Environment Variables | Limited support | Full support | Full support |
Scope Control | No | Yes (local/project/user) | Project/Global |
Server Monitoring | No | Yes (
command) | Limited |
Authentication | None | OAuth available | OAuth available |
Best For | Individual GUI use | Development teams | Code-focused workflows |
Command Examples:
Claude Desktop: Edit config file with JSON
Claude Code CLI:
claude mcp add puppeteer-real-browser -- npx puppeteer-real-browser-mcp-server@latest
Cursor IDE: One-click install or manual JSON config
Q: What if Chrome is installed in a non-standard location? A: Version 1.3.0 dramatically improves Chrome detection. The server now searches 15+ locations including portable installations and uses Windows Registry detection. If Chrome is still not found automatically, you can:
Set environment variable:
set CHROME_PATH="C:\Your\Chrome\Path\chrome.exe"
Use the
customConfig.chromePath
option:{"customConfig": {"chromePath": "C:\\Custom\\Chrome\\chrome.exe"}}
Q: Why am I getting "Chrome not found" or ECONNREFUSED errors on Windows? A: Version 1.3.0 includes comprehensive fixes for Windows Chrome detection and connection issues. The server now automatically searches these locations and more:
C:\Program Files\Google\Chrome\Application\chrome.exe
C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe
%USERPROFILE%\AppData\Local\Google\Chrome\Application\chrome.exe
Chrome Canary installations
Portable Chrome installations
Registry-detected installations
The server also implements multiple connection strategies with automatic fallback between localhost and 127.0.0.1, plus enhanced Windows-specific Chrome flags for better compatibility.
Q: I'm still getting ECONNREFUSED errors after upgrading to v1.3.0. What should I do? A: Try these steps in order:
Set the
CHROME_PATH
environment variable to your Chrome locationKill all existing Chrome processes:
taskkill /f /im chrome.exe
Check your Windows hosts file contains:
127.0.0.1 localhost
Try running your IDE as Administrator
Add Chrome to Windows Defender exclusions
If using a VPN/proxy, try disabling it temporarily
Debug Mode
To enable debug logging:
Or when running from source:
Getting Help
If you're still having issues:
Check the GitHub Issues
Create a new issue with:
Your operating system
Node.js version (
node --version
)npm version (
npm --version
)Full error message
Steps to reproduce the problem
Development
Project Structure
Building from Source
Adding New Tools
To add a new tool:
Add the tool definition to the
TOOLS
array insrc/index.ts
Implement the tool handler in the
CallToolRequestSchema
handlerTest the new tool functionality
Testing
This project includes a comprehensive testing suite with multiple categories optimized for different purposes:
Quick Tests (CI/CD) - ~30 seconds
Comprehensive Tests - ~5-10 minutes
Performance Testing - ~2-3 minutes
Performance tests measure:
Browser initialization timing (5 trials)
Navigation performance across different site types
Concurrent operation handling
Session longevity testing (30+ operations over 30 seconds)
Debug Tools - ~10 seconds
Debug tools provide:
Environment validation (Node.js version, platform, memory)
Chrome installation detection with specific paths
Quick server health check with startup timing
Network connectivity validation
Build status verification
All Tests - ~7-13 minutes
The test dashboard provides:
Unified execution of multiple test categories
Real-time progress reporting
Performance metrics and timing
Overall test status summary
Recommendations for failed tests
JSON results saved to
test-results/
directory
Integration Testing
For detailed testing information, see TESTING.md.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature
)Commit your changes (
git commit -m 'Add some amazing feature'
)Push to the branch (
git push origin feature/amazing-feature
)Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
This MCP server is based on the excellent puppeteer-real-browser library by ZFC-Digital.
Thank you to the puppeteer-real-browser team for creating such a powerful and detection-resistant browser automation solution!
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A Model Context Protocol server that enables AI assistants to control a real web browser with stealth capabilities, avoiding bot detection while performing tasks like clicking, filling forms, taking screenshots, and extracting data.
Related MCP Servers
- -securityFlicense-qualityA Model Control Protocol server that enables AI assistants to control a browser through tools for web automation tasks like navigation, typing, clicking, and taking screenshots.Last updated -
- -securityFlicense-qualityA Model Control Protocol server that enables AI assistants to control a browser through tools for web automation tasks like navigation, typing, clicking, and taking screenshots.Last updated -
- -securityFlicense-qualityA Model Control Protocol server that enables AI assistants to control a browser, allowing them to perform web automation tasks like navigation, typing, clicking, and taking screenshots.Last updated -
- -securityAlicense-qualityA Model Context Protocol server that enables AI assistants to control web browsers programmatically, allowing for web automation through natural language commands.