ChromeBridge

ChromeBridge is a local-first MCP bridge for controlling an existing, already logged-in Chrome session without exporting browser cookies, OAuth tokens, or Chrome profile data.

It is designed for the gap between a full computer-use agent and a simple HTTP fetcher: read the page that is already open, interact with DOM elements, upload an explicitly allowlisted local file, or download a file while keeping the browser session on the user's machine.

Status: early OSS MVP (0.1.0). The local bridge, MCP/REST surfaces, MV3 extension, CDP controls, security boundaries, and automated tests are implemented. Real-site compatibility still needs broader manual testing before a stable release.

Architecture

ChatGPT / MCP client
        |
        | private/dev: OpenAI Secure MCP Tunnel
        | public: stable HTTPS endpoint (for example Cloudflare Named Tunnel)
        v
127.0.0.1:8765  ChromeBridge
        |
        | local authenticated WebSocket /extension
        v
Chrome MV3 extension
        |
        | chrome.debugger / Chrome DevTools Protocol
        v
Existing Chrome tabs and login session

The extension WebSocket is intentionally not part of the public tunnel ingress.

Human Space / AI Tab Group

ChromeBridge 0.1.0 defaults to Dedicated AI Tab Group mode. It keeps AI work inside a native Chrome tab group named ChromeBridge AI in the same signed-in Chrome profile/session.

Tabs outside the ChromeBridge AI group are Human Space: readable, but write actions are rejected in Dedicated mode.
Tabs inside the group are writable: navigation, typing, clicking, uploads, downloads, and tab operations are allowed there.
browser_open_tab creates a background AI-group tab by default, so the human active tab and OS focus are not stolen.
browser_switch_tab selects ChromeBridge's preferred AI working tab without visually activating it in Dedicated mode.
AI interactions render a page-local virtual AI cursor and AI TAB GROUP badge. The Windows mouse cursor is never moved by ChromeBridge.
Clicking the extension action opens a Chrome Side Panel showing bridge state, the AI group, AI tabs, and controls to create/expand/collapse the group.

Users who explicitly want the original unrestricted behavior can switch to Shared mode in extension options.

What it can do

Read operations include tab listing, active-tab state, page text/DOM summaries, accessibility data, element search, screenshots, page-state inspection, and recent downloads.

Action operations include click, double-click, hover, text entry, key presses, scrolling, navigation, history/reload, and tab open/close/switch.

File operations include uploading files from allowlisted local roots with DOM.setFileInputFiles, triggering downloads, and listing recent downloads.

What it intentionally does not expose

ChromeBridge does not provide tools for cookies, OAuth tokens, localStorage dumps, Chrome profile export, arbitrary local filesystem reads, arbitrary CDP command execution, or arbitrary JavaScript execution supplied by the remote MCP client.

Security model

The bridge refuses to bind to 0.0.0.0 and only listens on loopback. The MCP endpoint uses Bearer authentication. The compatibility REST endpoint uses HMAC-SHA256 over method, path, timestamp, nonce, and the exact raw request-body hash, with a replay window and nonce cache. Extension pairing uses a separate random token.

Local uploads are deny-by-default outside configured roots. Paths are canonicalized with realpath, UNC/device paths are rejected, browser profile/credential-store files are blocked even if they appear under an allowlisted directory, file size and extension limits are enforced, and only regular files are accepted.

Navigation only permits http: and https: URLs. Optional hostname allowlisting can restrict browser actions further.

See SECURITY.md and docs/THREAT_MODEL.md.

Requirements

Windows 11 is the primary tested platform for the MVP.
Node.js >=20.12.
Google Chrome with Manifest V3 extension support.
OpenAI tunnel-client is recommended for private ChatGPT/development connections.
cloudflared is optional for a stable public MCP endpoint.

Quick start on Windows

Run PowerShell from the repository root:
```
.\scripts\setup.ps1
```
This installs pinned npm dependencies and creates .env with independent random MCP, REST-HMAC, and extension-pairing secrets.
Open chrome://extensions, enable Developer mode, choose Load unpacked, and select the extension directory.
Open the ChromeBridge extension options page and paste the extension pairing token printed by setup.ps1. The default bridge URL is ws://127.0.0.1:8765/extension. If 8765 is occupied, change CHROMEBRIDGE_PORT and the extension URL to the same loopback port.
Start the local bridge:
```
.\scripts\start-local.ps1
```
After Secure MCP Tunnel registration, users who do not want a visible PowerShell console can install a hidden Windows Startup launcher once:
```
.\scripts\install-background-startup.ps1 -TunnelId tunnel_...
```
On future Windows sign-ins, ChromeBridge and the Secure MCP Tunnel start as hidden background processes. The Chrome extension remains the user-facing control surface.

Verify locally:

Invoke-RestMethod http://127.0.0.1:8765/health

For OpenAI Secure MCP Tunnel (recommended for private ChatGPT use), public hosting, and ChatGPT registration, see docs/SETUP_WINDOWS.md.

MCP endpoint

The stateless Streamable HTTP endpoint is:

POST /mcp
Authorization: Bearer <CHROMEBRIDGE_MCP_TOKEN>

The MCP server exposes focused browser tools rather than a generic cdp_command escape hatch. Read-only tools are annotated as read-only; browser actions are annotated as writes/open-world operations where appropriate.

Compatibility REST endpoint

POST /api/v1/tool is retained for clients that need the original JSON contract. Required headers:

X-ChromeBridge-Timestamp
X-ChromeBridge-Nonce
X-ChromeBridge-Signature

Canonical HMAC input:

METHOD\n
PATH\n
TIMESTAMP\n
NONCE\n
SHA256(EXACT_RAW_BODY)

The signature is HMAC-SHA256(CHROMEBRIDGE_HMAC_SECRET, canonical_message) encoded as lowercase hex (an optional sha256= prefix is accepted).

Configuration

Copy .env.example if configuring manually. Important variables:

CHROMEBRIDGE_MCP_TOKEN
CHROMEBRIDGE_HMAC_SECRET
CHROMEBRIDGE_EXTENSION_TOKEN
CHROMEBRIDGE_FILE_ROOTS — semicolon-separated local roots
CHROMEBRIDGE_FILE_EXTENSIONS
CHROMEBRIDGE_MAX_FILE_BYTES
CHROMEBRIDGE_DOMAIN_ALLOWLIST — optional semicolon-separated hostname allowlist

Never commit .env or Cloudflare tunnel credentials.

Tests

npm test
npm run check
npm audit --omit=dev

The current suite covers HMAC/raw-body verification, replay rejection, Bearer auth, Host-header protection, domain policy, local-file policy, request dedupe, authenticated WebSocket pairing, and bridge-to-extension RPC behavior.

OpenAI Plugin packaging

.codex-plugin/plugin.json is included. An .app.json file is deliberately not committed with a fake identifier: after registering the MCP server in ChatGPT/OpenAI, use the real generated plugin_asdk_app... technical ID for the app mapping.

License

MIT. See LICENSE.