# cc-chrome-agent

**MCP server to control Chrome browsers on your network via Claude's Chrome extension.**

Control any Chrome browser — locally or on remote machines — directly from Claude Code, Claude Desktop, or any MCP client. Navigate pages, fill forms, click buttons, take screenshots, run JavaScript, and more.

## How it works

```
Claude Code / Claude Desktop / Any MCP Client
        |
        | MCP (stdio)
        v
cc-chrome-agent (this server)
        |
        | Socket protocol (4-byte length-prefix + JSON)
        v
Chrome + Claude Extension (local or remote)
```

The Claude Chrome extension exposes browser automation tools via a local Unix socket. This MCP server connects to that socket and makes those tools available to any MCP client.

For remote Chrome instances, a TCP bridge server proxies the socket over the network, with optional mDNS discovery.

## Quick Start

### 1. Install

```bash
# From GitHub:
pip install git+https://github.com/delltrak/cc_chrome_agent.git

# With network discovery (mDNS):
pip install "cc-chrome-agent[network] @ git+https://github.com/delltrak/cc_chrome_agent.git"
```

Or from source:

```bash
git clone https://github.com/delltrak/cc_chrome_agent
cd cc_chrome_agent
pip install -e .
```

### 2. Prerequisites

- **Chrome** (or Chromium-based browser) with the [Claude extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) installed
- Open the Claude extension sidebar at least once to activate the native host
- **Claude Code** (or any MCP client)

### 3. Register with Claude Code

```bash
claude mcp add cc-chrome-agent -- cc-chrome-agent
```

### 4. Use it

Just ask Claude to interact with your browser:

```
> Open github.com and tell me the trending repos today
> Fill the login form with test@example.com and click submit
> Take a screenshot of the current page
> Run document.title in the browser console
```

Claude Code will use the MCP tools automatically.

If the browser is closed, `cc-chrome-agent` now tries to launch a local Chromium browser automatically and waits for the Claude bridge socket to appear. If the browser is already open, it reuses the existing local bridge.

## Tools

### Browser Control

| Tool | Description |
|------|-------------|
| `navigate` | Go to a URL, or navigate back/forward |
| `find` | Find elements by natural language ("login button", "search bar") |
| `form_input` | Fill form fields using element ref_ids |
| `computer` | Mouse clicks, keyboard input, screenshots, scrolling |
| `javascript` | Execute JavaScript in the page context |
| `screenshot` | Capture a screenshot of the current tab |

### Page Reading

| Tool | Description |
|------|-------------|
| `read_page` | Get the accessibility tree with element ref_ids |
| `get_page_text` | Get the full text content of the page |
| `preview_snapshot` | Lightweight accessibility tree snapshot |
| `read_console` | Read browser console messages |
| `read_network` | Inspect network requests |

### Tab Management

| Tool | Description |
|------|-------------|
| `list_tabs` | List all open tabs |
| `create_tab` | Open a new tab |
| `resize_window` | Resize the browser window |

### Network (Meta)

| Tool | Description |
|------|-------------|
| `discover_bridges` | Find Chrome instances on the local network |
| `connect_bridge` | Connect to a local or remote Chrome |
| `connection_status` | Check current connection status |

## Local Browser Bootstrap

When a tool needs local Chrome and no bridge socket exists yet, the server will:

1. Reuse an existing local socket if one is already available.
2. Try to launch a local Chromium browser automatically.
3. Wait for the Claude extension socket to appear.
4. Reconnect automatically if the local socket drops mid-session.

Important caveat: the Claude extension still needs to be installed and activated on that machine. On a fresh install, open the extension sidebar once so the native host socket can be created.

## Network Mode

