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.
Puppeteer Real Browser MCP Server
A Model Context Protocol (MCP) server that provides AI assistants with powerful, detection-resistant browser automation capabilities using puppeteer-real-browser.
Table of Contents
- Quick Start for Beginners
- Introduction
- Features
- Prerequisites
- Installation
- Usage
- Available Tools
- Advanced Features
- Configuration
- Troubleshooting
- Development
- Testing
- Contributing
- 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, take screenshots, and much more, all while avoiding bot detection.
Step-by-Step Setup
1. Install Node.js
- 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. Set Up with Claude Desktop (No Installation Required)
The npx command will automatically download and run the latest version, so no manual installation is needed.
3. 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
4. Restart Claude Desktop
Close and reopen Claude Desktop completely.
5. Test It Works
In Claude Desktop, try saying:
"Initialize a browser and navigate to google.com, then take a screenshot"
If everything is working, Claude should be able to:
- Start a browser
- Navigate to Google
- Take and show you a screenshot
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"
- Take screenshots: "Show me what this page looks like"
- 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, take screenshots, 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
- Standard installations:
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
From npm
From source
Usage
With Claude Desktop
Add to Claude Desktop config:
With Cursor IDE
Cursor IDE has different MCP configuration requirements. Here are the setup methods for 2025:
Method 1: One-Click Installation (Recommended for 2025)
- 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 directory - Global: Create
~/.cursor/mcp.json
in your home directory
Basic Configuration:
Windows-Specific Configuration (if experiencing Chrome path issues):
Advanced Configuration with Proxy and Custom Options:
Platform-Specific Chrome Paths for Cursor IDE
Windows:
Alternative paths to try:
"C:/Program Files (x86)/Google/Chrome/Application/chrome.exe"
"%LOCALAPPDATA%/Google/Chrome/Application/chrome.exe"
macOS:
Linux:
Alternative paths: /usr/bin/chromium-browser
, /snap/bin/chromium
Cursor IDE vs Claude Desktop Configuration Differences
Aspect | Claude Desktop | Cursor IDE |
---|---|---|
Config Location | %APPDATA%\Claude\claude_desktop_config.json | ~/.cursor/mcp.json or .cursor/mcp.json |
Setup Method | Manual JSON editing | One-click install OR manual JSON |
Authentication | None required | OAuth support available |
Environment Variables | Limited support | Full environment variable support |
Chrome Path Detection | Automatic | May require manual configuration |
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 take a screenshot"
If successful, you should see:
- Browser window opening
- Navigation to Google
- Screenshot 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
- Add explicit Chrome path in
- "Permission denied"
- Use
sudo npm install -g puppeteer-real-browser-mcp-server
on Linux/Mac - Run Command Prompt as Administrator on Windows
- Use
- Configuration not loading
- Ensure file is named exactly
mcp.json
(notmcp.json.txt
) - Check file is in correct directory
- Restart Cursor IDE after changes
- Ensure file is named exactly
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 |
---|---|---|---|
browser_init | Initialize stealth browser with advanced options | None | headless , disableXvfb , ignoreAllFlags , proxy , plugins , connectOption |
navigate | Navigate to a URL | url | waitUntil |
screenshot | Take a screenshot of page or element | None | fullPage , selector |
get_content | Get page content (HTML or text) | None | type , selector |
browser_close | Close the browser instance | None | None |
Interaction Tools
Tool Name | Description | Required Parameters | Optional Parameters |
---|---|---|---|
click | Standard click on element | selector | waitForNavigation |
type | Type text into input field | selector , text | delay |
wait | Wait for various conditions | type , value | timeout |
find_selector | Find CSS selector for element containing specific text | text | elementType , exact |
Behavior Tools
Tool Name | Description | Required Parameters | Optional Parameters |
---|---|---|---|
random_scroll | Perform random scrolling with natural timing | None | None |
Element Discovery Tools
Tool Name | Description | Required Parameters | Optional Parameters |
---|---|---|---|
find_selector | Find CSS selector for element containing specific text | text | elementType , exact |
Anti-Detection Tools
Tool Name | Description | Required Parameters | Optional Parameters |
---|---|---|---|
solve_captcha | Attempt to solve captchas | type | 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 locations - Linux: 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
function - Adjust 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):
- Manual Chrome Path Configuration:
- Network Troubleshooting:
- Chrome Process Management:
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:
Step 3: Windows Launch Arguments For Windows compatibility, use these launch arguments:
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 PowerShell - Test 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
first - Check console output for Chrome path detection messages
- Claude doesn't see the MCP server
- Verify
claude_desktop_config.json
is in the correct location - Check JSON syntax is valid (use jsonlint.com)
- Restart Claude Desktop completely
- Check for any error messages in Claude Desktop
- Verify
4a. 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
- Global:
- Ensure filename is exactly
mcp.json
(notmcp.json.txt
) - Check file permissions allow reading
- Verify
- 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
- Verify Node.js is accessible:
- 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
- On Linux/Mac: Try
- 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 done - Don't initialize multiple browsers without closing previous ones
- Check for uncaught exceptions that might prevent cleanup
- Always close browser instances with
- Timeout errors
- Increase timeout values:
{ "timeout": 60000 }
- Use
wait
tool before interacting with elements - Check network connectivity and website response times
- Increase timeout values:
Frequently Asked Questions
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 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 location - Kill 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
handler - Test 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
- Screenshot generation speed (viewport vs full page)
- 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.
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
- -securityAlicense-qualityAI-driven browser automation server that implements the Model Context Protocol to enable natural language control of web browsers for tasks like navigation, form filling, and visual interaction.Last updated -1PythonMIT License
- -security-license-qualityA Model Context Protocol server that enables AI assistants to control Chrome browsers through the Chrome DevTools Protocol, allowing for navigation, clicking, typing, and extracting page information.Last updated -3TypeScript
- -securityAlicense-qualityA streamlined Model Context Protocol server that enables AI models to perform stealth browser automation using Patchright, avoiding detection by anti-bot systems while providing essential web interaction capabilities.Last updated -3TypeScriptApache 2.0
- -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 -TypeScript