Chrome Bridge

By frsorrentino · npm chrome-bridge-mcp · not affiliated with other projects named "chrome-bridge".

An MCP server that gives Claude Code your real, logged-in Chrome — measured
2.75× fewer turns and 2.28× lower cost than the official "Claude in Chrome"
extension on a form-filling task, with ~3× the toolset and no paid plan.

60 web-development tools (navigation, DOM inspection, visual regression, audits,
network mocking) over a local WebSocket bridge, plus a headless instance for CI.
Self-hosted, local-only.

Quickstart

Requires Node.js 18+ and Chrome 135+.

git clone [email protected]:frsorrentino/chrome-bridge.git
cd chrome-bridge && ./install.sh

1. Open chrome://extensions, enable Developer mode, click Load
   unpacked, select the extension/ folder.
2. Restart Claude Code.

Then ask for something like "open localhost:3000, run an accessibility audit
and find the Sign Up button": Claude Code calls navigate,
audit and find_text. Because navigate already returns
element refs, click(ref="n1") follows with no discovery turn in between.

On ChromeOS/Crostini install from the Chrome Web
Store
instead: an unpacked extension is dropped on every reboot, because the
container isn't mounted when Chrome starts.

install.sh registers the MCP server with --scope user. To do it by hand:
claude mcp add --scope user chrome-bridge node /path/to/server/index.js.
For execute_js, enable Allow user scripts in chrome://extensions →
Chrome Bridge → Details (on Chrome 135-137, enable Developer Mode instead).

As a plugin, without a clone: in Claude Code, /plugin marketplace add frsorrentino/chrome-bridge then /plugin install chrome-bridge@chrome-bridge
registers the MCP server from npm (all capabilities) together with the recipes
skill; clients that read Agent Plugins 1.0 get the
same from plugin.json + mcp.json. The extension still comes from the Web
Store or extension/. Pick one path: the plugin and install.sh would
register the same server twice.

Why Chrome Bridge?

Codex for Chrome (OpenAI, May 2026) sits in the Claude in Chrome column: an
official extension with the debugger permission, macOS and Windows only,
the ChatGPT app required. Claude in Chrome documents Linux desktop since
September 2026; ChromeOS and WSL stay out. Competitor figures measured on
2026-09-01 and 2026-09-11 (docs/analisi-2026-09-11-concorrenti.md).

It wins on round trips, not payload size: short element refs instead of the
screenshot-and-click loop, fill_form filling N fields in one call, table
filtering done server-side. Per single turn it actually costs slightly more.

The full benchmark — method, every raw run including the unfavourable ones, and
what the harness can't measure — is in
docs/EFFICIENCY.md.

Using it

The skill in skills/chrome-bridge/SKILL.md
is what makes the tools discoverable: recipes with the phrase that triggers
each one ("verify the email arrives", "test the checkout with a test card",
"which plugin slows the page", "what fires before consent"), the tool sequence,
and the zero-token CLI commands the model would otherwise never see.
install.sh copies it to ~/.claude/skills/chrome-bridge; do the same by
hand for other clients.

Beyond the MCP tools, two lanes keep work away from the model entirely.

CLI — batch operations, piped through grep or jq before anything reaches
the context:

chrome-bridge navigate --url https://example.com
chrome-bridge read_console --level error | head -20
chrome-bridge assert --selector "#success" --text "Done"
chrome-bridge replay --file ./recordings/login.jsonl

Launch mode — a dedicated Chromium instance with an ephemeral profile, for
isolated sessions or CI:

node server/index.js --launch --headless

Pair it with session_record + replay for smoke tests with no model in the
loop. In launch mode execute_js falls back to new Function when the
user-script toggle isn't available.

Tools

60 in total, in seven groups. Only core (39 tools) loads by default; the rest
are opt-in via --caps.

Every tool, with the notes that matter: docs/TOOLS.md.

How it works

Claude Code  <--stdio-->  MCP Server  <--WebSocket :8765-->  Chrome Extension
                          (server/)                          (extension/, MV3)

The Node.js server handles the protocol and tool logic; the MV3 extension
executes commands through Chrome APIs. User scripts (execute_js) run via
chrome.userScripts.execute().

Configuration and security

Environment variables, each with a matching CLI flag:

