Laptop Browser Bridge — MCP server + Chrome extension

Yes — a Chrome extension is the right approach (and fully possible). This repo lets an AI coding agent running on your VPS control any website in your laptop's Chrome.

[Laptop Chrome + Extension] --outbound WSS--> [VPS: Bridge :3001 + MCP :3000] --MCP--> [AI agent on VPS]

Laptop is behind NAT, so the extension dials out to the VPS. No port-forwarding on the laptop. The MCP server runs next to the agent on the VPS.

Repo layout

src/
  index.ts     # starts WS bridge (:3001) + MCP Streamable HTTP (:3000)
  bridge.ts    # tracks connected laptops, request/response correlation
  mcp.ts       # MCP tools: tabs_*, page_snapshot/click/type/press/scroll/...
  protocol.ts  # WS message types
extension/
  manifest.json
  popup.html / popup.js          # configure VPS URL + token
  background/service-worker.js   # WS client, tab APIs
  content/content.js             # DOM snapshot/click/type

Related MCP server: MCP Chrome Bridge

MCP tools (what the VPS agent gets)

Typical agent loop: bridge_status → tabs_create/page_navigate → page_snapshot → page_click/page_type → repeat.

1. VPS setup

git clone <this-repo> && cd browser-bridge-mcp
cp .env.example .env   # set BRIDGE_TOKEN to a long random secret
npm install
npm run build
BRIDGE_TOKEN=your-secret npm start
# → WS  ws://0.0.0.0:3001/bridge
# → MCP  http://0.0.0.0:3000/mcp
# → health http://0.0.0.0:3000/health

Production: put wss:// in front via Caddy/Nginx (TLS terminates there, proxies to :3001). Keep :3000 on localhost — the agent runs on the same VPS.

Connect your agent (same VPS) to http://localhost:3000/mcp. Examples:

opencode / Claude Code / generic MCP client:

{ "mcpServers": { "laptop-browser": { "url": "http://localhost:3000/mcp" } } }

2. Laptop setup (Chrome)

1. chrome://extensions → enable Developer mode → Load unpacked → select extension/.

2. Click the extension icon → set:

   • Bridge URL: wss://your-vps-domain (or ws://<vps-ip>:3001 for testing)

   • Token: same BRIDGE_TOKEN

   • Client ID: laptop-1

3. Save + Connect → status turns green. Keep Chrome open; laptop must stay awake.

3. Verify end-to-end

On VPS: curl localhost:3000/health should list laptop-1. Then in the agent: call bridge_status, then tabs_list, then page_snapshot.

Security notes

• BRIDGE_TOKEN is mandatory in production — bridge rejects bad tokens (code 4401).

• Extension uses <all_urls> + tabs/scripting because the point is "any website". It only acts when the VPS sends a command.

• page_evaluate is powerful — only connect agents you trust. For hardening: bind MCP to 127.0.0.1, add IP allowlist, rotate token.

• MV3 service workers sleep — the extension reconnects with backoff + alarms heartbeat (~20s).

Dev

npm run typecheck
npm run build
npm run dev   # tsx watch