Connects AI agents to real Chrome tabs to provide structured access to DOM, styles, layout, console, network, and accessibility data.
Also known as koltyakov/browser-bridge, @browserbridge/bbx
- Stars
- 31
- Tools
- —
- Downloads, 30 days
- 2,249
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is Browser Bridge MCP?
Browser Bridge connects AI agents to real Chrome tabs to provide structured access to DOM, styles, layout, console, network, and accessibility data.
Summary generated from the project's README
About Browser Bridge MCP server
Browser Bridge provides a local connection between AI coding agents and active Chrome tabs. Unlike headless automation tools that start from a clean state, this server allows agents to inspect the existing state of a real browser window, including logged-in sessions, feature flags, and specific application data. It works by using a Chrome extension alongside a native CLI installed on macOS, Linux, or Windows.
Developers can use this to give agents structured access to the DOM, computed styles, layout information, console logs, and network data. The system supports a wide range of agents including Claude Code, Cursor, GitHub Copilot, and Windsurf. It is designed for deep debugging and verification tasks where an agent needs to see exactly what a user sees in a live tab.
Setup involves installing the extension from the Chrome Web Store and running a platform-specific installation script. The server operates through MCP or native messaging, allowing for precise interactions like handling JavaScript dialogs and applying reversible patches to a live page to test fixes before committing them to source code.
What you can do with it
- 1Debug local UI stateAn agent can inspect the DOM, styles, and console logs of a running localhost application to find errors.
- 2Verify code changes visuallyUse the bridge to confirm that a recent code update rendered the correct results in a real browser tab.
- 3Test live page patchesApply a temporary fix to a live website to see if it works before moving the change into the actual source code.
- 4Capture network evidenceExport sanitized network reproduction data in HAR format to analyze web requests.
Written from the project's README. Every use case is checked against a quote from it.
How to install Browser Bridge MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Browser Bridge MCP in Claude Code
$ claude mcp add browser-bridge -- npx -y @browserbridge/bbxInstall Browser Bridge MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"browser-bridge": {
"command": "npx",
"args": [
"-y",
"@browserbridge/bbx"
]
}
}
}Install Browser Bridge MCP in VS Code
.vscode/mcp.json
{
"servers": {
"browser-bridge": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@browserbridge/bbx"
]
}
}
}Install Browser Bridge MCP in VS Code CLI
$ code --add-mcp '{"name":"browser-bridge","type":"stdio","command":"npx","args":["-y","@browserbridge/bbx"]}'Install Browser Bridge MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"browser-bridge": {
"command": "npx",
"args": [
"-y",
"@browserbridge/bbx"
]
}
}
}Install Browser Bridge MCP in Codex
$ codex mcp add browser-bridge -- npx -y @browserbridge/bbxInstall Browser Bridge MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.browser-bridge] command = "npx" args = ["-y", "@browserbridge/bbx"]
Install Browser Bridge MCP in Gemini CLI
$ gemini mcp add -s user browser-bridge npx -- -y @browserbridge/bbxInstall Browser Bridge MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"browser-bridge": {
"command": "npx",
"args": [
"-y",
"@browserbridge/bbx"
]
}
}
}Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablekoltyakov/browser-bridge is public and reachablegithub.com/koltyakov/browser-bridge ↗Pass
- Package names this repository as its source@browserbridge/bbx names koltyakov/browser-bridge as sourcenpmjs.com/package/@browserbridge/bbx ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @browserbridge/bbxnpmjs.com/package/@browserbridge/bbx/v/2.1.1#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/koltyakov/browser-bridge ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @browserbridge/bbxPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubBrowser Bridge (BBX)

