chrome-bridge

Agent tools like Claude Code, Codex and Cursor can drive web pages, but they can't touch the browser itself: bookmark folders, tab groups, which tabs are open. Chrome only exposes those to extensions. chrome-bridge is that extension plus a tiny MCP server, so you can say things like:

Make bookmarks for every server in this list under Bookmarks bar/Lab, then open them as a tab group called "Lab" in cyan.

and the agent does it.

How it works

 Claude Code / Codex / Cursor / shell
              │  MCP (stdio) or `chrome-bridge call`
              ▼
   bin/chrome-bridge.mjs ── opens 127.0.0.1:4736x only while in use
              ▲
              │  WebSocket, mutual HMAC handshake
              │
   extension/ (MV3 service worker) ── chrome.bookmarks / tabs / tabGroups

• The server opens its port only when a tool is called and closes it after 5 minutes idle.

• The extension's service worker wakes every 30 s (the chrome.alarms minimum), tries the ports, finds nothing, and goes back to sleep. Nothing stays resident for the life of the browser.

• The cost of that design: the first call after an idle period waits up to ~30 s for the extension to connect. Calls after that are immediate.

• Up to five servers can run at once (ports 47361-47365), so several agent clients can each have their own.

Related MCP server: Tabryn

Security

Out of scope: anything already running as your user account can read the secret file. That's the same trust boundary as your Chrome profile itself.

Install

Requires Node 20+ and Chrome 120+.

git clone https://github.com/PLCMercenary/chrome-bridge.git
cd chrome-bridge
npm ci                         # one dependency: ws
./bin/chrome-bridge.mjs pair   # generates the shared secret

pair writes the secret to ~/.config/chrome-bridge/secret and extension/pair.json (both mode 0600, and pair.json is gitignored). Run it again any time to rotate the secret.

Then load the extension:

1. Open chrome://extensions and turn on Developer mode.

2. Click Load unpacked and pick the extension/ folder.

3. After any pair rotation or code update, click the reload icon on the extension's card.

Optionally put the CLI on your PATH:

ln -s "$PWD/bin/chrome-bridge.mjs" ~/.local/bin/chrome-bridge

Connect your agent

Use absolute paths. GUI clients often don't inherit your shell's PATH, so point at the real node binary (command -v node).

Claude Code

claude mcp add --scope user chrome-bridge -- "$(command -v node)" "$PWD/bin/chrome-bridge.mjs" mcp

Codex

codex mcp add chrome-bridge -- "$(command -v node)" "$PWD/bin/chrome-bridge.mjs" mcp

Cursor (~/.cursor/mcp.json), or any client that takes the usual JSON form:

{
  "mcpServers": {
    "chrome-bridge": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/chrome-bridge/bin/chrome-bridge.mjs", "mcp"]
    }
  }
}

Anything else can use the CLI:

chrome-bridge tools
chrome-bridge call bookmarks_tree '{"depth": 1}'
chrome-bridge call tab_group_create '{"title":"Docs","color":"blue","urls":["https://developer.chrome.com/docs/extensions"]}'

Tools

Colors: grey, blue, red, yellow, green, pink, purple, cyan, orange.

Folder paths

Paths look like Bookmarks bar/Work/Servers and match case-insensitively. Recent Chrome versions keep two copies of each root folder when you're signed in: a synced account copy and a local-only copy, merged in the UI. The bridge searches both and prefers the synced one, so new items sync to your account. If a name is ambiguous, the error lists the candidate ids so you can use parentId instead.

Known limits

• Closed saved tab groups are invisible. Chrome doesn't expose saved groups to extensions while they're closed. Click a group's chip to open it and the bridge can see and edit it.

• Whether ungrouping or closing an open saved group also deletes the saved chip hasn't been verified yet.

• Incognito windows are only visible if you allow the extension in incognito.

Troubleshooting

Layout

bin/chrome-bridge.mjs     MCP server + CLI (Node, ESM)
extension/manifest.json   MV3 manifest: bookmarks, tabs, tabGroups, alarms, storage
extension/background.js   connection, auth, and the command table
extension/popup.*         on/off switch and connection status
assets/logo.svg           project logo

License

MIT