brave-real-browser-mcp-server 2.9.17 → 2.9.19

package/README.md

@@ -114,8 +114,8 @@ assistants to control a real browser, extract content, and more.
 
 - **🔄 Auto-Update System**: Automatically updates all dependencies to latest versions on every `npm install`
 - **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)
+- **Enhanced Windows support**: Comprehensive Brave detection and ECONNREFUSED error fixes (v1.3.0)
+- **Smart Brave 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 brave-real-browser options
@@ -133,25 +133,25 @@ assistants to control a real browser, extract content, and more.
 
 - Node.js >= 18.0.0
 - npm or yarn
-- Google Chrome or Chromium browser installed
+- Brave Browser installed (recommended) or Google Chrome/Chromium as fallback
 - 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`
+- Brave Browser installation (automatic detection in v1.3.0+ includes):
+  - Standard installations: `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`
+  - 32-bit installations: `C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`
+  - User installations: `%LOCALAPPDATA%\BraveSoftware\Brave-Browser\Application\brave.exe`
+  - Brave Beta/Nightly: `%LOCALAPPDATA%\BraveSoftware\Brave-Browser-Beta\Application\brave.exe`
   - Portable installations and Registry-detected paths
-  - Manual path specification: Use `CHROME_PATH` environment variable
+  - Manual path specification: Use `BRAVE_PATH` environment variable
 
 **macOS:**
-- Google Chrome or Chromium must be installed in `/Applications/`
+- Brave Browser must be installed in `/Applications/Brave Browser.app`
 
 **Linux:**
-- Install Chrome/Chromium: `sudo apt-get install -y google-chrome-stable` or `sudo apt-get install -y chromium-browser`
+- Install Brave: `sudo apt install brave-browser` or download from https://brave.com/linux/
 - Install xvfb for headless operation: `sudo apt-get install -y xvfb`
 
 ## Installation for Developers
@@ -231,11 +231,11 @@ This command:
 
 #### Method 2: Add with Environment Variables
 
-If you need to configure proxy settings or custom Chrome paths:
+If you need to configure proxy settings or custom Brave paths:
 
 ```bash
 claude mcp add brave-real-browser \
-  -e CHROME_PATH="/path/to/chrome" \
+  -e BRAVE_PATH="/path/to/brave" \
   -e PROXY_URL="http://proxy:8080" \
   -- npx brave-real-browser-mcp-server@latest
 ```
@@ -262,7 +262,7 @@ claude mcp add-json brave-real-browser '{
   "command": "npx",
   "args": ["brave-real-browser-mcp-server@latest"],
   "env": {
-    "CHROME_PATH": "/path/to/chrome",
+    "BRAVE_PATH": "/path/to/brave",
     "PROXY_URL": "http://proxy:8080"
   }
 }'
@@ -337,7 +337,7 @@ Cursor IDE uses the same npx approach - no installation needed! Here are the set
 
 > **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):**
+**Windows-Specific Configuration (if experiencing Brave path issues):**
 ```json
 {
   "mcpServers": {
@@ -345,7 +345,7 @@ Cursor IDE uses the same npx approach - no installation needed! Here are the set
       "command": "npx",
       "args": ["brave-real-browser-mcp-server@latest"],
       "env": {
-        "CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
+        "BRAVE_PATH": "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"
       }
     }
   }
@@ -354,7 +354,7 @@ Cursor IDE uses the same npx approach - no installation needed! Here are the set
 
 > **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:**
