# wsl-chrome-mcp-bridge

MCP bridge that launches Chrome on Windows from WSL2 and proxies [chrome-devtools-mcp](https://www.npmjs.com/package/chrome-devtools-mcp).

## How it works

```
Claude Code (WSL2)
    ↕ stdio (JSON-RPC)
wsl-chrome-mcp-bridge (WSL2)
    ├── spawns Chrome on Windows (--remote-debugging-port)
    ├── spawns chrome-devtools-mcp via npx
    └── proxies MCP messages + adds chrome_open / chrome_close tools
```

The bridge adds two lifecycle tools (`chrome_open` / `chrome_close`) and proxies all other tool calls to `chrome-devtools-mcp`. Chrome is launched on-demand when `chrome_open` is called and tool definitions are prefetched at startup for instant availability.

## Requirements

- WSL2 with **mirrored networking mode** enabled (see below)
- Node.js >= 20
- Google Chrome installed on Windows
- `npx` available in PATH

### WSL2 mirrored networking

The bridge connects to Chrome's debug port at `127.0.0.1`. WSL2's default NAT mode isolates the network from Windows, so mirrored mode is required.

Add to `%USERPROFILE%\.wslconfig`:

```ini
[wsl2]
networkingMode=mirrored
```

Then restart WSL: `wsl --shutdown`

## Installation

```bash
# Run directly (no install needed)
npx -y wsl-chrome-mcp-bridge

# Or install globally
npm install -g wsl-chrome-mcp-bridge
```

## Claude Code configuration

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "wsl-chrome-mcp-bridge"]
    }
  }
}
```

## Options

| Option | Environment Variable | Default | Description |
|--------|---------------------|---------|-------------|
| `--port`, `-p` | `CHROME_DEBUG_PORT` | `9222` | Chrome remote debugging port |
| `--user-data-dir` | `CHROME_USER_DATA_DIR` | `C:\tmp\chrome-devtools-mcp` | Chrome user data directory (Windows path) |
| `--chrome-path` | `CHROME_PATH` | auto-detect | Path to Chrome executable |
| `--headless` | `CHROME_HEADLESS=1` | off | Run Chrome in headless mode |
| `--help`, `-h` | | | Show help |
| `--version`, `-v` | | | Show version |

### Chrome path auto-detection

1. Query Windows registry via PowerShell (`App Paths\chrome.exe`)
2. Check known paths (`/mnt/c/Program Files/Google/Chrome/Application/chrome.exe`, etc.)

## License

MIT