MCP Browser

Give your AI a real browser.

MCP server that lets AI assistants browse the web through your real Chrome — with your cookies, sessions, and fingerprint. No bot detection. No CAPTCHAs.

Quick Start (30 seconds)

No installation needed. Just add the config to your MCP client:

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json (Mac/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@wgarrido/mcp-browser"],
      "env": {
        "CHROME_HEADLESS": "true"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add browser -- npx -y @wgarrido/mcp-browser

VS Code / Cursor

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@wgarrido/mcp-browser"],
      "env": {
        "CHROME_HEADLESS": "true"
      }
    }
  }
}

That's it. Chrome launches automatically in the background. Start browsing.

Related MCP server: Blueprint MCP

Why MCP Browser?

Available Tools (15)

Core

Persistent Sessions

Keep tabs open across multiple tool calls for multi-step workflows:

Most tools accept an optional tab_id to reuse a persistent session instead of opening a new page.

Usage Examples

Just talk naturally to your AI:

• "Search for the latest Node.js release notes" → web_search + fetch_page

• "Read and summarize this article: https://..." → fetch_readable

• "Compare pricing on these two pages" → multi_fetch

• "Take a screenshot of https://..." → screenshot

• "Log into this site, then scrape my dashboard" → open_tab + click_and_navigate + fetch_page

• "Extract all /docs/ links from this page" → extract_links

• "Crawl this site 2 levels deep" → crawl

• "Watch this page for changes every 30 seconds" → monitor_page

Advanced: Use Your Own Chrome Sessions

By default, MCP Browser launches Chrome in headless mode (background, no window). This is the simplest setup.

If you want to use your existing cookies and logged-in sessions, launch Chrome manually with CDP enabled, then point MCP Browser to it:

Launch Chrome with CDP

Mac:

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 --no-first-run

Linux:

google-chrome --remote-debugging-port=9222 --no-first-run

Windows (PowerShell):

& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 --no-first-run

Or use the included scripts:

./scripts/launch-chrome.sh       # Mac/Linux
.\scripts\launch-chrome.ps1      # Windows

Important: Chrome must be started fresh. If it's already running, the CDP flag is ignored. Quit Chrome first, or use --user-data-dir="/tmp/chrome-cdp" for a separate profile.

Config without headless

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@wgarrido/mcp-browser"],
      "env": {
        "CDP_URL": "http://localhost:9222"
      }
    }
  }
}

Configuration

All settings are optional. Pass them via env in your MCP config:

Example with custom settings:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@wgarrido/mcp-browser"],
      "env": {
        "CHROME_HEADLESS": "true",
        "SEARCH_ENGINE": "duckduckgo",
        "DEFAULT_TIMEOUT": "60000",
        "MAX_CONTENT_LENGTH": "100000"
      }
    }
  }
}

Features

• Headless mode — Chrome runs in the background, auto-launched by the server

• Anti-bot stealth — Hides navigator.webdriver, fakes plugins, languages, and permissions

• Cloudflare handling — Detects Turnstile/interstitial challenges and waits up to 15s for resolution

• Cookie banner dismissal — Auto-clicks consent overlays (GDPR, OneTrust, CookieBot, Reddit, 40+ patterns)

• Smart DOM cleaning — Strips nav, sidebars, footers, ads, modals, and action links

• URL rewriting — Redirects SPAs to scraping-friendly versions (e.g. reddit.com → old.reddit.com)

• Google → DuckDuckGo fallback — If Google shows a CAPTCHA, search falls back automatically

• Persistent sessions — Keep tabs open for multi-step workflows (login, forms, navigation chains)

• LRU cache — Avoids redundant fetches with configurable TTL

• Concurrency control — Semaphore limits concurrent tabs to prevent resource exhaustion

• Multi-profile support — Connect to multiple Chrome instances via named profiles

Troubleshooting

"Cannot connect to Chrome" Chrome must be running with --remote-debugging-port=9222, or set CHROME_HEADLESS=true for auto-launch.

"Port 9222 already in use" Another Chrome instance is using CDP. Close it or use a different port:

./scripts/launch-chrome.sh 9333

Then set CDP_URL=http://localhost:9333.

"Page timeout" Increase the timeout: "DEFAULT_TIMEOUT": "60000"

"Empty results from web_search" Google may show a CAPTCHA. Switch to DuckDuckGo: "SEARCH_ENGINE": "duckduckgo"

"Cloudflare challenge page" The server auto-waits up to 15s for Cloudflare challenges. If it needs manual verification, use open_tab to create a persistent session, solve it in Chrome, then use the tab_id with other tools.

"MCP error -32000: Connection closed" This can have two causes:

1. Chrome is not running with CDP enabled — If you're not using CHROME_HEADLESS=true, make sure Chrome is launched with --remote-debugging-port=9222 before starting the server. Verify with:

   curl http://localhost:9222/json/version

   If this returns an error, Chrome is not listening. See Launch Chrome with CDP.

2. Corrupted npx cache — If you see TypeError: Comparator is not a constructor in the logs, the npx cache is corrupted. Clear it and retry:

   rm -rf ~/.npm/_npx/*
   # The next npx -y @wgarrido/mcp-browser call will re-download cleanly

Development

git clone https://github.com/wgarrido/mcp-browser.git
cd mcp-browser
npm install
npm run dev    # Run with hot reload
npm run build  # Build for production

Requirements

• Node.js 18+

• Google Chrome or Chromium

License

MIT