+**Advanced Configuration with Custom Brave Path:**
 ```json
 {
   "mcpServers": {
@@ -362,7 +362,7 @@ Cursor IDE uses the same npx approach - no installation needed! Here are the set
       "command": "npx",
       "args": ["brave-real-browser-mcp-server@latest"],
       "env": {
-        "CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
+        "BRAVE_PATH": "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"
       }
     }
   }
@@ -371,34 +371,34 @@ Cursor IDE uses the same npx approach - no installation needed! Here are the set
 
 > **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
+#### Platform-Specific Brave Paths for Cursor IDE
 
-If Chrome auto-detection fails, you can specify the Chrome path using the `CHROME_PATH` environment variable:
+If Brave auto-detection fails, you can specify the Brave path using the `BRAVE_PATH` environment variable:
 
 **Windows:**
 ```json
 "env": {
-  "CHROME_PATH": "C:/Program Files/Google/Chrome/Application/chrome.exe"
+  "BRAVE_PATH": "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"
 }
 ```
 Alternative Windows paths:
-- `"C:/Program Files (x86)/Google/Chrome/Application/chrome.exe"`
-- `"%LOCALAPPDATA%/Google/Chrome/Application/chrome.exe"`
+- `"C:/Program Files (x86)/BraveSoftware/Brave-Browser/Application/brave.exe"`
+- `"%LOCALAPPDATA%/BraveSoftware/Brave-Browser/Application/brave.exe"`
 
 **macOS:**
 ```json
 "env": {
-  "CHROME_PATH": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+  "BRAVE_PATH": "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
 }
 ```
 
 **Linux:**
 ```json
 "env": {
-  "CHROME_PATH": "/usr/bin/google-chrome"
+  "BRAVE_PATH": "/usr/bin/brave-browser"
 }
 ```
-Alternative Linux paths: `/usr/bin/chromium-browser`, `/snap/bin/chromium`
+Alternative Linux paths: `/usr/bin/brave`, `/snap/bin/brave`
 
 
 #### Testing Cursor IDE Setup
@@ -423,9 +423,9 @@ If successful, you should see:
    - Ensure Node.js 18+ is installed
 
 2. **"Browser failed to launch" on Windows**
-   - Add explicit Chrome path in `executablePath`
+   - Add explicit Brave path in `executablePath`
    - Try running Cursor IDE as Administrator
-   - Check Windows Defender isn't blocking Chrome
+   - Check Windows Defender isn't blocking Brave
 
 3. **"Permission denied"**
    - Use `sudo npm install -g brave-real-browser-mcp-server` on Linux/Mac
@@ -586,27 +586,27 @@ brave-real-browser implementation.
 
 ## Configuration
 
-### Automatic Chrome Path Detection (Enhanced in v1.3.0)
+### Automatic Brave Path Detection (Enhanced in v1.3.0)
 
-The server automatically detects Chrome installation paths across different operating systems with significantly improved Windows support:
+The server automatically detects Brave installation paths across different operating systems with significantly improved Windows support:
 
 - **Windows (v1.3.0+)**: 
-  - Registry-based detection for installed Chrome versions
+  - Registry-based detection for installed Brave 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
+  - Support for Brave Beta and Nightly fallback
+  - Environment variable detection (`BRAVE_PATH`, `PUPPETEER_EXECUTABLE_PATH`)
+  - Detailed troubleshooting guidance when Brave is not found
   
-- **macOS**: Looks for Chrome in `/Applications/Google Chrome.app/` and Chrome Canary locations
+- **macOS**: Looks for Brave in `/Applications/Brave Browser.app/` and Beta/Nightly locations
 
-- **Linux**: Checks multiple locations including `/usr/bin/google-chrome`, `/usr/bin/chromium-browser`, and snap installations
+- **Linux**: Checks multiple locations including `/usr/bin/brave-browser`, `/usr/bin/brave`, 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.
+The server now queries Windows Registry to find Brave 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
+If Brave is not found automatically, you can specify a custom path using:
+1. Environment variable: `set BRAVE_PATH="C:\Your\Brave\Path\brave.exe"`
+2. Browser init option: `customConfig.bravePath` 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:
@@ -662,11 +662,11 @@ When initializing the browser with `browser_init`, you can configure:
 
 ### Advanced Configuration Examples
 
-#### Specifying Custom Chrome Path
+#### Specifying Custom Brave Path
 ```json
 {
   "customConfig": {
-    "chromePath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
+    "bravePath": "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
   }
 }
 ```
@@ -709,14 +709,14 @@ For advanced users, you can modify the server behavior by editing the source cod
 
 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
+**Enhanced Brave Path Detection:**
+- Added Windows Registry-based Brave 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`)
+- Added support for Brave Beta and Nightly fallback
+- Environment variable support (`BRAVE_PATH`, `PUPPETEER_EXECUTABLE_PATH`)
 
 **Windows-Specific Launch Optimizations:**
-- 20+ Windows-specific Chrome flags for better compatibility
+- 20+ Windows-specific Brave 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)
@@ -731,12 +731,12 @@ Version 1.3.0 includes comprehensive fixes for the `connect ECONNREFUSED 127.0.0
 
 1. **Environment Variables (Recommended):**
    ```bash
-   set CHROME_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"
+   set BRAVE_PATH="C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe"
    ```
 
-2. **Manual Chrome Path Configuration:**
+2. **Manual Brave Path Configuration:**
    ```text
-   Ask Claude: "Initialize browser with custom Chrome path at C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
+   Ask Claude: "Initialize browser with custom Brave path at C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
    ```
 
 3. **Network Troubleshooting:**
@@ -750,10 +750,10 @@ Version 1.3.0 includes comprehensive fixes for the `connect ECONNREFUSED 127.0.0
    # Ensure: 127.0.0.1 localhost
    ```
 
-4. **Chrome Process Management:**
+4. **Brave Process Management:**
    ```bash
-   # Kill existing Chrome processes
-   taskkill /f /im chrome.exe
+   # Kill existing Brave processes
+   taskkill /f /im brave.exe
    ```
 
 ### Common Issues
@@ -812,20 +812,20 @@ Version 1.3.0 includes comprehensive fixes for the `connect ECONNREFUSED 127.0.0
    - 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
