# Chrome MCP

Chrome MCP exposes real Chrome tabs to Model Context Protocol clients without copying browser sessions into another engine. The Chrome extension controls tabs in the user's existing profile through `chrome.debugger`, while a persistent local daemon coordinates one or more Chrome profiles and MCP processes.

## Architecture

```text
MCP client ──stdio── MCP bridge ──authenticated HTTP── persistent daemon
                                                        │
                                                        ├── WebSocket ── Chrome extension/profile A ── tabs
                                                        └── WebSocket ── Chrome extension/profile B ── tabs
```

- Tabs are browser sessions. Closing a session closes its Chrome tab.
- Each extension installation represents one Chrome profile/instance.
- The daemon assigns global numeric `session_id` values across every connected instance.
- The daemon persists independently of MCP client restarts and has no tray icon.
- Actions use Chrome DevTools Protocol through `chrome.debugger`, so evaluated JavaScript is not blocked by page CSP.
- Authentication state, cookies, IndexedDB, service workers, certificates, extensions, and browser fingerprint remain in the original Chrome profile because no session migration is required.

## Install

Chrome 116 or newer is required.

```bash
bun install
```

Load the extension in every Chrome profile that should be available:

1. Open `chrome://extensions`.
2. Enable **Developer mode**.
3. Choose **Load unpacked**.
4. Select this repository's `extension` directory.
5. Open the extension popup, give the instance a recognizable name, and select **Use as default** when appropriate.

Chrome must be able to reach `ws://127.0.0.1:55333`. The daemon accepts extension WebSockets only from `chrome-extension://` origins and binds only to localhost.

## MCP client configuration

```json
{
  "mcpServers": {
    "chrome": {
      "command": "bunx",
      "args": ["-y", "@cypherpotato/chrome-mcp", "--mcp"]
    }
  }
}
```

For a local checkout after `bun link`, point the MCP configuration directly at the linked executable rather than using `bunx`:

```json
{
  "command": "C:\\Users\\<user>\\.bun\\bin\\chrome-mcp-electron",
  "args": ["--mcp"]
}
```

## CLI

```text
chrome-mcp-electron --mcp
chrome-mcp-electron --daemon
chrome-mcp-electron --status
chrome-mcp-electron --stop-daemon
chrome-mcp-electron --help
```

`--mcp` starts the daemon in the background when necessary and then serves MCP over stdio. Closing the MCP process does not stop the daemon or disconnect Chrome extensions.

## Tools

The public tool names and input schemas match Browser MCP:

- `browser_toggle_session`
- `browser_import_session`
- `browser_run_actions`
- `browser_get_context`

`browser_toggle_session({ "action": "start" })` opens a tab in the default Chrome instance. When multiple instances are connected, choose the default in the extension popup. Existing tabs reported by the extensions also receive `session_id` values and can be controlled directly.

`browser_get_context` lists all connected instances and their tabs. URLs are returned without query strings.

## Multiple Chrome instances and profiles

Install the unpacked extension separately in every profile. Each installation creates a stable random instance ID stored in that profile and reconnects to the daemon automatically. Instance names do not need to be unique, but distinct names are recommended.

The daemon reconciles tabs after extension or service-worker restarts. A session remains addressable while its owning extension is connected and the tab still exists.

## Capabilities

`browser_run_actions` supports the same browser helper surface as Browser MCP:

- snapshots and JavaScript evaluation;
- click, right-click, hover, drag, scroll, and typing;
- navigation;
- screenshots;
- console and network logs;
- network request details and response bodies when Chrome still retains them;
- responsive viewport emulation and color-scheme emulation;
- JavaScript alert, confirm, and prompt handling.

## Limitations

- Chrome allows only one debugger attachment per tab. Close DevTools before controlling that tab. Opening DevTools can detach the extension.
- Chrome internal pages, extension pages, the Chrome Web Store, and other restricted schemes cannot be controlled or exposed as agent sessions.
- The extension must be installed in each profile; one profile cannot inspect another profile's tabs.
- The debugger permission displays a Chrome warning while a tab is attached.
- Response bodies can expire from Chrome's network buffer.
- Native touch input and browser-internal download CDP APIs are not exposed through `chrome.debugger`.

## Development

```bash
bun run check
bun run test
```

The test suite uses mock extension WebSocket clients to validate persistent daemon lifecycle, authentication, tab/session reconciliation, multiple instances, default-instance selection, action routing, and reconnect behavior without opening Chrome.

The internal protocol is documented in [`docs/protocol.md`](docs/protocol.md).