Agent Webbridge

agent-webbridge

[npm] [Chrome Web Store] [license] [node]

Let Claude Code, Cursor and any MCP client drive your real, logged-in Chrome — many profiles, many tabs, in parallel. No headless re-login, no bot detection, no cloud. Nothing leaves 127.0.0.1.

Add it to your agent (30 seconds)

npm i -g agent-webbridge && awb setup "Work"     # once: installs the daemon + the Chrome extension

Then add the MCP server to Claude Desktop, Claude Code, Cursor or Windsurf:

{  "mcpServers": {    "chrome": { "command": "npx", "args": ["-y", "agent-webbridge", "mcp"] }  }}

Claude Code: claude mcp add chrome -- npx -y agent-webbridge mcp

Or install it as an agent skill (Claude Code, Cursor, Codex and others): npx skills add jeet-dhandha/agent-webbridge

Your agent now has browser_navigate, browser_snapshot, browser_click, browser_fill, browser_evaluate, browser_screenshot and more — all running in your Chrome, with your sessions. Pass profile to choose an account and tabId to run tabs in parallel. If a call fails, browser_status tells the agent which profile isn't connected.

Why not Playwright or a cloud browser?

It automates a browser you are already signed in to — use it only on accounts and sites you are entitled to automate, and respect each site's terms.

agent-webbridge is a tiny Node daemon (one runtime dependency: ws) plus a clean-room MV3 Chrome extension. An agent POSTs a command to a local router → the router fans it out to the right profile's daemon → the extension attaches the Chrome DevTools Protocol per tab.

See it work

Real runs, not mock-ups: a script sends MCP calls to npx agent-webbridge mcp, which drives a real, signed-in Chrome profile. The screenshots are the browser's own and the timings are measured. Public pages only; nothing is submitted to any account.

Timings come from one MacBook on home broadband; yours will differ.

Overview

• Drive your real browser — your actual Chrome, your actual login sessions. No headless re-login, no scraping around auth.
• Run tabs in parallel — the extension attaches chrome.debugger per tab, so N tabs in one profile run concurrently. 10 tabs finish as fast as 1 (~2 s, flat).
• Span multiple profiles — one daemon per profile. Total concurrency = profiles × tabs, all from one endpoint.
• Stay private — own daemon, own MV3 extension, no closed-source dependency, no account. Everything is local.

Install

npm i -g agent-webbridge        # 1. the daemon + the `awb` CLIawb setup "Work"                # 2. opens the Chrome Web Store; click "Add to Chrome"

awb setup opens the Agent WebBridge listing in your chosen profile and polls while you click Add to Chrome. As soon as it detects the install, it wires the profile to its daemon and brings the fleet up.

Requirements: macOS or Windows · Google Chrome · Node.js ≥ 18.

Quickstart

awb up "Work" "Personal"        # bring profiles up (setup did this on first run)
# Drive any profile by name — using the handy cmd helper function:cmd(){ curl -s -m 60 -X POST http://127.0.0.1:10086/command -H 'Content-Type: application/json' -d "$1"; echo; }
cmd '{"action":"navigate","args":{"url":"https://news.ycombinator.com"},"session":"scan","profile":"Work"}'
awb down                        # stop the fleet when done

Every call is a POST /command on 127.0.0.1:10086. Wrap payloads in single quotes ('...') to prevent shell quote-escaping issues. "session" groups a task's tabs into one Chrome tab group; "profile" picks which Chrome profile to drive. Pass {"action":"screenshot","args":{"path":"/path/to/img.png"}} to save screenshots directly to disk.

Tools

How it works

  AI agent  ──HTTP POST /command──▶  router (127.0.0.1:10086)   routes by "profile"                                          │                       ┌──────────────────┼──────────────────┐                       ▼                  ▼                  ▼                  daemon "Work"      daemon "Personal"     daemon …      one per profile                       │  WebSocket                       ▼                  MV3 extension      ──chrome.debugger (a Map: one attach PER TAB)──▶                       │                       ▼                  Chrome DevTools Protocol      tab 1 ║ tab 2 ║ tab 3   (concurrent)

The router proxies each command to the per-profile daemon on its deterministic hashed port; the daemon relays over WebSocket to that profile's extension; the extension keeps a Map of chrome.debugger attachments — one per tab — and issues CDP calls. That per-tab map is the whole trick: bridges that funnel everything through a single "current tab" can only drive one tab per profile; this drives N.

CLI

<profile> is anything that resolves uniquely — the profile name ("Work"), an email, or the Chrome directory ("Profile 2").

Use it from an AI agent

Ship it as a Claude Code skill / plugin — the bundled agent-webbridge skill teaches an agent the full flow (install via awb check --json, then drive over POST /command). To hack on the extension itself, awb install-dev Load-unpacks the in-repo build (chrome://extensions → Developer mode → Load unpacked → agent-webbridge-extension/); it ships its own key, so the dev id is stable across reloads.

Platform

Set AWB_CHROME_BIN / AWB_CHROME_DIR if Chrome or its data directory is somewhere non-standard (Chrome Beta, portable installs). Linux paths are wired up but untested.

On Windows, run commands from PowerShell or cmd (the curl examples below use bash quoting; in PowerShell use curl.exe and a here-string, or just use the MCP server). The daemon and the Windows code paths are covered by CI on windows-latest; the Chrome-launching steps (awb setup / awb up) are the least-tested part — please open an issue if one misbehaves.

Security

• Everything listens on 127.0.0.1 only. As of 1.3.1 the router and daemons also refuse requests that carry a web Origin or a non-loopback Host, so a website you visit cannot drive the bridge (see the changelog). Upgrade from earlier versions and restart the fleet with awb down && awb up.
• It acts as you, in your signed-in browser. Any local program that can reach 127.0.0.1:10086 can do the same, so only run it on a machine and account you trust, and keep irreversible actions (posting, paying, deleting) behind a human confirmation in your agent.
• Report vulnerabilities privately through GitHub's "Report a vulnerability" on the Security tab.

License

MIT © jeet-dhandha