+   - Check if Brave is installed in standard locations
    - **Windows specific troubleshooting**:
      
-     **Step 1: Verify Chrome Installation Paths**
+     **Step 1: Verify Brave 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`
+     - `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`
+     - `C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`
+     - `%LOCALAPPDATA%\BraveSoftware\Brave-Browser\Application\brave.exe`
+     - `%PROGRAMFILES%\BraveSoftware\Brave-Browser\Application\brave.exe`
      
      **Step 2: Manual Path Configuration**
-     If Chrome is in a different location, specify it manually:
+     If Brave is in a different location, specify it manually:
      ```
-     Ask Claude: "Initialize browser with custom Chrome path at C:\Your\Chrome\Path\chrome.exe"
+     Ask Claude: "Initialize browser with custom Brave path at C:\Your\Brave\Path\brave.exe"
      ```
      
      **Step 3: Windows Launch Arguments**
@@ -836,15 +836,15 @@ Version 1.3.0 includes comprehensive fixes for the `connect ECONNREFUSED 127.0.0
      
      **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
+     - **Windows Defender**: Add Brave and Node.js to Windows Defender exclusions
+     - **Antivirus Software**: Temporarily disable antivirus to test if it's blocking Brave
      - **User Account Control**: Lower UAC settings temporarily for testing
-     - **Chrome Processes**: Kill any existing Chrome processes in Task Manager
+     - **Brave Processes**: Kill any existing Brave processes in Task Manager
      
-     **Step 5: Alternative Chrome Installation**
-     If Chrome detection still fails:
-     - Download Chrome directly from [google.com/chrome](https://www.google.com/chrome/)
-     - Install to default location (`C:\Program Files\Google\Chrome\`)
+     **Step 5: Alternative Brave Installation**
+     If Brave detection still fails:
+     - Download Brave directly from [brave.com/download](https://brave.com/download/)
+     - Install to default location (`C:\Program Files\BraveSoftware\Brave-Browser\`)
      - Restart your IDE after installation
      
      **Step 6: PowerShell vs Command Prompt**
@@ -857,10 +857,10 @@ Version 1.3.0 includes comprehensive fixes for the `connect ECONNREFUSED 127.0.0
      - Clear npm cache: `npm cache clean --force`
      - Reinstall global packages: `npm install -g brave-real-browser-mcp-server@latest`
      
-   - **Linux**: Install dependencies: `sudo apt-get install -y google-chrome-stable`
-   - **macOS**: Ensure Chrome is in `/Applications/`
+   - **Linux**: Install dependencies: `sudo apt install brave-browser`
+   - **macOS**: Ensure Brave is in `/Applications/`
    - Try with `headless: true` first
-   - Check console output for Chrome path detection messages
+   - Check console output for Brave path detection messages
 
 4. **Claude doesn't see the MCP server**
    - Verify `claude_desktop_config.json` is in the correct location
@@ -1013,7 +1013,7 @@ A: brave-real-browser includes anti-detection features, but no solution is 100%
 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.
+A: Yes, tested on Windows, macOS, and Linux. The server automatically detects Brave installations on all platforms.
 
 **Q: What's the difference between Claude Desktop, Claude Code CLI, and Cursor IDE configurations?**
 A: Here's a comparison:
@@ -1034,30 +1034,30 @@ A: Here's a comparison:
 - **Claude Code CLI**: `claude mcp add brave-real-browser -- npx brave-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
+**Q: What if Brave is installed in a non-standard location?**
+A: Version 1.3.0 dramatically improves Brave detection. The server now searches 15+ locations including portable installations and uses Windows Registry detection. If Brave is still not found automatically, you can:
+1. Set environment variable: `set BRAVE_PATH="C:\Your\Brave\Path\brave.exe"`
+2. Use the `customConfig.bravePath` option: `{"customConfig": {"bravePath": "C:\\Custom\\Brave\\brave.exe"}}`
+
+**Q: Why am I getting "Brave not found" or ECONNREFUSED errors on Windows?**
+A: Version 1.3.0 includes comprehensive fixes for Windows Brave detection and connection issues. The server now automatically searches these locations and more:
+- `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`
+- `C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe` 
+- `%LOCALAPPDATA%\BraveSoftware\Brave-Browser\Application\brave.exe`
+- `%USERPROFILE%\AppData\Local\BraveSoftware\Brave-Browser\Application\brave.exe`
+- Brave Beta and Nightly installations
+- Portable Brave 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.
+The server also implements multiple connection strategies with automatic fallback between localhost and 127.0.0.1, plus enhanced Windows-specific Brave 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`
+1. Set the `BRAVE_PATH` environment variable to your Brave location
+2. Kill all existing Brave processes: `taskkill /f /im brave.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
+5. Add Brave to Windows Defender exclusions
 6. If using a VPN/proxy, try disabling it temporarily
 
 ### Debug Mode