Control Chrome on remote machines (e.g., a test server, a colleague's desktop).

### On the remote machine

```bash
# Install and start the bridge server:
pip install cc-chrome-agent
cc-chrome-agent serve

# With specific port:
cc-chrome-agent serve --port 9000
```

The bridge server:
- Finds the local Chrome socket automatically
- Exposes it via TCP
- Advertises via mDNS (if zeroconf is installed)

### From your machine

```
> Discover Chrome bridges on the network
> Connect to the bridge at 192.168.1.20
> Navigate to example.com and take a screenshot
```

Or discover from the command line:

```bash
cc-chrome-agent discover
cc-chrome-agent discover --scan    # TCP subnet scan (no mDNS needed)
cc-chrome-agent discover --json    # JSON output
```

## Configuration

### Claude Code

```bash
# Register the MCP server:
claude mcp add cc-chrome-agent -- cc-chrome-agent

# With verbose logging:
claude mcp add cc-chrome-agent -- cc-chrome-agent --verbose

# Remove:
claude mcp remove cc-chrome-agent
```

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "cc-chrome-agent": {
      "command": "cc-chrome-agent"
    }
  }
}
```

### Manual MCP config

```json
{
  "mcpServers": {
    "cc-chrome-agent": {
      "command": "python3",
      "args": ["-m", "cc_chrome_agent"]
    }
  }
}
```

### Skip permission prompts

When Claude Code uses Chrome tools for the first time, the extension asks whether to "Act without asking" or "Ask before acting". To skip this prompt and always allow actions automatically, set this environment variable:

```bash
# Add to your ~/.zshrc or ~/.bashrc:
export CLAUDE_CHROME_PERMISSION_MODE="skip_all_permission_checks"
```

Available modes:

| Mode | Behavior |
|------|----------|
| `ask` | Prompt before each action (default) |
| `skip_all_permission_checks` | Act without asking |
| `follow_a_plan` | Follow a pre-approved plan |

### Environment variables

Use these when the browser is not in a default location or when you want tighter startup control:

```bash
CC_CHROME_AGENT_BROWSER_COMMAND="/custom/browser/bin/chrome --profile-directory=Default"
CC_CHROME_AGENT_BROWSER_APP="Google Chrome"
CC_CHROME_AGENT_START_URL="about:blank"
CC_CHROME_AGENT_BOOT_TIMEOUT="20"
CC_CHROME_AGENT_AUTO_LAUNCH="1"
```

- `CC_CHROME_AGENT_BROWSER_COMMAND`: full custom launch command, used first
- `CC_CHROME_AGENT_BROWSER_APP`: preferred browser app or executable name
- `CC_CHROME_AGENT_START_URL`: URL opened during auto-launch
- `CC_CHROME_AGENT_BOOT_TIMEOUT`: seconds to wait for the bridge socket
- `CC_CHROME_AGENT_AUTO_LAUNCH`: set to `0` to disable browser auto-launch

## CLI Reference

```
cc-chrome-agent                  Start MCP server (stdio)
cc-chrome-agent serve            Start TCP bridge for remote access
cc-chrome-agent discover         Find Chrome bridges on the network
cc-chrome-agent --version        Show version
cc-chrome-agent --verbose        Enable debug logging
```

### `serve` options

```
--port PORT       TCP port (default: 8765)
--sock PATH       Unix socket path (auto-detected)
--no-mdns         Disable mDNS advertisement
--launch-timeout  Seconds to wait for a bridge after auto-launch
--no-launch       Disable local browser auto-launch
```

### `discover` options

```
--timeout SECS    Discovery timeout (default: 3.0)
--scan            Force TCP subnet scan
--json            JSON output
```

## Supported Browsers

Any Chromium-based browser that supports the Claude extension:

- Google Chrome
- Chrome Canary
- Brave
- Microsoft Edge
- Arc
- Vivaldi
- Chromium

## Architecture

```
┌─────────────────────────────────────────────────┐
│                  MCP Client                     │
│         (Claude Code / Desktop / SDK)           │
└──────────────────┬──────────────────────────────┘
                   │ MCP (stdio, JSON-RPC 2.0)
                   │
┌──────────────────▼──────────────────────────────┐
│             cc-chrome-agent                     │
│                                                 │
│  ┌─────────────┐  ┌────────────┐  ┌──────────┐ │
│  │ MCP Server  │  │   Bridge   │  │ Discovery│ │
│  │ (tools)     │──│ (protocol) │  │ (mDNS/   │ │
│  │             │  │            │  │  scan)    │ │
│  └─────────────┘  └─────┬──────┘  └──────────┘ │
└──────────────────────────┼──────────────────────┘
                           │
              ┌────────────┼────────────┐
              │ Local      │ Remote     │
              │            │            │
     ┌────────▼───┐  ┌─────▼──────┐    │
     │ Unix Socket│  │  TCP:8765  │    │
     │ /tmp/...   │  │  (bridge)  │    │
     └────────┬───┘  └─────┬──────┘    │
              │            │            │
     ┌────────▼────────────▼───────┐   │
     │    Chrome + Claude Extension│   │
     │    (native host socket)     │   │
     └─────────────────────────────┘   │
```

## Requirements

- Python 3.10+
- Chrome (or Chromium-based browser) with [Claude extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn)
- Optional: `zeroconf` for mDNS network discovery

## License

MIT