Agent Chrome Bridge

English | 简体中文

Let local AI agents work with the Chrome browser you already use, including your existing signed-in sessions. A Manifest V3 extension connects Chrome to a local, dependency-free MCP server through Native Messaging.

Status: v0.1.0 / MVP. Tested on macOS with real Chrome. Linux registration is implemented but has not been verified; Windows is not supported. This is an independent project, not an official product of Google, OpenAI, or any agent provider.

What it does

• Lists accessible tabs, reads page text and actionable elements, and enumerates frames.

• Clicks, fills ordinary inputs, selects options, scrolls, opens pages, and navigates tabs.

• Captures the visible viewport and returns images through MCP.

• Uses the browser's existing login state without exporting cookies.

• Reconnects automatically and coordinates multiple clients with per-tab leases.

• Provides persistent pause and write-action controls in the extension popup.

Site access is requested when the extension is installed. There is no additional per-site allowlist or repeated debugger-attachment prompt. Chrome's own site-access restrictions and the agent client's approval policies still apply.

Related MCP server: TraeBridge MCP Server

Architecture

Local agent / MCP client
        │ MCP stdio (JSON-RPC)
        ▼
src/mcp.mjs
        │ Unix socket (0700 directory / 0600 socket)
        ▼
src/native-host.mjs
        │ Chrome Native Messaging
        ▼
Manifest V3 extension
        │ tabs / scripting / ISOLATED DOM operations
        ▼
Your existing HTTP(S) pages

No debugger permission, remote debugging port, or public network listener is used by the bridge. The optional test fixture server listens only on loopback.

Quick start (macOS)

Requirements: Node.js 20+, Google Chrome 120+, and Git. The project has zero npm dependencies; npm install is not required.

1. Clone and register the native host

git clone https://github.com/FUTUREWORKER/agent-chrome-bridge.git
cd agent-chrome-bridge
npm run prepare:extension
npm run install:host -- --register

Keep this checkout in a stable location: Chrome runs the native host from it. prepare:extension prints the absolute extension directory. The installer generates .runtime/mcp-config.json, a native-host launcher, and a manifest using your actual Node executable and checkout paths. --register also installs the manifest into Chrome's per-user Native Messaging directory. Without --register, the command only generates local files.

2. Load the Chrome extension

1. Open chrome://extensions and enable Developer mode.

2. Choose Load unpacked and select this checkout's extension directory.

3. Open the extension popup. The current popup is in Chinese; 已连接 · 可供 Agent 使用 means “Connected · Ready for agents”.

4. For access across websites, set Chrome's extension Site access to On all sites. You can restrict this later in Chrome.

The bundled public key keeps the unpacked extension ID stable: ghpncnhckadomkikpdngadhmjcckcdbi. It is a public identifier, not a secret or signing private key. If the ID differs, verify the loaded directory and rerun the installer.

The bridge starts with connection and write actions enabled. 暂停连接 pauses the connection; 允许点击、输入和导航 controls clicks, input, and navigation. These settings persist. Disabling write actions still allows reads, scrolling, and screenshots; screenshots may focus a tab when explicitly requested.

3. Connect your agent

Merge the agent-chrome entry from .runtime/mcp-config.json into your client's MCP settings, preserving its other servers. The client must support launching a local stdio MCP process. Restart or reload its MCP configuration as needed.

Illustrative configuration only—use the generated file's real absolute paths:

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

A cloud-only agent cannot reach your Mac by using its own localhost. Remote HTTP MCP access and per-agent authentication are not implemented. Compatibility with any specific third-party agent client, including Grok Bot, has not been verified.

4. Check the connection

npm run doctor
node src/cli.mjs status
node src/cli.mjs tabs

doctor checks host registration, the socket, directory permissions, and live bridge status. It exits unsuccessfully if the bridge cannot be reached.

Tools and usage

Recommended sequence: browser_tabs → browser_snapshot → act using returned ref values → read again to verify → browser_release.

