Browser Bridge
Allows AI agents to inspect and interact with live Brave browser tabs using the user's existing signed-in sessions and cookies, with per-tab read-only or read-write access, screenshots, and controlled browser interactions.
Allows AI agents to inspect and interact with live Firefox tabs using the user's existing signed-in sessions and cookies, with per-tab read-only or read-write access, screenshots, and controlled browser interactions.
Allows AI agents to inspect and interact with live Google Chrome tabs using the user's existing signed-in sessions and cookies, with per-tab read-only or read-write access, screenshots, and controlled browser interactions.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
English · 简体中文 · 1-Prompt Install · Usage Guide · Feature Deep Dive · MCP Client Setup · Python SDK · Wiki
Browser Bridge lets local AI coding agents (GitHub Copilot, Claude Desktop / Claude Code, Cursor, Windsurf, Cline, or any MCP client) and local Python scripts safely inspect and act inside your own live Edge, Chrome, Brave, or Firefox tabs — using the accounts, SSO sessions, cookies, and browser extensions you already have open.
Unlike headless browser drivers (Playwright, Selenium, Puppeteer) or containerized cloud browsers, Browser Bridge never launches an isolated profile, never exports cookies, and opens zero TCP or WebSocket ports. Every tab stays private until you explicitly share it.
Why Browser Bridge?
Capability | Headless Drivers (Playwright / CDP Port) | Browser Bridge |
Signed-in SSO & corporate sessions | Loses session or requires fragile profile cloning | Works directly in your live signed-in browser |
Network attack surface | Localhost debugging port reachable by local processes/pages | 0 TCP ports — OS user-isolated Named Pipes / |
Tab privacy boundary | Exposes the entire browser context | Opt-in per tab ( |
Repeat-visit speed on complex sites | Static timeouts & repeated failures | Adaptive |
Native W3C WebMCP support | None | Discovers & invokes |
Host footprint | Hundreds of MBs of browser binaries + Node/Python drivers | ~1.5 MB standalone Rust binary + 0-dependency Python SDK |
Related MCP server: byob
Quickstart — Install in One Prompt (Out of the Box)
1. Install the Host & Register MCP
Method A (Recommended): Paste One Prompt into Your AI Coding Agent
Copy and paste this single prompt into GitHub Copilot (VS Code or CLI), Claude Code, Cursor, Windsurf, Cline, or Codex — no Rust, Cargo, or Node.js required:
Install and configure Browser Bridge by following https://raw.githubusercontent.com/dcluomax/browser-bridge/main/docs/INSTALL.md — download and SHA-256-verify the prebuilt release for my OS/CPU, register the native host and my AI client MCP config, verify with `BrowserBridge status`, and print the exact extension folder path to load in my browser.Want read-only inspection or the Python SDK too? Append "enable read-only MCP mode" or "also install the Python SDK" to the prompt above.
Downloads SHA-256-verified prebuilt binaries (windows-x64, windows-arm64, macos-arm64, macos-x64, linux-x64) + unpacked extensions from GitHub Releases and auto-configures installed MCP clients:
Windows (PowerShell):
irm https://raw.githubusercontent.com/dcluomax/browser-bridge/main/scripts/bootstrap.ps1 | iexmacOS / Linux:
curl -fsSL https://raw.githubusercontent.com/dcluomax/browser-bridge/main/scripts/bootstrap.sh | bashWindows (PowerShell):
git clone https://github.com/dcluomax/browser-bridge.git
cd browser-bridge
.\scripts\install.ps1 -RegisterAllMcp -InstallPythonSdkmacOS / Linux:
git clone https://github.com/dcluomax/browser-bridge.git
cd browser-bridge
./scripts/install.sh --register-all --install-pythonPrefer registering a single MCP client? Pass
-RegisterCopilotMcp,-RegisterClaudeMcp, or-RegisterCursorMcp(or--register-copilot,--register-claude,--register-cursoron macOS/Linux). Add-ReadOnlyMcp/--read-onlyto enforce host-level read-only inspection.
2. Load the Browser Extension (Once per Profile)
The installer copies built extensions to a stable per-user directory so rebuilding or pulling repository updates never breaks your browser:
Browser | Navigation | Folder / Manifest to Select |
Microsoft Edge |
| Windows: |
Google Chrome / Brave |
| Windows: |
Mozilla Firefox |
| Windows: |
Verify that the native host is registered and connected:
# Windows
"%LOCALAPPDATA%\BrowserBridge\app\BrowserBridge.exe" status
# macOS / Linux
~/.browser-bridge/app/BrowserBridge statusWhen connected, the Browser Bridge toolbar icon displays a green status dot.
3. Share a Tab & Prompt Your Agent
Open any web page in your browser and click the Browser Bridge toolbar icon (or right-click anywhere on the page → Browser Bridge).
Share the tab in
Read-Only(safe inspection & screenshots only) orRead-Write(full interaction) mode.Click Copy Prompt to paste a single-line tab handle into any AI agent, or simply ask your MCP-connected assistant:
"Inspect my shared browser tab, summarize the failing CI logs, and tell me the root cause."
Architecture & Security Boundary
Cross-Browser Extension (
extension/) — TypeScript + React 19 + Astryx UI bundled for Chromium (Manifest V3 service worker) and Firefox (Manifest V2 persistent background page). Enforces per-tab grants, origin-verified reload persistence, exclusive session leases, password/token redaction, and background screenshot capture.Standalone Rust Host & MCP Server (
rust/) — A single ~1.5 MB native binary (BrowserBridge) with zero runtime dependencies:Launched automatically by Edge, Chrome, Chromium, or Firefox via browser Native Messaging (
io.github.dcluomax.browser_bridge).Exposes each browser profile on a current-user-only Windows Named Pipe (
\\.\pipe\browser-bridge.<SID>.<browser>.<instance>) or0700/0600Unix Domain Socket.Runs as an MCP server (
BrowserBridge mcp), JSON-line stdio RPC bridge (BrowserBridge rpc), or direct CLI (status,screenshot,routines,mcp-mode).
Zero-Dependency Python SDK (
python/) — Pure Python (>=3.10) speaking directly over the Named Pipe / Unix Socket (~1.1 msmedian round-trip, zero intermediate subprocesses), offering Playwright-style chained locators,page.request(in-tab authenticated fetch),browser.request(anonymous host HTTP), andbrowser.smart_fetch(adaptive WAF fallback).
Toolbar Popup & 3-Layer Permission Controls
Browser Bridge enforces three independent safety layers before any mutation can touch a tab:
MCP Server Flag (
--read-only/BROWSER_BRIDGE_READ_ONLY=1) — Strips mutating tools fromtools/listand blocks mutating RPC calls at the host boundary.Popup Global Read-Only Lock — Instant per-profile kill switch in the toolbar popup that freezes all clicks, typing, navigation, and tab creation across every connected agent.
Per-Tab Access Mode (
[read-only]vs[read-write]) — Share sensitive dashboards (Grafana, Azure/AWS consoles, production logs) asRead-Onlywhile grantingRead-Writeonly to local dev apps or sandboxes. Promote or downgrade anytime with one click.
Additional popup capabilities:
Trusted Input (
chrome.debugger) — Enabled by default on Chromium so clicks, drags, and shortcuts carry genuine user activation; automatically falls back to DOM events on Firefox or when detached.Background
[Agent]Tab Grouping — Agent-opened tabs open in the background (active: false) inside a collapsed[Agent]group without stealing window focus.Multi-Language UI — Built-in English (
en), Simplified Chinese (zh_CN), Traditional Chinese (zh_TW), and Japanese (ja) with dark/light theme toggle.
Adaptive Site Memory, Fast Routines & WebMCP
Real-world web apps stall window.onload with analytics beacons, re-render during SPA hydration, cover buttons with cookie banners, or block plain HTTP with 403 WAF rules. Browser Bridge learns per-domain adaptations automatically:
Error-Driven
SiteLearner— Observesloadtimeouts → switches future visits todomcontentloaded; detects hydrationstale_refraces → applies tunedhydrationSettleMs; recordsError -> Recovery Action -> Retry Successtriads for overlay blockers; remembers403WAF endpoints sosmart_fetchroutes through the authenticated browser tab.Executable Site Memory Routines — Parameterized multi-step workflows stored locally in
routines/<domain>.json(includes built-inapp.diagrams.netroutines such asread_diagram_xml,write_diagram_xml, andinsert_shape). Agents inspect routines viabrowser_routine_list, execute in 1 call viabrowser_routine_run, and save newly discovered workflows viabrowser_routine_save.Native W3C WebMCP (
document.modelContext) — Automatically discovers imperative tools registered viadocument.modelContext.registerTool(...)/navigator.modelContext.registerTool(...)and declarative<form toolname="...">actions across Edge, Chrome, and Firefox (browser_webmcp_list/browser_webmcp_call).
MCP Tool Catalog (26 Tools + Resources + Prompts)
Category | Tools | Description |
Discovery & Tabs |
| Inspect connected browsers/profiles ( |
Navigation |
| Navigate with learned wait strategies ( |
Page Reading |
| Accessibility outline with stable refs ( |
User Actions |
| Ref- or locator-targeted interactions with covered-element guards, modifier keys, HTML5/pointer drag-and-drop, and verified checkbox toggling |
Files, Dialogs & Waits |
| Chunked file input uploads, |
Site Memory & WebMCP |
| Per-domain learned performance profiles, pitfall logs, 1-call multi-step routines, and W3C WebMCP page tool discovery/invocation |
Optional Script Eval |
| Disabled by default; requires both |
MCP Resources (bridge://guide, bridge://status, bridge://tabs, bridge://routines) and Prompts (inspect-shared-tab, act-in-shared-tab) are also exposed out of the box.
Local Python SDK (Zero Dependencies)
Control your live browser from standard Python without Playwright, WebDriver binaries, or browser restarts:
from browser_bridge import BrowserBridge
with BrowserBridge() as browser:
# Open an agent-owned background tab (auto-closed on context exit; never closes your browser)
page = browser.new_page("https://example.com")
print(page.title(), page.locator("h1").first.inner_text())
# Attach to a tab you shared from the toolbar popup (released, never closed, on exit)
# shared = browser.page(42)
# Adaptive fetch: fast host HTTP first, transparent in-tab session fallback on 403 WAF
api_resp = browser.smart_fetch("https://example.com/", page=page)
print("Status:", api_resp.status)
page.screenshot("example-full.png", full_page=True)Read the complete Python SDK & Direct IPC Reference and JSON-Line Wire Protocol Spec.
Documentation & Repository Map
Document | Contents |
AI Agent 1-Prompt installation playbook (zero-build SHA-256 prebuilt release setup) | |
Machine-readable repository index for LLM coding agents | |
Complete installation, onboarding, popup controls, CLI subcommands, and daily workflows | |
Deep dive into all 26 MCP tools, | |
Copy-paste setup for GitHub Copilot, VS Code, Claude Desktop, Claude Code, Cursor, Windsurf, and Cline | |
Zero-port IPC isolation, 3-layer ACLs, credential redaction, and human handoff invariants | |
Direct Named Pipe / Unix Socket & | |
Full Python SDK guide (locators, waits, | |
Multi-page GitHub Wiki source mirrored automatically to the repository Wiki |
browser-bridge/
├── extension/ # Cross-browser TypeScript + React 19 + Astryx extension (Chromium MV3 & Firefox MV2)
├── rust/
│ └── crates/
│ ├── bridge-core/ # Named Pipe / Unix Socket IPC, Native Messaging, HTTP, SiteLearner & Routines
│ └── browser-bridge/ # Standalone Native Host, MCP server, RPC server, installer & CLI
├── python/ # Zero-dependency Python 3.10+ SDK (`browser_bridge`)
├── e2e/ # Real-browser MCP + Python SDK end-to-end test harness & HTML fixtures
├── scripts/ # Turnkey cross-platform install, uninstall & sanitization check scripts
├── docs/ # Illustrated guides, architecture specs & vector SVG diagrams
└── wiki/ # Full GitHub Wiki project pagesDevelopment & Verification
# Run sanitization audit + TypeScript check + Extension unit tests + Rust workspace tests
npm test
# Run zero-dependency Python SDK unit tests
python -m unittest discover -s python/tests -v
# Build extension bundles (dist/chromium, dist/firefox) + Rust release binary
npm run build
# Package distributable extension archives (.zip and .xpi)
npm run package:extension
# Run full real-browser E2E suite (36 MCP checks + Python integration suite)
npm run e2e:edge # or: npm run e2e:chrome / npm run e2e:firefoxSee CONTRIBUTING.md for development setup, coding conventions, and pull request guidelines, and SECURITY.md for vulnerability reporting.
License
Released under the MIT License · Copyright © dcluomax.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Browz hosted MCP (free public beta): let an AI app drive your own Browz browser profiles from anywhere. Connect https://mcp.gobrowz.com/mcp and sign in with your Browz account (OAuth) or an agent token. Each call is relayed to the Browz app on your computer, which must be online with Remote control on and have a hardware security chip (Mac Secure Enclave or TPM 2.0). 17 tools: profiles, tabs, navigate, snapshot, act, wait, screenshot. Cookies, downloads and stored sign-ins stay on your computer.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceA local MCP server that lets AI coding tools drive the user's own already-logged-in Chrome — clicking, typing, reading pages, taking screenshots, and inspecting cookies, network, and console through the extension rather than a debug port. All communication stays on the machine, with agent-opened tabs grouped and kept out of focus.1 npmISC
- AlicenseNot gradedqualityAmaintenanceA local MCP server that lets AI coding assistants drive the user's own already-signed-in Chrome, so agents can read logged-in pages, click, fill forms, navigate, screenshot, inspect network traffic and storage, and run multi-step browser workflows without a separate headless browser or remote debugging port. All communication stays on the user's machine and agent-opened tabs are grouped so they never steal focus.1 npmISC
- AlicenseNot gradedqualityAmaintenanceA local MCP server that lets AI coding tools drive the user's actual, already-logged-in Chrome browser — snapshotting pages, clicking, typing, navigating, reading content, taking screenshots, and inspecting cookies, network traffic, and console output. Browser automation happens through a Chrome extension using Native Messaging, so no remote-debugging port is exposed and all communication stays on the local machine.1 npmISC
- AlicenseNot gradedqualityAmaintenanceA local MCP server that lets AI coding tools drive the real Chrome browser you already have open, so agents can read logged-in pages, click, fill forms, take screenshots, and inspect tabs, cookies, and network traffic. All communication stays on your machine, with no debugging port or manual cookie copying required.1 npmISC