MCP server for puppeteer-real-browser
npm install @eikaramba/puppeteer-real-browser-mcp-server
ā ļø UNDER MAINTENANCE - This project is still being actively developed. Some features may be incomplete or change without notice.
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.
node --version
%APPDATA%\Claude\
claude_desktop_config.json
json
{
"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
$3
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"
$3
- 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)
$3
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
$3
If you want to run the server directly from the command line without using npx:
`bash
npm install -g puppeteer-real-browser-mcp-server@latest
`
After global installation, you can run:
`bash
puppeteer-real-browser-mcp-server
`
$3
`bash
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
$3
The configuration below uses npx to automatically download and run the latest version. No installation required!
`json
{
"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.
$3
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:
`bash
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:
`bash
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):
`bash
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):
`bash
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:
`bash
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:
`bash
/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:
- 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 | .mcp.json in project | Testing, project-specific |
| project | Shared with entire team | .mcp.json 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 improvements
- No 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
$3
Cursor IDE uses the same npx approach - no installation needed! Here are the setup methods:
#### Method 1: One-Click Installation (Recommended)
1. Open Cursor IDE
2. Open Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on Mac)
3. Search for "Cursor Settings" and select it
4. Click on "MCP" in the sidebar
5. Browse curated MCP servers and install browser automation tools with one-click
6. 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 (No Installation Required):
`json
{
"mcpServers": {
"puppeteer-real-browser": {
"command": "npx",
"args": ["puppeteer-real-browser-mcp-server@latest"]
}
}
}
`
> 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):
`json
{
"mcpServers": {
"puppeteer-real-browser": {
"command": "npx",
"args": ["puppeteer-real-browser-mcp-server@latest"],
"env": {
"CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
}
}
}
}
`
> 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:
`json
{
"mcpServers": {
"puppeteer-real-browser": {
"command": "npx",
"args": ["puppeteer-real-browser-mcp-server@latest"],
"env": {
"CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
}
}
}
}
`
> 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:
`json
"env": {
"CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
}
`
Alternative Windows paths:
- "C:/Program Files (x86)/Google/Chrome/Application/chrome.exe"
- "%LOCALAPPDATA%/Google/Chrome/Application/chrome.exe"
macOS:
`json
"env": {
"CHROME_PATH": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}
`
Linux:
`json
"env": {
"CHROME_PATH": "/usr/bin/google-chrome"
}
`
Alternative Linux paths: /usr/bin/chromium-browser, /snap/bin/chromium
#### Testing Cursor IDE Setup
After configuration:
1. Restart Cursor IDE completely
2. Open a new chat
3. 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:
1. "MCP server not found"
- Verify config file location and JSON syntax
- Use jsonlint.com to validate JSON
- Ensure Node.js 18+ is installed
2. "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
3. "Permission denied"
- Use sudo npm install -g puppeteer-real-browser-mcp-server on Linux/Mac
- Run Command Prompt as Administrator on Windows
4. Configuration not loading
- Ensure file is named exactly mcp.json (not mcp.json.txt)
- Check file is in correct directory
- Restart Cursor IDE after changes
$3
Start the server:
`bash
puppeteer-real-browser-mcp-server
`
Or if installed from source:
`bash
npm start
`
The server communicates via stdin/stdout using the MCP protocol.
$3
#### Basic Web Browsing
`text
User: "Initialize a browser and navigate to example.com"
AI: I'll initialize a stealth browser and navigate to the website.
[Uses browser_init and navigate tools]
`
#### Form Automation
`text
User: "Fill in the search form with 'test query'"
AI: I'll type that into the search field.
[Uses type tool with selector and text]
User: "Click the search button"
AI: I'll click the search button.
[Uses click tool]
`
#### Data Extraction
`text
User: "Get all the product names from this e-commerce page"
AI: I'll extract the product information from the page.
[Uses get_content tool with appropriate selectors]
User: "Save the page content as text"
AI: I'll get the text content of the entire page.
[Uses get_content tool with type: 'text']
User: "Save this page content as a markdown file"
AI: I'll extract the page content and save it as a formatted markdown file.
[Uses save_content_as_markdown tool with specified file path]
`
#### Working with Proxies
`text
User: "Initialize a browser with a proxy server"
AI: I'll set up the browser with your proxy configuration.
[Uses browser_init with proxy: "https://proxy.example.com:8080"]
`
Available Tools
$3
| 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 |
| get_content | Get page content (HTML or text) | None | type, selector |
| browser_close | Close the browser instance | None | None |
$3
| 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 |
$3
| Tool Name | Description | Required Parameters | Optional Parameters |
|-----------|-------------|---------------------|-------------------|
| random_scroll | Perform random scrolling with natural timing | None | None |
$3
| Tool Name | Description | Required Parameters | Optional Parameters |
|-----------|-------------|---------------------|-------------------|
| find_selector | Find CSS selector for element containing specific text | text | elementType, exact |
$3
| Tool Name | Description | Required Parameters | Optional Parameters |
|-----------|-------------|---------------------|-------------------|
| save_content_as_markdown | Extract page content and save it as a formatted markdown file | filePath | contentType, selector, formatOptions |
$3
| Tool Name | Description | Required Parameters | Optional Parameters |
|-----------|-------------|---------------------|-------------------|
| solve_captcha | Attempt to solve captchas | type | None |
Advanced Features
$3
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:
`text
User: "Find the submit button that says 'Sign Up'"
AI: I'll locate that button for you.
[Uses find_selector with text: "Sign Up", elementType: "button"]
AI: Found button at selector: "form > button.btn-primary:nth-of-type(2)"
`
This approach eliminates the need for manually crafted selectors and makes automation more reliable across different websites.
$3
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.
$3
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
$3
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:
1. Environment variable: set CHROME_PATH="C:\Your\Chrome\Path\chrome.exe"
2. Browser init option: customConfig.chromePath when initializing the browser
$3
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:
`
Please initialize a browser with headless mode enabled and a 30-second timeout
`
Claude will then use the browser_init tool with appropriate parameters:
`json
{
"headless": true,
"connectOption": {
"timeout": 30000
}
}
`
$3
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.
$3
When initializing the browser with browser_init, you can configure:
`json
{
"headless": false,
"disableXvfb": false,
"ignoreAllFlags": false,
"proxy": "https://proxy:8080",
"plugins": ["plugin1", "plugin2"],
"connectOption": {
"slowMo": 250,
"timeout": 60000
}
}
`
$3
#### Specifying Custom Chrome Path
`json
{
"customConfig": {
"chromePath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
}
}
`
#### Using a Proxy
`json
{
"headless": true,
"proxy": "https://username:password@proxy.example.com:8080"
}
`
#### Stealth Mode with Custom Options
`json
{
"headless": false,
"ignoreAllFlags": true,
"disableXvfb": false,
"connectOption": {
"slowMo": 100,
"devtools": false
}
}
`
$3
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
$3
š§ 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:
1. Environment Variables (Recommended):
`bash
set CHROME_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"
`
2. Manual Chrome Path Configuration:
`text
Ask Claude: "Initialize browser with custom Chrome path at C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
`
3. Network Troubleshooting:
`bash
# 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 localhost
`
4. Chrome Process Management:
`bash
# Kill existing Chrome processes
taskkill /f /im chrome.exe
`
$3
#### npx-Specific Issues
1. "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 and npm --version
- Reinstall Node.js from nodejs.org
- For NVM users, see the NVM-specific section below
2. "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
3. 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
4. Using NVM (Node Version Manager)?
- Standard npx commands may fail with NVM
- Solution 1: Use absolute paths in your config:
`json
{
"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
5. 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
1. "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
2. "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
3. 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 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
4. 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
4a. Claude Code CLI doesn't see the MCP server
- Installation Issues:
- Verify claude mcp add command was successful
- Check 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 root
- For user scope: check user config directory
- MCP Server Status:
- Use /mcp command in Claude Code to check server status
- Look 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:
`bash
# 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 (not mcp.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
5. 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
6. 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"
7. 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
8. Timeout errors
- Increase timeout values: { "timeout": 60000 }
- Use wait tool before interacting with elements
- Check network connectivity and website response times
$3
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 (claude mcp add) | One-click install OR manual JSON |
| Config Location | claude_desktop_config.json | .mcp.json (scoped) | .cursor/mcp.json |
| 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 (/mcp 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:
1. Set environment variable: set CHROME_PATH="C:\Your\Chrome\Path\chrome.exe"
2. 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:
1. Set the CHROME_PATH environment variable to your Chrome location
2. Kill all existing Chrome processes: taskkill /f /im chrome.exe
3. Check your Windows hosts file contains: 127.0.0.1 localhost
4. Try running your IDE as Administrator
5. Add Chrome to Windows Defender exclusions
6. If using a VPN/proxy, try disabling it temporarily
$3
To enable debug logging:
`bash
DEBUG=true npm start
`
Or when running from source:
`bash
DEBUG=true npm run dev
`
$3
If you're still having issues:
1. Check the GitHub Issues
2. 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
$3
`text
puppeteer-real-browser-mcp-server/
āāā src/
ā āāā index.ts # Main server implementation
ā āāā stealth-actions.ts # Browser interaction functions
āāā test/
ā āāā test-server.ts # Test script
āāā package.json
āāā tsconfig.json
`
$3
`bash
Install dependencies
npm install
Run in development mode
npm run dev
Build for production
npm run build
Test the server
npm test
`
$3
To add a new tool:
1. Add the tool definition to the TOOLS array in src/index.ts
2. Implement the tool handler in the CallToolRequestSchema handler
3. Test the new tool functionality
Testing
This project includes a comprehensive testing suite with multiple categories optimized for different purposes:
$3
`bash
npm run test:quick # Fast Jest tests for protocol compliance
npm test # Alias for test:quick
`
$3
`bash
npm run test:full # End-to-end MCP client testing
`
$3
`bash
npm run test:performance # Browser performance benchmarking
`
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)
$3
`bash
npm run test:debug # Environment diagnostics and troubleshooting
`
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
$3
`bash
npm run test:all # Runs quick + full + performance tests
npm run test:dashboard # Unified test runner with reporting
`
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
$3
`bash
npm run test:integration # Claude Code CLI integration testing
`
For detailed testing information, see TESTING.md.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)