browser-relay

Drives the user's real, logged-in Chrome from AI agent sessions without ever handing another browser client the user's cookies (which gets sessions invalidated). An MV3 extension lives inside real Chrome and executes commands sent over a WebSocket from a local relay daemon.

Architecture

Claude session -> MCP (HTTP :9277/mcp) -> relay daemon -> WebSocket -> MV3 extension -> real Chrome tabs

• extension/ - the Chrome MV3 extension.

• server/relay.js - the relay daemon: MCP streamable-HTTP server + WebSocket server. Node >= 18, single dependency (ws).

• deploy/ai.wecko.browser-relay.plist - launchd LaunchAgent template (macOS); install.sh fills in your node and repo paths.

• install.sh - installs deps + the LaunchAgent and prints the two remaining manual steps.

• test/ - MCP smoke test (e2e.sh), a direct tool-call helper (call.js), and a mock extension for testing the relay without Chrome.

The extension connects out to ws://127.0.0.1:9277/ws as a client (it does not run a server itself), sends a hello on open, and answers every command the relay sends with exactly one ok:true/ok:false reply.

Related MCP server: Chrome MCP Server

Install

/bin/bash install.sh

This copies the LaunchAgent, (re)starts it, and waits for http://127.0.0.1:9277/health to answer. It then prints two steps you do by hand:

1. Register the MCP server:

   claude mcp add --transport http browserx http://127.0.0.1:9277/mcp -s user

2. Load the extension: chrome://extensions -> enable Developer mode -> Load unpacked -> select extension/.

Tools (relay commands)

tab_id is optional everywhere it appears - it falls back to the active tab of the last focused normal window.

snapshot is the main way an agent finds things to act on: it walks the top document (same-origin iframes are out of scope in v1) for interactive elements, tags each one with a stable data-bx-id="eN" ref, and returns a compact list plus a text excerpt of the page. click and type_text then target elements by that ref.

Known limitations

• Synthetic input is not trusted input. click and type_text dispatch real DOM events, but they are not OS-level input, so some sites (payment iframes, bot-detection-heavy forms) may reject or flag them.

• Screenshots require the tab to be active. chrome.tabs.captureVisibleTab only captures the active tab of a window; screenshot briefly activates the target tab if it isn't already, then restores the previous one.

• evaluate can be blocked by a page's CSP. Strict script-src policies can reject the injected eval; when that happens the error is surfaced verbatim rather than swallowed. A future version should switch to chrome.userScripts.execute in the USER_SCRIPT world, which is exempt from page CSP.

• The MV3 service worker gets killed by Chrome. It is normal for background.js to be torn down and revived repeatedly; the bx-keepalive alarm (every ~24s) and the reconnect-on-close logic are what keep the WebSocket connection coming back. A short gap in connectivity right after Chrome starts or the SW is revived is expected.

• Google (and similar) may challenge with reCAPTCHA or a security check. If that happens, the agent must stop and ask the human to clear it in the real browser window rather than trying to script around it.

• Same-origin iframes are not walked by snapshot in v1.

Troubleshooting

• curl 127.0.0.1:9277/health - confirms the relay daemon is up.

• tail -f relay.log - relay daemon stdout/stderr (from the LaunchAgent).

• Reload the extension from chrome://extensions if it stops responding.

• Inspect the service worker console: chrome://extensions -> browserx relay -> "service worker" link, to see WebSocket connect/reconnect logs and any errors from injected scripts.