MCP Chrome Bridge

MCP server that lets any AI agent control Chrome — tabs, navigation, clicks, forms, screenshots, console/network logs, GIF recording, and more. Works with any MCP-compatible client (Claude Code, OpenCode, custom agents).

Architecture

Agent → MCP server (stdio) → WebSocket relay (localhost:9876) → Chrome Extension → chrome.debugger API

• The extension creates a dedicated "Agent" tab group (purple) in your existing Chrome

• Same Chrome session = same cookies/auth (no separate browser needed)

• Native messaging keeps the extension alive

Related MCP server: Chrome MCP Server

Setup

1. Install dependencies

cd mcp-chrome-bridge
npm install

2. Start the relay

node relay.js

Or set it up as a systemd user service for persistence.

3. Load the Chrome extension

1. Open Chrome → chrome://extensions/

2. Enable "Developer mode" (toggle top-right)

3. Click "Load unpacked" → select the extension/ folder

4. Install native messaging host

./install.sh <your-extension-id>

The extension ID is shown in chrome://extensions/ after loading.

5. Configure your MCP client

Add to your MCP config:

{
  "mcpServers": {
    "chrome-bridge": {
      "command": "node",
      "args": ["/path/to/mcp-chrome-bridge/server.js"]
    }
  }
}

Tools

Browser (via Chrome extension relay)

Desktop (local, no relay needed)

System dependencies

• Node.js 18+

• xdotool — for desktop mouse/keyboard tools

• grim — for Wayland screen capture (optional, X11 fallback via extension)

Environment variables

Troubleshooting

See TROUBLESHOOTING.md for common issues (relay timeouts, extension disconnects, shadow DOM, file uploads).