BrowserConnect

Give Claude eyes, ears, and hands in your browser.

BrowserConnect is a Chrome extension + MCP server that connects Claude Code directly to your live browser. See pages, read console errors, intercept network requests, click elements, fill forms, and take screenshots — all from Claude, without leaving your terminal.

Installation

1. Configure Claude Code

Option A — Per project (recommended):

cd your-project
npx browserconnect --init

Creates .mcp.json and appends BrowserConnect instructions to CLAUDE.md in one step. Run once per project.

Option B — Global (available in every project, no .mcp.json needed):

claude mcp add browser-connect browserconnect && npx browserconnect --init

Registers the server globally via Claude Code, then writes CLAUDE.md to the current project. The --init command detects the global registration and skips .mcp.json automatically.

2. Restart Claude Code

Restart Claude Code so the MCP server starts. You'll see browser-connect in your tool list.

3. Install the Chrome extension

1. Open chrome://extensions
2. Enable Developer mode (top right toggle)
3. Click Load unpacked
4. Select the chrome-extension folder inside the npm package:
   • Mac (Homebrew): /opt/homebrew/lib/node_modules/browserconnect/chrome-extension
   • Mac (nvm): ~/.nvm/versions/node/$(node -v)/lib/node_modules/browserconnect/chrome-extension
   • Windows: %APPDATA%\npm\node_modules\browserconnect\chrome-extension

4. Open the side panel

Click the BrowserConnect icon in Chrome's toolbar. A side panel opens alongside the page — you're ready.

Team Setup (zero-config)

Team members with Node installed need only one command per project:

npx browserconnect --init

This automatically:

• Creates .mcp.json with the correct MCP server config
• Appends BrowserConnect instructions to CLAUDE.md
• Detects an existing global claude mcp add registration and skips .mcp.json if not needed

⚠️ Restart Claude Code after running --init to activate the MCP tools.

Then install the Chrome extension (step 3 above) and you're done.

Features

📸 Visual Capture

| Tool | Description | |------|-------------| | Annotate | Full-tab screenshot — draw arrows, boxes, and text on top before sending | | Region | Drag a crosshair to capture exactly the area you care about | | Full page | Auto-scrolls and stitches the entire page into one image | | Filmstrip | Hold R on the page to record a frame sequence; frames include timestamps, scroll position, and diff indicators | | Screenshot diff | Capture a "before" state, make changes, compare — pixel-level diff highlights what changed | | Clipboard paste | Paste any image directly into the panel with Ctrl/Cmd+V |

🔍 Page Inspection

| Tool | Description | |------|-------------| | Element picker | Hover over any element to see its tag, selector, computed styles, and HTML | | Annotations | Mark multiple elements with text notes and send them all at once | | Selected text | Grab highlighted text from the page into the panel input | | DOM reader | Claude can read the full HTML of any element or the entire page | | Storage inspector | Read localStorage, sessionStorage, and cookies | | Performance metrics | TTFB, FCP, LCP, CLS, FID, DNS, TCP, and the 10 slowest resources | | Accessibility audit | One-click WCAG check — missing alt text, contrast ratios, ARIA labels, keyboard traps, landmark regions | | SEO inspector | Title length, meta description, OG tags, Twitter Card, JSON-LD structured data |

🐛 Debugging

| Tool | Description | |------|-------------| | Console capture | Live JS console output — logs, warnings, errors, and stack traces with timestamps | | Network log | All fetch / XHR requests — URL, method, status, duration, errors; grouped by route | | Noise filter | Toggle to hide static assets (JS/CSS/fonts/images) and RSC prefetch requests | | Auto-error | Toggle to automatically forward uncaught JS errors to Claude as they happen |

Claude calls get_console_log automatically when you describe a JS error, and get_network_requests when you describe an API failure — no need to ask.

🤖 Browser Automation

Claude can control the browser directly via MCP tools:

| Tool | What it does | |------|-------------| | take_screenshot | Capture the visible tab as a JPEG | | click_element | Click any DOM element by CSS selector | | fill_input | Set input / textarea values, fires React/Vue/Angular-compatible events | | hover_element | Trigger hover states to reveal tooltips and dropdowns | | scroll_page | Scroll up, down, to top/bottom, or by exact pixel amount | | navigate_to | Navigate the tab to a URL and wait for page load | | wait_for_element | Poll until a CSS selector appears (configurable timeout) | | type_text | Type into focused elements via real keyboard events | | press_key | Press Enter, Tab, Escape, Arrow keys, Backspace, etc. | | find_element | Find an element by natural language description | | get_dom | Read the full page HTML or a specific element | | execute_js | Run arbitrary JavaScript in the page's MAIN world | | get_console_log | Fetch live console output | | get_network_requests | Fetch intercepted network request log | | get_storage | Read localStorage, sessionStorage, and cookies | | get_performance | Core Web Vitals + full navigation timing | | get_selected_text | Return whatever text the user has highlighted on the page | | get_pending_message | Read the next message sent from the panel | | send_response | Send a reply back to the panel | | clear_messages | Clear the message queue |