Chrome Web Store: Install
Browser Bridge (BBX)from the Chrome Web Store. For local or custom builds, use the unpacked install flow in docs/unpacked-extension.md.
A local bridge between your coding agent and a real Chrome tab. Browser Bridge gives the agent structured access to DOM, styles, layout, console, network, accessibility data, reliable browser input, explicit JavaScript dialog handling, and reversible patches - starting from the actual tab you already have open, with all its real state intact.
See Quickstart to get started in another repo, or browse the rest of the guides in docs/index.md.
Upgrading an existing installation? Follow the v1 to v2 migration guide to update the extension, replace the Node.js runtime, and refresh agent setup.
Supported Agents
Managed installs support Codex (OpenAI), Claude Code, OpenCode, GitHub Copilot, Cursor, Devin Desktop (formerly Windsurf), Antigravity, Gemini CLI, Cline, Zed, Amp, Factory Droid, Pi, Kilo Code, Qwen Code, Goose, OpenHands, Muse Code, Grok Build, and generic .agents layouts for MCP and CLI skills. Devin Desktop keeps the windsurf setup target for compatibility. Cline, Goose, OpenHands, and Muse MCP setup is user-scope only; their CLI skills also support projects. Zed support targets its native agent; external agents keep their own configuration.
What it's for
- Debugging a UI on
localhost: read DOM, computed styles, layout, console logs, and network state without a screenshot - Exporting sanitized, metadata-only HAR 1.2 evidence after explicitly capturing a network reproduction
- Verifying a code change actually rendered the expected result in Chrome
- Patching the live page to prove a fix visually, then moving it into source and rolling the patch back
- Running structured browser checks from any local agent or IDE, not just one AI product
- Calling website-provided WebMCP tools when the browser supports them, with exact-action user approval and DOM verification
Why Browser Bridge
Most adjacent tools optimize for different goals. Playwright and headless automation stacks are excellent for deterministic tests and CI - but they start from a clean browser context by design. Claude in Chrome is great for integrated Claude workflows, and the Codex extension is a great option if you use Codex, but both are vendor-specific. Generic MCP browser servers offer broad control without the developer-focused depth.
Browser Bridge is optimized for the opposite starting point: inspect the state that already exists in a real tab - logged-in sessions, feature flags, seeded storage, SPA state - use structured reads to understand it, test a patch in place, then fix the source. It's open-source, agent-agnostic, and scoped to one explicitly enabled browser window rather than ambient browser control.
Setup
-
Install Browser Bridge from the Chrome Web Store in Chrome or another Chromium-based browser
-
Install the native CLI with the script for your platform. No Node.js, npm, or Go installation is needed.
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/koltyakov/browser-bridge/main/scripts/install.sh | shWindows x64, PowerShell:
irm https://raw.githubusercontent.com/koltyakov/browser-bridge/main/scripts/install.ps1 | iex -
Return to the extension and choose your agent under Connect your agent. Start with MCP.
-
Enable access for the browser window you want the agent to use.
-
Ask your agent to use Browser Bridge.
The installers download the latest stable executable from GitHub Releases, verify its SHA-256 against the release's checksums.txt, install to ~/.local/bin, register every supported browser where Browser Bridge is detected, and restart the daemon. Existing native registrations are refreshed too. Supported platforms are macOS arm64/x64, Linux arm64/x64, and Windows x64. Keep ~/.local/bin on your shell's PATH on macOS and Linux. Windows adds it to your user PATH; open a new terminal afterward.
To match your extension's release line, use the install command shown in its setup panel. The scripts accept BBX_VERSION=2.0 on macOS/Linux or -Version '2.0' in PowerShell to select the newest stable 2.0.x patch, or an exact version. They also try to remove an existing global @browserbridge/bbx npm package so its launchers do not shadow the standalone CLI. See the installer options for browser, version, and installation-directory overrides.
Generated MCP configurations use the Go binary's absolute path, not npm, npx, Node, or a bbx shim. Native messaging launchers also execute the binary directly.
If the extension does not connect, run bbx install to detect and register its browsers. Register only a specific browser with bbx install --browser chrome|edge|brave|chromium|arc. See browser detection for profile discovery and fallback behavior.
On Ubuntu, Chromium is commonly installed as a strict snap, and Flatpak Chromium is similarly sandboxed. If native messaging stays disconnected there, use a non-sandboxed Chromium-based browser such as Google Chrome, Brave, or Edge.
MCP mode is self-contained: the dual-era stdio server supports legacy MCP clients and modern stateless MCP revision 2026-07-28, and exposes tools and matching startup instructions without requiring a separate CLI skill.
Alternative: install with npm
With Node.js 20 or later installed:
npm install -g @browserbridge/bbx
The npm package is a bootstrap and launcher with zero runtime npm dependencies. It downloads and verifies the latest stable Go executable independently of the npm package version, then registers the native host. Set BBX_VERSION to select a release line or exact native version. Local dependency installs do not register a browser; if install scripts were skipped, the first command downloads the executable, then run bbx install to register it. See the native CLI guide.
How it works
- The extension is scoped to one explicitly enabled Chrome window at a time - no ambient browser access
- Requests default to the active tab in that window unless a tab is targeted explicitly
- Targeted input actions reject hidden, disabled, ambiguous, stale, or obscured targets instead of silently guessing; their responses report the resolution and DOM/CDP execution path (
cdp_press_keyandscroll_into_viewuse separate contracts) - Native pointer/text input, dialog handling, all-resource network capture, accessibility trees, screenshots, and raw CDP reads use the existing debugger permission only when requested
- HAR export is a read of an already armed CDP capture: start capture, reproduce, export, then stop. Export never starts, stops, or clears capture, and omits headers, cookies, bodies, authorization values, and unsupported size/timing detail
- HAR and screenshot artifacts are opaque, owner-scoped daemon handles with a five-minute lifetime and no browser-host path; CLI capture commands download, verify, delete, and write them on the CLI host
- File workflows include staged uploads, trusted PNG paste, and browser-native large downloads with progress, pause/resume, and cancellation
- Opt-in recording supports child-tab watch, timing correlations, durable crash-recovery journals, continuous renderer playback, and local MP4 export
- Element references are document-local and strict by default; stale input recovery is opt-in, same-document, requires one strong unique semantic match, and fails safely when its bounded scan cannot prove uniqueness
- Semantic DOM baselines provide explicit create/compare/describe/release verification without modifying the page; compact snapshots stay memory-only, expire after five minutes, and are invalidated by navigation or access teardown
- Patches keep per-document rollback history and Browser Bridge attempts best-effort rollback when window access is disabled or switched; committing the patch baseline keeps current changes but discards their rollback history
- URL waits observe full navigation and same-document SPA changes, and report the final URL and observed navigation kind
- Structured DOM/style/layout reads are the primary transport; screenshots are a fallback
- Browser input dispatch does not prove the application accepted the intended change, so agents should verify with a wait or structured read
- Open-ended investigation should start with structured reads on a smaller, lower-cost subagent when the client supports delegation
- Recovery diagnostics use process-local five-minute counters for six fixed, content-free categories.
health.ping,daemon.metrics, andbbx doctorexpose no page data; three failures in the same category group within 60 seconds produce an active-loop warning and fixed recovery guidance - Performance reads are raw browser-maintained CDP counter point samples with browser-defined names and units, not Web Vitals or Browser Bridge navigation measurements
- The native host daemon auto-starts on demand
Documentation
- Quickstart
- Migrate from v1 to v2
- Usage scenarios
- Manual setup
- Agent permissions
- CLI guide
- MCP vs CLI
- Troubleshooting
- BridgeClient API
- WebMCP website tools
- Development and Make tasks
Privacy
The extension and native host communicate on the browser machine, and local clients connect to that daemon by default. If you explicitly configure an authenticated remote destination, bridge results can travel over your user-provided SSH tunnel or network route to the selected client. Browser Bridge does not operate a Browser Bridge cloud service, and raw remote TCP is not presented as encrypted.
Your connected agent or IDE may still forward tool calls or tool results to remote services under that product's own settings and privacy policy. See PRIVACY.md for the Browser Bridge policy.
Responsible Use
Browser Bridge is intended for local development, debugging, and testing of web resources you own, control, or are explicitly authorized to test. Do not use it for web scraping, unauthorized data collection, or impersonating or acting as another user. You are responsible for the agents you connect, the actions they perform, and compliance with applicable laws, permissions, website terms, and third-party rights. See the Responsible Use Agreement.
License
MIT. See LICENSE.
Browser Bridge MCP questions
How do I add Browser Bridge MCP to Claude Code?
Run claude mcp add browser-bridge -- npx -y @browserbridge/bbx in your terminal. Add --scope user to make it available in every project.
How do I add Browser Bridge MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Which AI agents are supported?
It supports a wide range of agents including Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Windsurf, Cline, Goose, and OpenHands.
Does it work with sandboxed browsers like Chromium on Ubuntu?
If native messaging stays disconnected on sandboxed versions like Snap or Flatpak, you should use a non-sandboxed browser like Google Chrome, Brave, or Edge.