ZCode for Chrome

A Chrome extension (MV3) plus an MCP server that give ZCode control of your real browser: tabs, page reading, snapshots with stable references, clicks, form filling, keyboard input, scrolling, screenshots, and JavaScript evaluation. It runs on the profile you actually browse with, sessions and extensions included.

Architecture

ZCode -> MCP over stdio -> Node server (packages/server)
server -> WebSocket on 127.0.0.1, ports 8765-8785 -> extension
an offscreen document in the extension keeps that WebSocket open
the offscreen document forwards each request to the service worker via chrome.runtime.sendMessage
the service worker runs it with chrome.tabs, chrome.scripting, or chrome.debugger
the response travels back the same path to ZCode

The offscreen document only has access to chrome.runtime messaging: it has no chrome.storage and no chrome.runtime.getManifest, so anything it needs from those (the token, the extension version) it asks the service worker for by message.

The repo is a monorepo with three packages: packages/shared (protocol types and constants), packages/server (the MCP stdio server with the WebSocket bridge), and packages/extension (the extension you load into Chrome).

Related MCP server: Chrome Browser Control

Install

You need Node 22+ and Chrome 120+.

1. Build:

   npm install
   npm run build

2. Open chrome://extensions, turn on "Developer mode" (top right corner), click "Load unpacked", and select this repo's packages/extension/dist directory.

3. Register the server with ZCode: in ~/.zcode/cli/config.json, under mcp.servers, add the zcode-for-chrome entry from docs/zcode-config.example.json, replacing <ABSOLUTE_PATH_TO_REPO> with the absolute path where you cloned the repo. If you're not using a shared token, drop the whole env block.

4. Restart your ZCode session and check under Settings -> MCP that zcode-for-chrome shows as connected.

Once it's running, open the extension's popup to see the bridge status. That's where you set the shared token, the blocked-hosts list, and the two safety toggles described below.

Tools

The 20 tools ZCode sees through the server. tabId is optional wherever it appears: omit it and the tool acts on the active tab of the most recently focused window. Action tools accept ref or selector; refs like e1, e2, e3... come from snapshot or query_selector and expire once the page navigates (STALE_REF error: take a new snapshot).

Security model

The extension operates your real browser, so the safeguards are on by default and controlled from the popup:

• Localhost only. The server listens on 127.0.0.1 and the WebSocket only accepts connections whose Origin starts with chrome-extension://. There's no daemon: the process exits when ZCode closes its stdin.

• Optional shared token. Start the server with ZCODE_CHROME_TOKEN and the extension must send the same token (set it in the popup). Without a token, the only defense is the Origin header, which has a known gap: any local process can spoof that header and connect to the bridge. Set a token if your machine runs code you don't trust.

• One bridge at a time. The server binds the first port of the range (8765) or, with ZCODE_CHROME_PORT set, that exact port; if the port is taken by another live bridge, it waits for it to free up instead of silently sliding to the next port (which used to strand the second ZCode session with no extension, since the extension always picks the lowest healthy port). Set ZCODE_CHROME_ALLOW_SCAN=1 to restore the old scan-the-range behavior. While waiting, browser_status reports the conflict and tool errors name the port holder.

• Protected pages. Page tools refuse to act on chrome://, chrome-extension://, devtools:, about:, edge:, file:, view-source:, and the Chrome Web Store (PROTECTED_PAGE), plus any host in your blockedHosts list, which accepts patterns like *.bank.com (BLOCKED_HOST).

• Global switch. The popup's enabled toggle cuts off every tool except browser_status (EXT_DISABLED) and detaches any attached debuggers.

• evaluate_js has its own toggle. allowEvaluateJs can be turned off (EVAL_DISABLED); it runs with a 10s timeout, truncates results to 50,000 characters, and returns exceptions as errors with their message.

• Limits. One in-flight command per tab, four tabs in parallel; per-tool server timeouts (45s navigation, 20s screenshots and evaluate_js, 15s everything else); screenshots capped at two per second.

• Data. Screenshots stay in memory and never touch disk. Server logs (stderr only) record the tool, tab, host, and duration, never fill or type_text values or page content. The popup keeps a rolling log of the last 50 actions.

• Debug bar. press_key, type_text, evaluate_js, trusted clicks, and full-page screenshots go through chrome.debugger, so Chrome shows the "ZCode for Chrome started debugging this browser" bar while they run. The attach is lazy and detaches after 30s of inactivity.

Limitations

• Only acts on each tab's main frame; iframes are out of reach.

• screenshot captures the window's active tab: if the requested tab isn't active, it activates it first (a visible side effect).

• Chrome 137+ ignores --load-extension, so loading is manual from chrome://extensions and there's no automated E2E from the command line.

• CDP-based tools fail with DEBUGGER_UNAVAILABLE if DevTools is open on the target tab; close it and retry. DOM tools keep working.

• The extension connects to a single server: with two ZCode sessions open, the bridge belongs to the session that took the port first, and the other session's tools fail with a hint naming the port holder. Closing the first session (or killing its server) hands the bridge to the waiting one within seconds; the running extension reconnects on its own.

Verify

npm run smoke        # headless: real server + a simulated extension over WebSocket
npm run smoke:live   # against your real Chrome, with the extension loaded

smoke checks that the server exposes all 20 tools, rejects web origins and wrong tokens, that screenshot returns an image, that errors carry their code, and that the process exits when stdin closes. It also checks that dist/offscreen.js doesn't call any chrome.* API outside what Chrome exposes to offscreen documents.

smoke:live opens https://example.com/, waits for the page text, takes a snapshot, clicks the link by ref, goes back, takes a screenshot, evaluates 1+1, presses End, and closes the tab. It needs the extension loaded and Chrome open; it waits up to 60s for the connection.

License

MIT, see LICENSE.