Chrome Agent Bridge

<p align="center"> <img src="./assets/chrome-agent-bridge-icon-512.png" width="160" alt="Chrome Agent Bridge icon"> </p>

Chrome Agent Bridge is a small, local bridge that lets MCP-compatible agents interact with user-approved Google Chrome tabs. It is a clean-room, MIT-licensed implementation built from public Chrome Native Messaging and Model Context Protocol APIs.

It does not contain or redistribute OpenAI's proprietary Chrome extension, browser client, or native host.

Architecture

Agent → MCP server → authenticated loopback RPC → Native Messaging host
      → Chrome extension → tabs / scripting / screenshots / sanitized network tools / Raw CDP

The MCP surface has two levels. The default tools list, navigate, watch, snapshot, screenshot, act on semantic element refs, and monitor sanitized request lifecycle metadata. The explicit Raw CDP tools attach to one tab and forward arbitrary CDP methods, params, results, target sessions, and events without field sanitization. A sanitized network projection can reuse the same Raw attachment when an Agent needs Raw commands without exposing Raw network events to its context.

High-level page control follows the open-source OpenClaw Browser plugin's snapshot → ref → act → snapshot contract while keeping this project's existing Native Messaging, token, MCP, and debugger attachment layers. OpenClaw is a design reference, not a runtime dependency; its Chrome extension is a thin CDP transport, so this project does not fork or embed that transport.

Raw CDP is equivalent to granting the local bearer token full developer control of an attached tab. Depending on the commands sent, it can execute JavaScript, read or modify page content, inspect cookies and storage, capture request or response bodies, intercept traffic, and control child targets. Do not expose the loopback service or token to another user or machine.

Requirements

• Node.js 18 or newer
• Google Chrome on macOS or Linux
• An MCP-compatible agent

Windows native-host installation is not implemented in the initial release.

Install

For an Agent-executable checklist, MCP configuration, verification steps, upgrades, and recovery guidance, see Install Chrome Agent Bridge for an Agent.

Install the released extension ZIP

1. Download chrome-agent-bridge-extension-vX.Y.Z.zip from GitHub Releases.
2. Extract the ZIP to a permanent local directory.
3. Open chrome://extensions, enable Developer mode, choose Load unpacked, and select the extracted directory.

The release manifest carries a public development key, so every unpacked release uses the stable extension ID hkedmoboloodflgcaidimhddljdnndcd. The ZIP is not directly installable: Chrome requires it to be extracted before Load unpacked.

Install the local Agent bridge

git clone https://github.com/escapeWu/chrome-agent-bridge.git
cd chrome-agent-bridge
npm ci
npm run install-host

Reload the extension on chrome://extensions. The extension and native host reconnect automatically. For a custom development build with a different ID, pass --extension-id ID explicitly.

Install the paired Agent Skill

Installing only the Extension ZIP and MCP server is incomplete for Agent use. Also install skills/chrome-agent-control so the Agent follows the required connection, tab-scoping, network-listening, Raw CDP, cleanup, and confirmation workflows.

The Codex plugin bundle installs the MCP registration and Skill together. When configuring mcp/server.mjs as a standalone MCP server, install the Skill separately. See the exact Agent checklist in docs/agent-installation.md.

Pairing token

Click the extension toolbar icon to open its local pairing window. The window shows a masked, long-lived authentication token with controls to reveal, copy, or renew it. Renew requires two clicks and invalidates the previous token immediately.

The token is generated by the native host and stored only in ~/.chrome-agent-bridge/auth.json with user-only permissions. It is not stored in Chrome Sync, the extension package, Git, or GitHub Releases. Local agents discover it automatically. A separately configured local agent can receive the copied value through CHROME_AGENT_BRIDGE_TOKEN.

Agent quick start

Agents can use this section as an installation and connection checklist:

1. Verify Node.js 18+ and Google Chrome are installed.
2. Run npm ci and npm run install-host in the repository root. The released extension ID is built in.
3. Ask the user to download and extract the Extension ZIP, then load its extracted directory from chrome://extensions with Developer mode enabled. This is the only required user-visible approval step.
4. Ask the user to reload Chrome Agent Bridge after source, manifest, or native-host installation changes.
5. Add mcp/server.mjs to the Agent's MCP configuration using an absolute filesystem path, or install this repository as a Codex plugin. Copy the ready-to-use configuration from docs/agent-installation.md.
6. Install and enable the paired chrome-agent-control Skill. Do not treat MCP configuration alone as a complete Agent installation.
7. Call browser_status, then browser_list_tabs. Do not begin browser actions until the bridge reports connected.

