<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

```bash
cd mcp-chrome-bridge
npm install
```

### 2. Start the relay

```bash
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

```bash
./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:

```json
{
  "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](TROUBLESHOOTING.md) for common issues (relay timeouts, extension disconnects, shadow DOM, file uploads).