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

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.

Related MCP server: monkeysee

Install

Chrome 116 or newer is required.

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

{
  "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:

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

CLI

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

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.