chrome-bridge

Install as a Claude Code plugin

/plugin marketplace add bbauersjt/sjt-chrome-bridge
/plugin install chrome-bridge@sjt-chrome-bridge

Then two manual steps the plugin can't do for you: pip install -r requirements.txt, and load the extension/ folder as an unpacked extension in Chrome (chrome://extensions → Developer mode → Load unpacked). Details below.

---

A direct line from Claude Cowork into your authenticated Chrome session — no linked tab, no file relay, no tab-group sprawl. Cowork calls MCP verbs; a local relay forwards them over a localhost WebSocket to an MV3 extension, which acts inside the live page (reads it, injects JS, calls the backend with the page's own cookies/CSRF) and returns the result.

Cowork ──MCP stdio──► server.py (relay) ──localhost WS (token)──► extension ──► Axcess / Suralink page

This is the generic transport. Site-specific JS (Axcess, Suralink) lives in the skill, not here.

Pieces

File	Role
extension/	MV3 extension. Holds the outbound WS, runs fetch/JS in the page. Load unpacked into Chrome.
server.py	Local stdio MCP server. Registers the chrome_* verbs; pure relay.
bridge_core.py	The WebSocket hub (background thread, request/response correlation).
register_server.ps1	Registers server.py with the Claude desktop app (auto-detects Python + config path, BOM-less).
requirements.txt	mcp, websockets.
selftest.py	Proves the server half with a mock extension — no Chrome/Claude needed.

Verbs

• chrome_bridge_status() — is the server up and the extension connected? Start here.
• chrome_list_tabs() — open tabs (id/url/title); use an id as target.
• chrome_page_info(target="active") — url/title/readyState.
• chrome_fetch(url, method, headers, body, target="active") — runs fetch() inside the page, so it carries that page's cookies/auth/CSRF. The backend-call primitive.
• chrome_eval(code, target="active", world="MAIN") — arbitrary JS, JSON result. MAIN world is subject to the page's CSP (may block eval); prefer chrome_fetch for backend calls.

Setup (Windows)

1. Install deps — pip install -r requirements.txt
2. Load the extension — Chrome → chrome://extensions → enable Developer mode → Load unpacked → select the extension/ folder. The toolbar badge reads on once it connects to the server (which must be running — see step 4/5).
3. Register the server — powershell -ExecutionPolicy Bypass -File ".\register_server.ps1"
4. Fully quit and reopen the Claude desktop app (not just close the window) so it loads the new MCP server and launches server.py.
5. Test — open an Axcess tab and log in, then in Cowork:
   • chrome_bridge_status → extension_connected: true
   • chrome_list_tabs → your tabs
   • chrome_page_info → the Axcess page's url/title
   • chrome_fetch an Axcess backend endpoint → JSON, authenticated.

Verify the server logic anytime without Chrome: python selftest.py → SELFTEST OK.

Security model

• Server binds 127.0.0.1 only and requires a shared token (BRIDGE_TOKEN, must match in bridge_core.py and extension/background.js).
• The relay is capability-by-omission: no filesystem/shell/code-exec verbs. Arbitrary JS (chrome_eval) runs in the browser page, contained by Chrome's sandbox — never on the host.
• You stay logged in as yourself; the extension reuses your live session (correct for an attest tool).

Known limits / next

• DEV token is hardcoded. Before sharing with coworkers, move it to an extension options page (per-user secret), not source.
• Multiple instances self-organize. The desktop app and the Cowork runtime each spawn server.py. The first to bind 8765 is the daemon (owns the extension); any other becomes a controller that proxies its calls through the daemon. So whichever process a call lands on, it reaches the one extension. chrome_bridge_status shows role and (for the daemon) the controller count.
• MV3 keepalive. While connected, the worker pings every 20s so it isn't suspended (WebSocket activity resets Chrome's idle timer). A 30s alarm + on-demand connect cover cold starts, so a dropped socket self-heals within ~30s.
• One extension at a time. The daemon tracks a single extension socket. If the extension is installed in multiple Chrome profiles, disable all but one (the daemon would otherwise bind to whichever connected last). Multi-profile routing is a future enhancement.
• chrome_eval vs page CSP. If a page blocks eval, use chrome_fetch or world="ISOLATED".
• Distribution. One-click handoff later = publish the extension (Web Store / enterprise CRX) + bundle server.py as a Cowork plugin (which registers the MCP server) + freeze Python to an exe so coworkers need no toolchain.
• Port is 8765 (change in both bridge_core.py and background.js if it collides).