Browser Control MCP Server v3.1.0

Unified CDP-based browser control for AI agents via MCP (Model Context Protocol). Works with Chrome, Comet, Edge, Brave, and any Chromium-based browser.

Why CDP?

Previous versions (v1/v2) used AppleScript + JavaScript injection — limited to macOS and unable to access native browser features. This v3.0 upgrade uses the Chrome DevTools Protocol (CDP) directly over WebSocket, providing:

• Cross-platform: macOS, Linux, Windows, WSL, Docker

• 36 tools (up from 11 original / 26 JS-injected)

• Real input events: Click, type, drag via the browser engine (not DOM simulation)

• Accessibility tree: Full semantic page structure for AI understanding

• Network monitoring: Capture requests/responses with body extraction

• Performance tracing: CPU profiling and rendering analysis

• Device emulation: Mobile viewports, user agents, touch, DPR

• File upload: Native file input handling via CDP

• PDF generation: Print pages to PDF

• Screenshot: Full-page, element, and viewport screenshots

• Dialog handling: Alert, confirm, prompt auto-handling

Related MCP server: Browser-Debugger

Quick Start

1. Install Dependencies

cd /path/to/browser-control-mcp-oss
npm install

2. Launch Your Browser with CDP Enabled

macOS (Recommended) — Wrapper Apps:

Pre-built wrapper apps launch your browser with CDP enabled automatically. Just click to open like any normal app:

These wrappers use your existing browser profile (no --user-data-dir isolation). If the browser is already running, they bring it to the front.

macOS (Manual):

# Chrome
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug

# Comet
/Applications/Comet.app/Contents/MacOS/Comet \
  --remote-debugging-port=9223 \
  --user-data-dir=/tmp/comet-debug

# Edge
/Applications/Microsoft\ Edge.app/Contents/MacOS/Microsoft\ Edge \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/edge-debug

# Brave
/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/brave-debug

Linux:

# Chrome
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Edge
microsoft-edge --remote-debugging-port=9222 --user-data-dir=/tmp/edge-debug

# Brave
brave-browser --remote-debugging-port=9222 --user-data-dir=/tmp/brave-debug

Windows (PowerShell):

# Chrome
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 `
  --user-data-dir="$env:TEMP\chrome-debug"

# Edge
& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" `
  --remote-debugging-port=9222 `
  --user-data-dir="$env:TEMP\edge-debug"

Docker (headless):

docker run -d -p 9222:9222 \
  chromedp/headless-shell:latest \
  --remote-debugging-address=0.0.0.0 \
  --remote-debugging-port=9222

3. Configure in Claude Code (.claude.json)

{
  "mcpServers": {
    "chrome-control": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/browser-control-mcp-oss/server/index.js",
        "--browser", "chrome"
      ]
    },
    "comet-control": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/browser-control-mcp-oss/server/index.js",
        "--browser", "comet"
      ]
    }
  }
}

4. CLI Arguments

Tool Reference (36 Tools)

Tab & Navigation (10 tools)

JavaScript & Content (2 tools)

Interaction (10 tools)

Visual & Export (4 tools)

Device & Files (3 tools)

Accessibility (1 tool)

Monitoring (4 tools)

Performance (2 tools)

Device Emulation Presets

Key Modifier Flags (for press_key)

Combine with addition: Ctrl+Shift = 2 + 8 = 10

Architecture

Claude Code  ──stdio──>  MCP Server  ──WebSocket──>  Browser CDP
                          (index.js)                   (port 9222)
                             │
                             ├── Per-page WS connections (tab control)
                             └── Browser-level WS (tracing, browser ops)

• One unified codebase serves Chrome, Comet, Edge, Brave via --browser flag

• CDP HTTP API (/json/list, /json/new, /json/close) for tab management

• Per-page WebSocket for page-specific commands (DOM, Input, Runtime)

• Browser-level WebSocket for cross-page operations (Tracing, Browser)

• Auto-enabled domains: Runtime (console capture) and Page (navigation events) enabled on connection

• Network domain: Enabled on demand when network_requests is called with start: true

Error Responses (v3.1+)

Every tool error returns a structured payload so consumer agents can decide retry strategy programmatically — no string parsing required:

{
  "error":       "CDP connection lost: Inspector detached (reason=target closed)",
  "tool":        "execute_javascript",
  "reason_code": "inspector_detached",
  "recoverable": true,
  "next_action": "Call list_tabs and retry — the next request will reconnect lazily.",
  "cdp_extra":   { "cdp_reason": "target closed" }
}

Transport failures (a Chrome extension attaching via chrome.debugger.attach, a closed tab, a quit browser) now fail in < 50 ms instead of hanging for 30 s, and the next tool call transparently re-establishes the CDP connection (lazy reconnect — no manual restart needed).

Full reason_code taxonomy and recommended consumer-agent retry logic: docs/RESILIENCE.md. Release notes: CHANGELOG.md.

Troubleshooting

"ECONNREFUSED" Error

The browser is not running with CDP enabled. Launch it with --remote-debugging-port=9222.

"Page not found" Error

The target tab may have been closed. Call list_tabs to get current tab IDs.

Port Already in Use

Another browser instance is using port 9222. Either close it or use a different port:

node server/index.js --browser chrome --port 9223

Using with Existing Browser Profile

By default, --user-data-dir creates a separate profile. To use your existing profile, omit the flag — but note that only one Chrome instance can run at a time with CDP.

Remote/Docker CDP

For remote browsers or Docker containers, use the --host argument:

node server/index.js --browser chrome --host 192.168.1.100 --port 9222

Claude Code Skills (Powered by This Server)

A Claude Code skill consumes this CDP server for intelligent browser workflows:

Skills are defined in ~/.claude/commands/ and invoked as slash commands in Claude Code sessions.

Multi-Browser Strategy

Both browsers use this same unified server. The MCP tool prefix determines targeting:

• mcp__chrome-control__<tool> — Chrome

• mcp__comet-control__<tool> — Comet

Version History

Requirements

• Node.js: 18.0+ (uses node:http built-in)

• Browser: Any Chromium-based browser with --remote-debugging-port flag

• Dependencies: ws (WebSocket client), @modelcontextprotocol/sdk

License

MIT. See LICENSE.

Built by LostMind AI.