MCP Chrome Bridge

<p align="center"> <img src="docs/banner.svg" alt="MCP Chrome Bridge" width="700"/> </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT License"/></a> <img src="https://img.shields.io/badge/MCP-server-blue?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJ3aGl0ZSI+PGNpcmNsZSBjeD0iMTIiIGN5PSIxMiIgcj0iMTAiLz48L3N2Zz4=" alt="MCP Server"/> <img src="https://img.shields.io/badge/Chrome-Extension_MV3-yellow?style=flat-square&logo=googlechrome&logoColor=white" alt="Chrome MV3"/> <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square&logo=node.js&logoColor=white" alt="Node 18+"/> </p>

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

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)

Tool	Description
tabs_context	List tabs in the agent window
tabs_create	Open a new tab
tabs_close	Close a tab
navigate	Navigate to a URL
read_page	Read visible text content
get_page_text	Get full page text
click	Click an element (CSS selector)
form_input	Fill a form field
javascript	Execute JS in a tab
find	Find elements by selector or text
file_upload	Upload a file to an input[type=file]
screenshot	Screenshot a tab
screenshot_area	Screenshot a specific region
console_logs	Read browser console messages
network_logs	Read network requests
gif_start	Start GIF recording
gif_capture	Capture a GIF frame
gif_stop	Stop recording, get frames

Desktop (local, no relay needed)

Tool	Description
computer_mouse_move	Move mouse cursor
computer_click	Click at coordinates
computer_type	Type text via keyboard
computer_key	Press key combo (e.g. ctrl+a)
computer_screenshot	Screenshot entire screen or region
web_fetch	Fetch a URL (server-side)
web_search	Search the web via DuckDuckGo

System dependencies

• Node.js 18+
• xdotool — for desktop mouse/keyboard tools
• grim — for Wayland screen capture (optional, X11 fallback via extension)

Environment variables

Variable	Default	Description
RELAY_URL	ws://127.0.0.1:9876	WebSocket relay address

Troubleshooting

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