🖱️ Context Menu

Right-click any selected text on a page and choose Ask Claude — the side panel opens with the selection pre-loaded in the input.

🔄 Auto-Tab Follow

The panel automatically tracks whichever tab you're actively viewing. Switch tabs and the panel's context switches with you — no manual reconnect needed.

💬 Panel UI

The side panel lives alongside Chrome and gives you a full chat interface:

| Button | Action | |--------|--------| | 📷 Annotate | Draw on the page and capture | | ⬜ Region | Drag-select a cropped area | | 📄 Full page | Scroll-stitch the entire page | | ⏺ Record | Filmstrip recording (hold R on page) | | ↔ Diff | Capture before/after and compute pixel diff | | 🖱️ Element picker | Click to inspect any element | | ✏️ Annotate elements | Mark multiple elements with text notes | | ♿ A11y | Run accessibility audit | | 🔍 SEO | Run SEO inspector | | ↗ Selected text | Grab highlighted text into the input | | 📡 Network | Attach network log to message | | ▶ Console | Attach console output to message | | ⚡ Auto-error | Toggle auto JS error forwarding | | ⬇ Export | Download conversation as HTML with embedded images | | 🗑️ Clear | Clear conversation thread |

Paste any image from clipboard with Ctrl/Cmd+V directly into the panel.

Token Efficiency

BrowserConnect is designed to be more token-efficient than tools like Playwright MCP or browser-use:

| | BrowserConnect | Playwright MCP / browser-use | |---|---|---| | After each action | Nothing (unless you ask) | Full screenshot | | Console / network data | Text (cheap) | Screenshot of DevTools | | Agent loop | Human-driven | Autonomous — screenshot every step | | 10-step automation | 0–1 images | ~10 full-page images |

Why it's cheaper:

• Text-first tools — get_console_log, get_network_requests, get_dom, get_storage, get_performance return text. Text is 10–50× cheaper than a screenshot for the same information.
• On-demand only — Claude fetches data when you describe a problem, not on every step.
• Human-in-the-loop — you control when messages are sent. No autonomous loop burning tokens in the background.
• Selective screenshots — take_screenshot is called when Claude genuinely needs to see the UI, not as a default return after every action.

How It Works

You (Chrome panel)  ──POST /message──▶  Express server  ──▶  Claude (via MCP)
                    ◀─long-poll──────────────────────────  send_response()

Claude  ──take_screenshot──▶  MCP server  ──▶  panel polls /action-pending
                                               panel executes in active tab
        ◀──────────────────────────────────────  POST /action (result)

• Long-poll architecture — responses arrive the instant Claude sends them
• Pull pattern — Claude requests console/network data on demand; the panel fetches fresh data from the tab
• Push pattern — Claude dispatches actions; the panel executes them in the active tab and returns results
• Auto-demand — Claude calls the right tool automatically based on what you describe

Privacy

• Everything runs locally — no cloud, no telemetry
• The MCP server binds to localhost:2222 only
• Data goes only to Claude via your own MCP connection

Security model

BrowserConnect's HTTP bridge listens on loopback only (127.0.0.1:2222), so it is unreachable from the network. Its actual security boundary and residual limitations are:

What is protected

Every endpoint (except /health) requires a session token fetched from /handshake. The token is a fresh 192-bit random value generated at each server start. All extension-to-server calls include it as X-BC-Token. Custom-header requirement forces a CORS preflight for any cross-origin caller, which the server rejects unless the Origin is a chrome-extension:// URL — blocking malicious web pages from injecting messages or forging tool results even via multipart/form-data (which would otherwise bypass preflight).

Trusted boundary: same OS user, not network

The server is on loopback. Any process running as your OS user — a shell script, a curl command, a local app — can call http://localhost:2222/handshake without CORS restriction and receive the token. After that it can drive the bridge. This is an intentional trade-off: local software running as you is already trusted in the same way it can read your files or spawn processes. BrowserConnect does not defend against compromised local software; it defends against malicious web content in your browser tabs.

Residual: extension-origin allowlist is not pinned to this extension's ID

The server echoes CORS headers for any chrome-extension:// origin, not specifically BrowserConnect's ID. A different installed extension with a chrome-extension:// origin could call /handshake and obtain the token. The fix — pinning to chrome-extension://<exact-id> — will be applied once the extension has a stable Chrome Web Store ID. Until then, keep your installed extensions to ones you trust.

Requirements

• Node.js 18+
• Chrome (or any Chromium-based browser)
• Claude Code CLI with an active Claude subscription

Tech Stack

| Layer | Technology | |-------|-----------| | Chrome Extension | Manifest V3, Side Panel API, chrome.scripting | | Content Scripts | world: "MAIN" + ISOLATED, run_at: "document_start" | | MCP Server | Node.js, @modelcontextprotocol/sdk, stdio transport | | HTTP Bridge | Express, long-polling, multer for image uploads | | AI Client | Claude Code CLI |

License

MIT