Browser Bridge MCP

Browser Bridge MCP


MCP server that gives AI coding assistants direct control of a real Chrome browser — navigate, click, fill forms, run JavaScript, take screenshots, and read page content. It exists so your assistant can see what you see, instead of you alt-tabbing to copy-paste errors and describe UI state in words.

MCP Client ←(stdio)→ mcp-browser-bridge ←(WebSocket :7483)→ Browser Extension ←(Chrome APIs)→ Browser

Works with any MCP-compatible client: Claude Code, Cursor, Windsurf, Cline, and others.

Quick Start

1. Install the extension

Load it as an unpacked extension:

1. Download or clone this repo.
2. Open chrome://extensions and enable Developer mode.
3. Click Load unpacked and select the extension/ folder.

Works in any Chromium browser: Chrome, Brave, Edge, Arc, Vivaldi, Opera.

2. Add to your MCP client

<details> <summary><strong>Claude Code</strong></summary>

Run: ``sh claude mcp add browser-bridge -- npx -y mcp-browser-bridge ``

Or add to .mcp.json: ``json { "mcpServers": { "browser-bridge": { "command": "npx", "args": ["-y", "mcp-browser-bridge"] } } } `` </details>

<details> <summary><strong>Cursor</strong></summary>

Add to .cursor/mcp.json: ``json { "mcpServers": { "browser-bridge": { "command": "npx", "args": ["-y", "mcp-browser-bridge"] } } } `` </details>

<details> <summary><strong>Windsurf</strong></summary>

Add to ~/.codeium/windsurf/mcp_config.json: ``json { "mcpServers": { "browser-bridge": { "command": "npx", "args": ["-y", "mcp-browser-bridge"] } } } `` </details>

<details> <summary><strong>Cline</strong></summary>

In the Cline pane, open MCP Servers → Configure MCP Servers to edit cline_mcp_settings.json, and add: ``json { "mcpServers": { "browser-bridge": { "command": "npx", "args": ["-y", "mcp-browser-bridge"] } } } `` </details>

<details> <summary><strong>Other MCP clients</strong></summary>

Use npx -y mcp-browser-bridge as the server command in your client's MCP configuration. The server communicates over stdio. </details>

3. Verify

Start your MCP client. The extension popup should show a green Connected indicator. Call the browser_status tool to confirm.

Available Tools

All tools accept an optional tabId parameter. When omitted, they target the active tab.

| Tool | Description | |------|-------------| | browser_status | Check if the extension is connected and get active tab info | | browser_navigate | Navigate a tab to a URL | | browser_screenshot | Capture a screenshot of the visible area of a tab | | browser_evaluate | Execute JavaScript in a tab and return the result | | browser_click | Click an element by CSS selector | | browser_fill | Fill a form field by CSS selector (React-compatible) | | browser_get_content | Get the text or HTML of a page or element | | browser_get_tabs | List all open browser tabs | | browser_get_console | Get captured console log entries from a tab | | browser_wait_for | Wait for a CSS selector to appear on the page | | browser_send_message | Send a custom message to the extension |

Included Prompts

The server ships two MCP prompts that provide guided workflows to any connected client:

| Prompt | Description | |--------|-------------| | browse | General-purpose browser interaction — navigating, clicking, filling forms, screenshotting, running JS. Accepts an optional task argument. | | qa-runner | Structured QA checklist execution — drives the browser through test scenarios defined in markdown and reports pass/fail results. Accepts an optional checklist path. |

In Claude Code, these appear as slash commands: /browser-bridge:browse and /browser-bridge:qa-runner.

Configuration

The WebSocket port defaults to 7483. To change it:

• Server side: Set the BRIDGE_WS_PORT environment variable in your MCP config.
• Extension side: Change the port in the extension popup and click Reconnect.

Security

• WebSocket binds to 127.0.0.1 only — no network exposure.
• Connections restricted to browser extension origins.
• Single extension client at a time.

Troubleshooting

Extension shows "Disconnected" Check that the MCP server is running and the port is free: ```sh

macOS/Linux

lsof -i :7483

Windows

netstat -aon | findstr :7483 ```

Tools return "No extension connected" Open the extension popup and click Reconnect.

Screenshots fail The target tab must be visible and focused. Background or minimized tabs cannot be captured.

browser_evaluate returns unexpected results Results must be JSON-serializable. Promises return {} — use synchronous expressions or await inside an IIFE and return a plain value.

Development

git clone https://github.com/adbarc92/mcp-browser-bridge.git
cd mcp-browser-bridge
npm install
npm run build
npm test                 # 57 tests via Vitest

Load the extension locally via chrome://extensions → Load unpacked → select extension/.

The repo includes a .mcp.json configured for local development.

License

MIT