browser-mcp-bridge

A desktop tray application that bridges the Browser MCP stdio server to Streamable HTTP, so HTTP-based MCP clients — like Open WebUI or anything else on your network — can drive your actual, logged-in browser.

┌──────────────┐   HTTP + Bearer    ┌──────────────────────────────┐
│ Open WebUI   │ ─────────────────► │ browser-mcp-bridge (tray)   │
│ (homelab)    │   :8020/mcp        │  ├─ stdio ─► @browsermcp/mcp│
└──────────────┘                    │  └────────► Browser ext.    │
                                    │              └─► your Chrome│
                                    └─────────────────────────────┘

Why?

Browser MCP is a stdio MCP server that pairs with a Chrome extension and automates your real browser — with your cookies, your sessions, your login state. Great idea, but stdio means the MCP client has to run on the same machine. If your LLM frontend lives on a homelab server (Open WebUI, etc.), it can't reach it.

browser-mcp-bridge closes that gap:

• 🌉 stdio ⇄ HTTP — exposes @browsermcp/mcp as a Streamable HTTP endpoint

• 🔐 Bearer token auth — every /mcp request must carry your token

• 🌐 CIDR allowlist — restrict which source IPs may connect (defaults to localhost only)

• 🖥️ System tray app — live status icon, settings GUI, log viewer

• 🩺 Honest status light — 3-state tray icon: green (browser connected), orange (bridge up, browser extension disconnected), red (subprocess down)

• 💓 Heartbeat — polls the browser with a read-only browser_snapshot every 10s (configurable) so the status light reflects reality, not stale state

• 🛟 Crash-resilient — auto-restarts the npx subprocess with backoff; survives browser restarts

• 🩹 Health endpoint — GET /health (no auth) for monitoring from anywhere on the LAN

Related MCP server: Echo

Security model

This tool gives an LLM full control of your real browser session. Please read this.

Recommended setup: LAN-only deployment (homelab), token in Open WebUI, CIDR limited to your subnet. Do not expose this to the internet without putting a TLS-terminating reverse proxy in front of it.

The token is stored in ~/.config/browser-mcp-bridge/config.json (chmod 600).

Requirements

• Python 3.10+

• Node.js (for npx, which fetches @browsermcp/mcp)

• Qt6/PySide6 (tray + GUI; headless mode works without it)

• Browser MCP Chrome extension

Install

git clone https://github.com/NopeNix/browser-mcp-bridge.git
cd browser-mcp-bridge
python3 -m venv venv
venv/bin/pip install -r requirements.txt

Usage

GUI (tray) mode

venv/bin/python bridge.py

Tray icon appears in your system tray (green → orange → red depending on state). Right-click for: Show window · Restart subprocess · Quit. The settings dialog lets you set port, bearer token (show/hide), CIDR allowlist, and heartbeat interval.

Headless mode

venv/bin/python bridge.py --headless

Desktop integration (KDE/Plasma)

mkdir -p ~/.local/share/applications ~/.config/autostart
cp packaging/browser-mcp-bridge.desktop ~/.local/share/applications/
cp packaging/browser-mcp-bridge.desktop ~/.config/autostart/

systemd user service (optional, headless servers)

cp packaging/browser-mcp-bridge.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now browser-mcp-bridge

⚠️ Run either the GUI or the headless service — they both bind the same port and spawn their own subprocess, so running both will conflict.

Connecting Open WebUI

1. Admin Panel → Settings → Tools → add MCP server: http://<bridge-host>:8020/mcp

2. Auth: header Authorization = Bearer <your-token> (find it in the tray settings dialog)

3. In Chrome, click the Browser MCP extension icon → Connect

4. Tools (browser_navigate, browser_click, …) appear in the model's toolset

Configuration

~/.config/browser-mcp-bridge/config.json:

{
  "port": 8020,
  "token": "auto-generated-on-first-run",
  "allowed_cidrs": ["127.0.0.1/32", "::1/128"],
  "heartbeat_interval": 10
}

• allowed_cidrs — list of IPv4/IPv6 CIDRs permitted to call /mcp

• heartbeat_interval — seconds between read-only browser probes (status light refresh)

Endpoints

Troubleshooting

Architecture

bridge.py          single-file app: HTTP server, subprocess manager, tray GUI
packaging/         .desktop launcher, systemd unit

The HTTP server is stdlib http.server (no aiohttp/flask dep for the server path); PySide6 is only needed for the tray/GUI. Each HTTP request is translated 1:1 into a JSON-RPC message over the subprocess's stdio, and responses are matched back by request id.

License

MIT — see LICENSE.