Chrome Bridge

Chrome Bridge

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

[License: MIT] [Node 18+] [Chrome 135+] [Tests] [Chrome Web Store] [Chrome Bridge MCP on mcprush]

Claude Code drives the Chrome you are already using — signed in, with your extensions and your cookies. 69 tools: navigation, forms, DOM inspection, network mocking, visual regression, audits, performance traces and the WebMCP tools a page declares. Self-hosted, local-only, no paid plan, works on ChromeOS.

Measured against the official Claude in Chrome extension on the same tasks (paired runs, 17/10/2026, Claude Code 2.1.302, n=5 per task, medians):

15 correct answers out of 15, against 14. Method, every run and the caveats in docs/EFFICIENCY.md.

Quickstart

1. In a Claude Code session:
   /plugin install chrome-bridge --marketplace frsorrentino/chrome-bridge

   From a shell, the same: claude plugin install chrome-bridge --marketplace frsorrentino/chrome-bridge.
2. Add the extension from the Chrome Web Store.
3. 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.

The plugin registers the MCP server from npm together with the recipes skill.

git clone https://github.com/frsorrentino/chrome-bridge.gitcd chrome-bridge && ./install.sh

[The same form filled in 3 turns instead of 15 — 5× fewer turns on the form, 3.9-6.1× lower cost on form, 1,500-row table and debugging (paired runs, 17/10/2026, n=5)]

Why it takes fewer turns

• Refs, not screenshots. navigate returns the page's interactive elements as short refs (n1, n2…), so the next call is the click, not a screenshot and a coordinate guess.
• One call for a whole form. fill_form fills N fields and submits in the same call.
• Filtering on the server. extract_table with where and columns returns the matching rows of a 1,500-row table, not the table.
• Debugging starts with the answer. navigate reports the first console error mapped to its source line and the failed requests with their status; get_css_styles names the rule behind a style and flags undefined CSS variables.
• Deferred loading. 22 stay in context; the rest of the 46 in the default set wait behind Claude Code's tool search (2.1.285+), and loading one mid-session does not invalidate the prompt cache. The other 23, in seven optional groups, switch on mid-session with get_status({enable: [...]}), no restart.

Your browser, your login

No blank profile, no debugging port, no cloud browser. The extension runs in your Chrome, so every site you are signed into is already open to the agent: webmail, the hosting panel, a back office, a staging site behind basic auth. Tabs the agent opens are marked as its own and closed when the session ends; your tabs stay yours. Several Claude Code sessions share the same browser: the second one becomes a relay on the first one's bridge.

WebMCP. When a page declares its own tools through WebMCP, navigate and get_interactives say so in one line, webmcp_tools lists them and webmcp_call runs one, with a timeout. Needs the WebMCP flag or origin trial in Chrome; get_status reports whether it is on.

Limits you can set. upload_file refuses keys and credentials (~/.ssh, .env*, *.pem, …) and --read-root fences it to one directory; --write-root fences every path the model writes; --no-js removes arbitrary JavaScript. The agent never types credentials: for a login, a 2FA code or a choice, handoff shows a banner in the page and waits for you.

Compared

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 tool counts measured on 2026-09-01 and 2026-09-11 (docs/analisi-2026-09-11-concorrenti.md); WebMCP, recording and tracing rows checked in their documentation on 2026-10-28.

[Claude checks its own work: console errors, pixel diffs, network mocking and audits]

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.

[Some jobs never touch the model: the CLI lane runs the same tools at zero tokens]

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

chrome-bridge navigate --url https://example.comchrome-bridge read_console --level error | head -20chrome-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

It looks for Chromium, Microsoft Edge, Brave and last Google Chrome in their standard paths on Linux, macOS and Windows; CHROME_BRIDGE_BROWSER picks another binary. Google Chrome 137+ ignores --load-extension, so the extension never connects in it: use Chromium, Edge, Brave or Chrome for Testing.

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

69 in total. core (46 tools: every tool used in 101 real sessions, plus the two WebMCP tools) loads by default; the other 23 sit in seven optional caps, switched on with get_status({enable: ["visual"]}) or at startup with --caps.

[69 tools in nine groups, from clicking a button to tracing a page]

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

How it works

[It drives the Chrome you are logged into, over a local WebSocket bridge]

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

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.

• Launch mode also opens a DevTools port on 127.0.0.1 (chosen by the system), for lighthouse and heap_snapshot. CDP has no authentication: any local process can drive that dedicated browser while it runs. Its profile is temporary and holds nothing of yours; your own Chrome never gets a port.
• The debugger bar is the signal. click/press_key with trusted, emulate_media via: "debugger", perf_trace and screencast attach chrome.debugger to one tab only for that work; Chrome shows its "started debugging this browser" bar meanwhile, and cancelling it ends the work.
• 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, and see Limits you can set. 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/). A PostToolUseFailure hook writes it, or the server when used without the plugin. A repeated error 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 to send them as one GitHub issue: it shows the anonymized text first and sends only what you choose. /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 69 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/misure/2026-10-token-cache-vs-claude-in-chrome.md — the 17/10 paired set and the prompt-cache breakdown (Italian)
• 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).

Related projects

• agent-webbridge — drives several Chrome profiles at once, with parallel tabs
• awb-recipes — community-maintained, dated per-site recipes for automating logged-in websites

License

MIT