References are bound to a page/frame and its latest snapshot. Do not guess references or reuse them after a new snapshot, navigation, or element replacement. For frames, call browser_frames, then pass the returned frameId to snapshot and element tools.

CLI examples (replace 123 and REF_FROM_SNAPSHOT with actual returned values):

node src/cli.mjs snapshot '{"tabId":123}'
node src/cli.mjs fill '{"tabId":123,"ref":"REF_FROM_SNAPSHOT","text":"Hello"}'
node src/cli.mjs browser_select '{"tabId":123,"ref":"REF_FROM_SNAPSHOT","value":"b"}'

Each CLI invocation disconnects on completion, so tab leases do not persist across CLI commands. Prefer a persistent MCP connection for multi-agent work. A tab can be leased by one connection at a time; release it explicitly or disconnect. Browser actions are serialized across clients, including actions on different tabs.

Security and privacy

• Installing the extension grants broad ongoing site access. Only connect agents and local software you trust.

• Any process running as the same OS user can use the local bridge. Socket permissions isolate other OS users; they do not authenticate individual agents.

• Page text, tab titles/URLs, and screenshots are returned to the calling client. Whether that client forwards them to a cloud model depends on its configuration.

• Password input values are omitted. Automatic filling rejects password/file inputs and fields marked with autocomplete values for one-time codes, card numbers, or card security codes. This is not general-purpose secret detection; text and screenshots can contain sensitive information.

• Web content is untrusted input. The calling agent must handle prompt injection and obtain any necessary approval for submissions, payments, or destructive actions. The bridge does not enforce per-action human approval.

• Automatic reconnection does not replay business commands. After a timeout or disconnect, inspect the page before retrying: the action may already have occurred.

See SECURITY.md for the security model and reporting guidance.

Limitations

• Ordinary HTTP(S) pages only. Chrome internal pages, extension pages, file URLs, and incognito windows are unsupported. Protected pages such as the Chrome Web Store may reject injection.

• Uses DOM events. Sites requiring trusted native input may not work. No native keyboard/mouse control, coordinate-based Canvas clicks, drag-and-drop, file uploads, browser-dialog handling, or full Playwright API.

• Supports open shadow roots; closed roots are inaccessible. Frames remain subject to Chrome permissions, sandboxing, and URL restrictions.

• A snapshot returns at most 300 actionable elements and 50,000 text characters (18,000 by default). It is not a full-site crawler.

• Screenshots capture only the viewport. The target must be active; activate: true switches tabs and focuses the window. Chrome applies capture rate limits.

• One Chrome profile per OS user can own the bridge at a time. Pause the other profile before switching.

Development and verification

npm test
# Optional: requires the installed, connected extension with write actions enabled.
node scripts/e2e.mjs
# Optional: open the printed local URL and click “运行 DOM 验证”.
node scripts/fixture-server.mjs

The Node tests use isolated temporary state and simulated extension responses; they do not require a running browser. The live end-to-end test opens a new local fixture tab, manipulates only that page, activates it for a screenshot, and writes local artifacts under docs/. These generated artifacts are gitignored. The fixture tab can be closed after testing.

The initial macOS validation recorded 12 Node tests, 8 live DOM checks, and 9 live MCP checks passing, plus automatic reconnection. See verification notes for scope and remaining gaps. These results are not a guarantee of compatibility with every website or agent.

Contributions are welcome; see CONTRIBUTING.md.

Troubleshooting

Uninstall

Pause the connection in the popup, remove the extension from Chrome, remove agent-chrome from your MCP client configuration, then run from this checkout:

node scripts/uninstall.mjs --confirm

The script removes only the Native Messaging registration that points to this checkout. It does not delete the source, generated files, or other extensions. You can remove this checkout separately when it is no longer needed.

License

MIT License. Copyright (c) 2026 FUTUREWORKER and contributors.

References

• Chrome Native Messaging

• Chrome scripting API

• Chrome screenshot API

• MCP stdio transport