For page interaction, take browser_snapshot, act once with browser_act using a returned ref, then take a new snapshot and verify. Refs are deliberately short-lived and invalidated after an action or navigation. A high-level click performs its full CDP mouse sequence atomically inside the extension; do not split mouseMoved, mousePressed, and mouseReleased across Raw MCP calls. For tab monitoring, call browser_watch_events with the previous cursor and, when useful, a specific tabId. Start sanitized request monitoring before the intended UI action, page through browser_network_poll, and always finish with browser_network_stop. When Raw commands and a safe network summary are both required, attach Raw with captureEvents=false and pass its session ID to browser_network_start as rawSessionId; this shares one Chrome debugger attachment. Do not fall back to Resource Timing or page-level fetch/XHR hooks merely because the page's performance buffer is full.

Never submit forms, purchase, publish, delete, send messages, or change permissions without the user's explicit approval. The high-level fill tool rejects password fields, but Raw CDP bypasses those high-level guardrails and may expose cookies, storage, credentials, and private page content.

Connect an MCP agent

Use an absolute path when configuring a standalone MCP client:

{
  "mcpServers": {
    "chrome-agent-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/chrome-agent-bridge/mcp/server.mjs"]
    }
  }
}

The local Agent reads ~/.chrome-agent-bridge/auth.json automatically. Set CHROME_AGENT_BRIDGE_TOKEN only when configuring a separate local process with a token copied from the extension popup.

The repository is also a Codex plugin: .codex-plugin/plugin.json registers the MCP server and the chrome-agent-control skill.

Standalone MCP clients must install the paired Skill separately. The Extension ZIP contains only the Chrome extension, and an MCP configuration exposes tools without teaching the Agent the required workflow. Follow Install Chrome Agent Bridge for an Agent.

Tools

• browser_status
• browser_list_tabs
• browser_open_tab
• browser_activate_tab
• browser_close_tab
• browser_navigate
• browser_snapshot
• browser_screenshot
• browser_act
• browser_click
• browser_fill
• browser_watch_events
• browser_network_start
• browser_network_poll
• browser_network_stop
• browser_cdp_attach
• browser_cdp_send
• browser_cdp_events
• browser_cdp_detach

Prefer browser_snapshot → browser_act(ref) → browser_snapshot. browser_click and browser_fill remain selector-based compatibility tools.

Security model

• Native Messaging only accepts the extension ID placed in the installed host manifest.
• The installer generates a private launcher containing absolute Node.js and host paths, so Chrome does not depend on the terminal's PATH.
• The native host listens only on 127.0.0.1 and requires a long-lived random bearer token for every RPC request.
• The token is stored in ~/.chrome-agent-bridge/auth.json with user-only permissions. It has no automatic expiry and remains valid until the user selects Renew in the extension popup.
• Runtime connection data is stored separately in ~/.chrome-agent-bridge/runtime.json; it does not contain the token.
• Renewing the token atomically replaces the local credential and immediately rejects the previous token.
• Password inputs are rejected by browser_fill; Raw CDP commands are not restricted by that check.
• Browser-internal URLs cannot be inspected or scripted.
• The default high-level tools do not read cookies, saved passwords, local storage, or session storage. Raw CDP can access data exposed by Chrome's CDP implementation.
• Network monitoring uses Chrome's user-visible debugger permission and attaches only to the selected tab for the lifetime of a network session.
• Network events contain lifecycle metadata only. Userinfo, URL fragments, headers, request bodies, response bodies, security details, and raw CDP request IDs are not returned. Query strings are removed by default and preserved only with explicit urlMode="full" because they may contain tokens or signatures.
• Network sessions have bounded event and byte buffers, monotonically increasing cursors, tab isolation, and explicit stop/detach behavior.
• Raw CDP accepts any method and JSON params and returns original results and events, including sensitive fields. Raw event buffers are bounded to 3 MB and command results to 3 MB by the Native Messaging transport envelope.
• Set captureEvents=false when Raw is needed for commands but original events are not required. A sanitized network session can reuse that Raw attachment through rawSessionId; stopping the projection leaves Raw attached, while detaching Raw terminates its active projection.
• Agents should require user confirmation before submitting, purchasing, publishing, deleting, sending, or changing permissions.

The clean-room capability analysis and migration boundaries are documented in docs/clean-room-browser-capabilities.md.

This is an early developer release. Review the requested tab and action before allowing an agent to operate a signed-in site.

Development

npm test
npm run check
npm run build:extension

Validate the Codex plugin and Skill with the corresponding Codex creator validators before publishing changes.

Pushing a matching vX.Y.Z tag runs the release workflow, validates package, plugin, and extension versions, and attaches the allowlisted Extension ZIP to a GitHub Release.

Uninstall the native host

npm run uninstall-host

Then remove the unpacked extension from chrome://extensions.

License

MIT