Puppeteer Real Browser MCP server

The Puppeteer Real Browser MCP Server allows AI assistants like Claude to control a real web browser, enabling them to navigate websites, fill forms, extract content, and perform complex web automation tasks while avoiding bot detection.

Installation

Claude Desktop

1. First, make sure Node.js (version 18 or higher) is installed on your system

   • Download from nodejs.org
   • Verify installation: node --version

2. Configure Claude Desktop:

   For Windows:

   1. Navigate to: %APPDATA%\Claude\
   2. Open or create claude_desktop_config.json
   3. Add this configuration:
   

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

   For Mac:

   1. Go to: ~/Library/Application Support/Claude/
   2. Open or create claude_desktop_config.json
   3. 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
   

3. Restart Claude Desktop completely

With Claude Code CLI

Use the claude mcp add command:

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

For custom Chrome path or proxy settings:

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

With Cursor IDE

Configure via Cursor IDE settings:

1. Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
2. Search for "Cursor Settings"
3. Click on "MCP" in the sidebar
4. Browse and install browser automation tools with one click

Or manually create configuration:

Create .cursor/mcp.json in your project directory or ~/.cursor/mcp.json in your home directory:

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

Usage

After installation, you can ask Claude to perform various web-based tasks:

Basic Examples

Initialize browser and navigate:

Initialize a browser and navigate to google.com

Fill forms:

Fill in the search form with 'test query'

Extract content:

Get all the product names from this e-commerce page

Handle captchas:

Handle any captchas that appear on this page

Advanced Browser Configuration

You can customize browser behavior when initializing:

Headless mode:

Initialize a browser with headless mode enabled

Using a proxy:

Initialize a browser with proxy server https://proxy.example.com:8080

Custom Chrome path (if detection fails):

Initialize browser with custom Chrome path at C:\Program Files\Google\Chrome\Application\chrome.exe

Available Tools

Core Browser Tools

Tool	Description
browser_init	Initialize browser with stealth features
navigate	Go to a specific URL
get_content	Extract HTML or text content
browser_close	Close the browser instance

Interaction Tools

Tool	Description
click	Click on elements
type	Enter text into forms
wait	Wait for elements or time
find_selector	Find elements containing specific text

Advanced Features

Tool	Description
random_scroll	Perform natural-looking scrolling
solve_captcha	Attempt to solve captchas

Troubleshooting

Common Issues

Chrome not found:

• Windows: Specify path with CHROME_PATH environment variable
• Mac: Ensure Chrome is in /Applications/Google Chrome.app/
• Linux: Install with sudo apt-get install -y google-chrome-stable

ECONNREFUSED errors on Windows:

• Set CHROME_PATH to your Chrome location
• Kill all Chrome processes: taskkill /f /im chrome.exe
• Check hosts file contains: 127.0.0.1 localhost
• Try running as Administrator

Permission denied errors:

• Linux/Mac: sudo npm install -g puppeteer-real-browser-mcp-server
• Windows: Run command prompt as Administrator

Claude doesn't see the MCP server:

• Verify config file is in correct location
• Check JSON syntax is valid
• Restart Claude completely

For more detailed troubleshooting, check the documentation on the GitHub repository.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "puppeteer-real-browser" '{"command":"npx","args":["puppeteer-real-browser-mcp-server@latest"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect