Browser MCP Server

🌐 Browser MCP Server

The most comprehensive Browser MCP Server for AI agents — 70 tools with human-like behavior, stealth anti-detection, session reuse, multi-browser support, 50+ device presets, and token-optimized outputs.

Built on Playwright + Model Context Protocol.

---

✨ Key Features

| Feature | Description | |---|---| | 🤖 Human-Like Behavior | Bezier curve mouse movements, variable-speed typing, smooth scrolling — evades bot detection | | 🛡️ Stealth Anti-Detection | WebGL spoofing, canvas fingerprint noise, navigator.webdriver hidden, plugin/language spoofing | | 🔄 Session Reuse | Connect to existing Chrome via CDP or user-data-dir — keeps cookies, logins, tabs | | 🌍 Multi-Browser | Chromium, Firefox, WebKit — test across all engines | | 📱 50+ Device Presets | iPhone, iPad, Pixel, Galaxy, OnePlus, Desktop — full viewport/UA/touch emulation | | 🌐 Proxy Support | HTTP/HTTPS/SOCKS5 proxy with bypass rules | | 📊 Network Monitoring | Auto-capture all requests/responses, console logs, filter by type | | 📸 Visual Annotation | mark_page: numbered boxes on interactive elements — massive token savings | | 💾 Storage State | Save/load cookies + localStorage for cross-session persistence | | 🎯 Smart Actions | Natural language commands: "click Login", "type hello into search" | | 📉 Token Optimized | Compact outputs, configurable truncation — saves 60-80% tokens vs competitors | | 🎬 Video Recording | Record browser sessions for debugging and replay | | 📍 Geolocation | Override latitude/longitude for location-based testing | | 🔒 HTTPS Errors | Ignore certificate errors for internal/staging sites |

---

🚀 Quick Start

Install

git clone https://github.com/user/browser-mcp-server.git
cd browser-mcp-server
npm install
npx playwright install
npm run build

Run

# Auto-detect: tries CDP on port 9222, falls back to launching a new browser
node dist/index.js

# Connect to existing Chrome (preserves your logged-in sessions)
chrome --remote-debugging-port=9222
node dist/index.js --cdp http://localhost:9222

# Reuse Chrome profile (keeps all cookies, logins, extensions)
node dist/index.js --user-data-dir "C:\Users\you\AppData\Local\Google\Chrome\User Data"

# Launch Firefox with iPhone emulation and proxy
node dist/index.js --browser firefox --device "iPhone 15" --proxy-server http://proxy:8080

VS Code MCP Configuration

Add to .vscode/mcp.json:

{
  "servers": {
    "browser": {
      "type": "stdio",
      "command": "node",
      "args": ["path/to/browser-mcp-server/dist/index.js"]
    }
  }
}

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["path/to/browser-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

---

🛠️ All 70 Tools

Connection (1)

| Tool | Description | |---|---| | browser_connect | Connect to browser (CDP/profile/temp launch). Multi-browser, device emulation, proxy. |

Navigation (5)

| Tool | Description | |---|---| | navigate | Navigate to URL with configurable wait conditions | | go_back | Go back in browser history | | go_forward | Go forward in browser history | | reload | Reload current page | | wait_for_navigation | Wait for page navigation to complete |

Page/Tab Management (4)

| Tool | Description | |---|---| | list_pages | List all open tabs | | new_page | Open new tab (optionally with URL) | | close_page | Close a tab by ID | | focus_page | Bring a tab to front/focus |

Interaction — Human-Like (14)

| Tool | Description | |---|---| | click | Click element with Bezier curve mouse movement | | type_text | Type with human-like keystroke timing | | fill_form | Fill multiple form fields with natural pauses | | select_option | Select dropdown option by value or label | | check_checkbox | Check/uncheck checkbox or radio button | | hover | Hover with natural mouse movement | | press_key | Press key or combo (Enter, Ctrl+C, Tab, etc.) | | scroll | Scroll with smooth human-like motion | | scroll_to_element | Scroll element into view | | wait_for_element | Wait for element to appear/disappear | | wait_for_text | Wait for specific text on page | | drag_and_drop | Drag element to target with natural motion | | upload_file | Upload file(s) to input | | handle_dialog | Accept or dismiss browser dialogs |

Reading/Observation — Token-Optimized (14)

| Tool | Description | |---|---| | get_page_content | Get visible text (default 4000 chars) | | get_page_html | Get HTML (truncated to save tokens) | | get_element_text | Get element text content | | get_element_attribute | Get element attribute value | | get_element_value | Get form element value | | element_exists | Quick true/false existence check | | element_count | Count elements matching selector | | get_bounding_box | Get element position and size | | take_screenshot | Screenshot page or element (PNG/base64) | | get_accessibility_tree | Compact ARIA accessibility tree | | get_form_elements | List form elements (compact format) | | get_links | List page links (deduplicated) | | get_table_data | Extract table data as structured JSON | | evaluate_javascript | Run JavaScript in page context |

Cookies & Storage (10)

| Tool | Description | |---|---| | get_cookies | Get cookies (compact format) | | set_cookies | Set cookies | | clear_cookies | Clear all cookies | | get_local_storage | Get localStorage | | set_local_storage | Set localStorage key-value pairs | | get_session_storage | Get sessionStorage | | set_session_storage | Set sessionStorage key-value pairs | | clear_storage | Clear localStorage, sessionStorage, or both | | save_storage_state | Save cookies + localStorage to JSON file | | load_storage_state | Load cookies + localStorage from JSON file |

Network Monitoring & Control (8)

| Tool | Description | |---|---| | wait_for_network_idle | Wait for all network requests to finish | | wait_for_url | Wait for URL to match pattern | | wait_for_response | Wait for network response matching URL | | wait_for_request | Wait for network request matching URL | | get_network_log | Get captured network requests/responses | | get_console_logs | Get captured console messages | | block_urls | Block URLs by pattern (ads, trackers, etc.) | | set_extra_headers | Set custom HTTP headers |

Device & Viewport (3)

| Tool | Description | |---|---| | set_viewport | Set viewport size for responsive testing | | emulate_device | Emulate device (50+ presets) | | list_devices | List all available device presets |

Geolocation & Permissions (3)

| Tool | Description | |---|---| | set_geolocation | Override browser geolocation | | grant_permissions | Grant browser permissions | | clear_permissions | Clear all granted permissions |

Frame/iFrame Support (3)

| Tool | Description | |---|---| | list_frames | List all frames on the page | | execute_in_frame | Run JavaScript in a specific frame | | click_in_frame | Click element inside a frame |

PDF (1)

| Tool | Description | |---|---| | save_as_pdf | Save page as PDF (A4, Letter, etc.) |

Visual Annotation — mark_page (5)

| Tool | Description | |---|---| | mark_page | Annotate page with numbered boxes on interactive elements | | unmark_page | Remove annotations | | click_element | Click by index from mark_page | | type_into_element | Type into element by index from mark_page | | mark_page_and_screenshot | Mark + screenshot (best for visual agents) |

Smart Tools (2)

| Tool | Description | |---|---| | get_page_summary | Ultra-compact page summary (minimal tokens) | | smart_action | Natural language browser action |

Browser Management (2)

| Tool | Description | |---|---| | get_browser_info | Get browser config details | | close_browser | Close browser and cleanup |

---

📱 Supported Device Presets (50+)

iPhones: SE, 12 Mini, 12, 12 Pro, 12 Pro Max, 13, 13 Pro, 14, 14 Pro, 14 Pro Max, 15, 15 Pro, 15 Pro Max, 16 Pro Max

iPads: Mini, Air, Pro 11, Pro 12.9, 10th Gen

Android: Pixel 5, 6, 7, 8 Pro, Galaxy S21, S23 Ultra, Z Fold 5, A54, OnePlus 12, Moto G, Xiaomi 14, Huawei P60

Desktop: Chrome 1920x1080, Chrome 1440, Firefox, Safari, Edge, Small Laptop, Ultrawide

Landscape: iPhone Landscape, iPad Landscape, Android Landscape

---

🔧 CLI Options

CONNECTION:
  --cdp <url>                 Connect via Chrome DevTools Protocol
  --user-data-dir <path>      Launch browser with user profile
  --executable-path <path>    Path to browser executable

BROWSER:
  --browser <engine>          chromium, firefox, or webkit (default: chromium)
  --headless                  Run in headless mode
  --timeout <ms>              Default action timeout (default: 30000)

VIEWPORT & DEVICE:
  --viewport <WxH>            Viewport size, e.g. 1920x1080
  --device <name>             Emulate device preset

NETWORK:
  --proxy-server <url>        Proxy URL
  --proxy-bypass <domains>    Domains to bypass proxy
  --ignore-https-errors       Ignore HTTPS certificate errors
  --block-service-workers     Block service workers

CONTEXT:
  --user-agent <string>       Custom user agent
  --locale <locale>           Browser locale (e.g. en-US)
  --timezone <tz>             Timezone (e.g. America/New_York)
  --color-scheme <scheme>     light, dark, or no-preference
  --geolocation <lat,lng>     Override geolocation
  --permissions <list>        Comma-separated permissions

SESSION:
  --storage-state <path>      Load session from JSON file

VIDEO:
  --record-video              Record browser session
  --video-dir <path>          Video output directory

Environment Variables

| Variable | CLI Equivalent | |---|---| | BROWSER_CDP_URL | --cdp | | BROWSER_USER_DATA_DIR | --user-data-dir | | BROWSER_EXECUTABLE_PATH | --executable-path | | BROWSER_ENGINE | --browser | | BROWSER_PROXY | --proxy-server |

---

🐳 Docker

docker build -t browser-mcp-server .
docker run -i browser-mcp-server
docker run -i browser-mcp-server --headless --browser chromium

---

🏗️ Architecture

src/
├── index.ts           # CLI entry point, MCP server setup
├── browser-manager.ts # Browser lifecycle, multi-engine, stealth, tracking
├── tools.ts           # All 70 MCP tools with human-like behavior
├── resources.ts       # 6 MCP resources (page, cookies, console, network, etc.)
├── human.ts           # Human behavior engine (Bezier curves, natural typing)
├── devices.ts         # 50+ device emulation presets
├── utils.ts           # Shared utilities (selectors, accessibility, text extraction)
└── mark_page.js       # Page annotation script (numbered interactive elements)

---

🔒 Anti-Detection Features

• navigator.webdriver set to false
• Chrome runtime spoofed
• Permissions query overridden
• Plugins and languages spoofed
• WebGL vendor/renderer overridden (Intel Iris)
• Canvas fingerprint noise injection
• connection.rtt consistency
• Automation command-line flags disabled
• Human-like timing on all interactions

---

📊 Competitive Advantage

| Feature | This Server | Playwright MCP (Microsoft) | mcp-playwright | Browserbase MCP | |---|---|---|---|---| | Human-like behavior | ✅ Bezier curves | ❌ | ❌ | ❌ | | Stealth anti-detection | ✅ Full suite | ❌ | ❌ | ❌ | | Session reuse (CDP) | ✅ | ✅ | ❌ | ❌ (cloud) | | Multi-browser | ✅ 3 engines | ✅ | ✅ | ❌ | | Device emulation | ✅ 50+ presets | ❌ | ✅ 143 | ❌ | | Token optimization | ✅ Compact outputs | ❌ | ❌ | ❌ | | Network monitoring | ✅ Auto-capture | ❌ | ❌ | ❌ | | mark_page annotation | ✅ | ❌ | ❌ | ❌ | | Smart natural actions | ✅ | ❌ | ❌ | ❌ | | Console log capture | ✅ Auto | ✅ | ❌ | ❌ | | Video recording | ✅ | ❌ | ✅ | ✅ | | iframe support | ✅ | ✅ | ❌ | ❌ | | Total tools | 70 | ~20 | ~30 | ~15 |

---

📄 License

MIT