The bridge binds loopback, accepts extension connections only from a
chrome-extension:// origin, and — when a token is set — requires it on both
handshakes. Without one, any local process could act as a relay and reach
execute_js inside your authenticated browser session. Secondary MCP instances
connect via loopback and are acknowledged with relay_init_ok, so a foreign
process holding the port fails fast instead of timing out per command.

What is not protected: page content reaches the model unfiltered, so a
hostile page's text is untrusted input. get_storage, session_fixture, HAR
exports and screenshots are not redacted and may carry cookies, tokens or
personal data. Don't point the automation at pages holding secrets you wouldn't
paste into a chat.

Threat model

chrome-bridge gives an AI agent your real, logged-in browser. Scanners that
rate MCP servers by capability flag it, correctly, for code execution
(execute_js), requests that carry your cookies (http_request) and reading
private page data (get_storage, get_tabs). Those are the product, not bugs.
What matters is who can reach them and what a hostile page can make the agent
do with them.

• Who can connect: see above — loopback bind, chrome-extension:// origin
  check, CHROME_BRIDGE_TOKEN on both handshakes.
• The real risk is prompt injection. A page can ask the agent to run
  JavaScript, send a request with your cookies, submit a form or upload a file.
  Treat every page you automate as untrusted input, and review what the agent
  proposes on sites that hold money or credentials.
• Reduce the surface: --caps core (the default) exposes the smallest set;
  --no-js removes arbitrary JavaScript; --write-root fences every path the
  model writes; upload_file refuses keys and credentials, and --read-root
  fences it to one directory. For sessions that matter, automate in a separate
  Chrome profile.
• --no-js is not a sandbox: inject_css stays, and CSS attribute
  selectors with url() can leak attribute values to a remote host.
• What leaves your machine is what the browser sends on the agent's behalf.
  chrome-bridge itself has no telemetry; the error log below stays local unless
  you approve an issue.

Local error log

When one of its own tools fails, chrome-bridge adds a line to a local file,
${XDG_STATE_HOME:-~/.local/state}/claude-observe/chrome-bridge.jsonl (mode
0600, in a 0700 folder), in the claude-observe
format (the plugin's copy is in observe/). With the plugin, a PostToolUseFailure hook writes it; with the npm
server alone, the server does. The same error seen again is one line with a
count.

• Kept: the tool name, the error text after scrubbing (your home folder
  becomes ~; emails, URL queries, secrets and typed values are removed), the
  names of the parameters and the length of text values, the chrome-bridge
  version, the OS, the name of the working folder and of the Claude Code config
  folder. With the plugin, also the Claude Code and model versions, the
  session id and the names of the last three tools called.
• Never kept: parameter values — no URLs, selectors, typed text or page
  content.
• Nothing leaves your computer unless you say yes. With the plugin, once
  a few errors have piled up (or one has waited a few days, or one is marked
  as a defect), a line at the end of a turn tells you so, and Claude may offer,
  at a natural moment, to send them as one GitHub issue: it shows you the
  anonymized text first, then asks with buttons (from your GitHub, or not now)
  and sends only what you chose. /chrome-bridge:observe send does the same
  on demand; list, mark and add read and triage the log. The server
  alone never sends or offers anything.
• Security observations (a read or write outside the perimeter, a secret
  exposed, unwanted code execution, data leaving the computer) never enter a
  public issue: /chrome-bridge:observe send --security prepares a private
  vulnerability report for the maintainers, see SECURITY.md.
• Turn it off: {"enabled": false} in ~/.config/claude-observe/config.json
  (every plugin that uses claude-observe), or CHROME_BRIDGE_OBSERVE=off for
  the server. Keep the log but stop the offers: {"propose": false}.

Troubleshooting

Documentation

• docs/TOOLS.md — all 60 tools, by group
• docs/CAPABILITIES.md — what the bridge gets past and what it does not, one dated state per wall
• docs/EFFICIENCY.md — the benchmark and the design behind it
• docs/PERFORMANCE.md — latency per tool on the real path, npm run bench:latency
• bench/RESULTS.md — raw runs and inclusion rule
• CHANGELOG.md

Tests

npm test (Chrome-free, ~22s) · npm run test:e2e (needs Chrome and a
connected extension; with a bridge already on 8765:
CHROME_BRIDGE_PORT=8799 node test/test-devtools.js --launch, which opens
its own Chromium with extension/) · npm run measure (schema cost) ·
npm run bench:latency (milliseconds per tool, launches its own Chromium,
writes docs/PERFORMANCE.md).

License

MIT