Better Browser

Better Browser MCP

Multi-agent local browser automation. Drop-in upgrade of @browsermcp/mcp with configurable ports, per-agent WebSocket paths, and no more port-9009 fighting between agents.
Issues • Multi-agent setup • Why this exists

---

What's different from @browsermcp/mcp?

	@browsermcp/[email protected]	@nbiish/[email protected]
Port collision behavior	Silently kills the other process (lsof -ti:9009 | xargs kill -9)	Hard error, process exits with clear message
Multiple agents on one machine	Each MCP process fights for the same port	Each agent runs on its own port — no fighting
Agent identification	None	BROWSER_MCP_AGENT_ID env var, exposed in WS path
WebSocket path	/ (any)	/ws/<agent-id>
Auth	None	Optional BROWSER_MCP_AUTH_TOKEN for shared-secret handshake
Recursion bug in server.close()	Yes (crashes on every reconnect)	Fixed — explicit __origClose binding
Workspace monorepo deps	Required @repo/* for build	Self-contained, builds from a single npm install
Bind address	Any	Defaults to 127.0.0.1 (localhost-only by default)

All browser_navigate, browser_click, browser_snapshot, etc. tool names are identical to upstream — no client changes needed on the LLM side.

Agent self-service: agents can onboard themselves with zero MCP settings changes — see .agents/skills/bbmcp/SKILL.md and run node scripts/bbmcp-connect.mjs --agent <id> --port 9223.

---

Quick start

Single agent (one process, one browser)

npx @nbiish/betterbrowsermcp@latest
# or, from this checkout:
npm install
npm run build
node dist/index.js

The server binds port 9009, WebSocket at ws://127.0.0.1:9009/ws/default. The browser extension connects there.

Multi-agent (one process per agent, all sharing one browser)

# Agent "hermes" on port 9009
BROWSER_MCP_AGENT_ID=hermes BROWSER_MCP_PORT=9009 \
  npx @nbiish/betterbrowsermcp@latest &

# Agent "omp" on port 9010
BROWSER_MCP_AGENT_ID=omp BROWSER_MCP_PORT=9010 \
  npx @nbiish/betterbrowsermcp@latest &

# Agent "codex" on port 9011
BROWSER_MCP_AGENT_ID=codex BROWSER_MCP_PORT=9011 \
  npx @nbiish/betterbrowsermcp@latest &

Each process binds its own port. They never fight. The browser extension connects to all three WebSocket endpoints and lets the user bind each tab to a specific agent.

---

Multi-agent setup

The user-facing flow:

1. Start one MCP process per agent (different ports, different BROWSER_MCP_AGENT_ID)
2. Configure the browser extension with the list of WS endpoints to monitor (e.g. ws://127.0.0.1:9009/ws/hermes, ws://127.0.0.1:9010/ws/omp)
3. For each browser tab, the user clicks the extension icon and picks which agent controls it. The binding persists for that tab until changed or disconnected.
4. Different tabs can be bound to different agents — the same browser serves many agents concurrently.

The MCP processes don't know about each other. The browser extension is the multiplexer that knows which agent controls which tab.

Multi-tab per agent (v0.3.0+)

A single agent can have multiple browser tabs bound to it, so a Hermes-style agent can drive Stripe in one tab and the inference provider dashboard in another, all from one MCP process. The LLM picks which tab to act on.

Tools for multi-tab work

Tool	Purpose
browser_list_tabs	List all bound tabs with their tabId, label, URL, active marker
browser_open_tab	Open a new tab and bind it (optional url, label)
browser_close_tab	Close a bound tab
browser_rename_tab	Set a human-readable label on a tab
browser_set_active_tab	Switch which tab unspecific tool calls route to

Every existing browser_* tool also accepts an optional tabId parameter. If omitted, the call routes to the agent's active tab.

Example: driving Stripe + OpenAI console from one agent

LLM: "I need to set up a Stripe webhook. Let me check what tabs are bound."
  -> browser_list_tabs
  -> response:
      tabId=12345  label="Stripe dashboard"  url=https://dashboard.stripe.com
      tabId=67890  label="OpenAI console"    url=https://platform.openai.com  ← ACTIVE

LLM: "I should focus on Stripe first."
  -> browser_set_active_tab(tabId=12345)

LLM: "Let me take a snapshot of the Stripe dashboard."
  -> browser_snapshot
  -> response: full ARIA tree, refs like e1, e2, ... for the Stripe dashboard

LLM: "Click 'Webhooks'."
  -> browser_click(element="Webhooks link in sidebar", ref="e14")

LLM: "Now switch to the OpenAI console and grab the API key."
  -> browser_set_active_tab(tabId=67890)
  -> browser_snapshot
  -> browser_click(element="API keys", ref="e7")

Multi-tab vs. multi-agent

• Multi-agent = multiple MCP processes, one per agent (e.g. Hermes + OMP + Codex), each with its own port and WS endpoint
• Multi-tab = within ONE agent's MCP process, multiple browser tabs are bound, with per-tab labels and an "active" tab for unspecific calls

The two compose: spawn N MCP processes (multi-agent), each connects to the same browser with M tabs (multi-tab), and the LLM picks which (agent, tab) pair to drive for each tool call.

Parallel-tabs tools (v0.9.0+)

Tool	Purpose
browser_bind_tab	Adopt an existing tab into the agent's bound set (no open, no focus)
browser_unbind_tab	Release a tab without closing it
browser_acquire_tab	Advisory per-tab lock (ttlMs, default 300000; returns lockId or BUSY + holder)
browser_release_tab	Release the advisory lock
browser_wait_for_content	Resolve when the tab's content script answers a readiness ping (default 10s)
browser_poll_events	Drain buffered tab_removed/tab_updated/binding_changed events (also appended to list_tabs/snapshot output)

browser_open_tab gains makeActive (default false) — background tabs by default; pass true only when you actually want focus. When driving multiple tabs, pass explicit tabId on every call.

Hub mode (v0.9.0+)

One process can now serve MANY agents:

BROWSER_MCP_HUB=true BROWSER_MCP_PORT=9009 node dist/index.js
# extension connects to ws://localhost:9009/ws/<anyAgentId>
# MCP clients POST JSON-RPC to http://localhost:9009/mcp/<agentId>
curl http://localhost:9009/
# {"mode":"hub",...,"agents":[{"agentId":"hermes","connected":true,"boundTabs":2}, ...]}

• Any /ws/<agentId> is accepted; the per-agent Context is lazily created on first connect. The auth handshake ({type:"auth", token}) is enforced per Context, exactly like single-agent mode.
• MCP is also mounted over Streamable HTTP on the same HTTP server: POST /mcp/<agentId> (stateless JSON-RPC; each request dispatches against that agent's Context).
• Security: on a non-loopback BROWSER_MCP_BIND, /mcp requires Authorization: Bearer $BROWSER_MCP_AUTH_TOKEN (401 otherwise, fail closed — including when no token is configured).
• stdio is disabled in hub mode; the process is a daemon (SIGINT/SIGTERM to stop). Single-agent mode (default) is unchanged and byte-compatible.

Environment variables

Var	Default	Description
BROWSER_MCP_AGENT_ID	default	Agent identifier. Used in the WS path (/ws/<id>) so the extension can route tab bindings.
BROWSER_MCP_PORT	9009	WebSocket port to bind. Use different ports for different agents.
BROWSER_MCP_BIND	localhost	Bind address. Loopback only by default — a non-loopback value requires BROWSER_MCP_AUTH_TOKEN (MCP-over-HTTP returns 401 without it; fail closed).
BROWSER_MCP_AUTH_TOKEN	(unset)	Optional shared secret. If set, the extension must send {type:"auth", token:"..."} as its first WS message, else the connection is closed with 4401. Required for /mcp when bound non-loopback.
BROWSER_MCP_WS_PATH_PREFIX	/ws	Path prefix for the WS endpoint. Default /ws means the agent's endpoint is at /ws/<agentId>.
BROWSER_MCP_HUB	false	Hub mode (v0.9.0+). true = one process serves many agents (see Hub mode).
BROWSER_MCP_PQC_SECRETS_BIN	(auto)	Override for the pqc-secrets binary path. Resolution order: this env → which pqc-secrets → ~/.local/bin → /usr/local/bin → legacy ~/code/ainish-coder/bin. The winner is logged to stderr once.

---

Browser extension

Better Browser MCP is server-side only. The browser extension that talks to it is a fork of the upstream @browsermcp extension with two changes:

1. Configurable WS endpoints — instead of a hard-coded ws://localhost:9009, the extension popup lets the user add/remove WS endpoints to monitor. Each is identified by agent ID.
2. Per-tab agent binding — when the user clicks the extension icon on a tab, they see a list of currently-connected agents (i.e. which WS endpoints are open and which tabs they're bound to). Picking one binds the current tab to that agent until changed or disconnected.

The forked extension is built separately and lives in nbiish/betterbrowsermcp-extension (forthcoming).

Until that's ready, you can patch the upstream extension to:

• Read WS endpoints from a config (instead of hardcoded localhost:9009)
• Show a tab-binding UI in the popup

---

Why this exists

The original @browsermcp/[email protected] has two design flaws that cause constant pain in multi-agent setups:

1. killProcessOnPort on startup

Every time the server starts, it runs lsof -ti:9009 | xargs kill -9 before binding. This was meant to free the port from a stale previous instance, but in a multi-agent world it means every agent's MCP process murders every other agent's MCP process on startup. The result: keepalive failures every ~90s, ClosedResourceError on every tool call, weeks of debugging.

Better Browser MCP removed this. Port collision is now a hard error with a clear message: which port, which env var to change, and how to investigate (lsof -ti:<port> | xargs ps -p).

2. Single WebSocket per process, no agent awareness

The upstream server has a single Context object holding the one WebSocket. There's no concept of "I'm agent X, please route my tool calls to my tab". The result: in a multi-agent setup, only one agent can have a tab connected at a time, and the others fail with "No connection to browser extension".

Better Browser MCP gives each MCP process an explicit BROWSER_MCP_AGENT_ID. The WebSocket is served at /ws/<agentId>. The browser extension binds tabs to specific agent IDs. Each agent gets its own dedicated tab.

3. Recursion bug in server.close()

The upstream dist/index.js has server.close = async () => { await server.close(); ... } — it calls itself recursively, blowing the stack on every reconnect with RangeError: Maximum call stack size exceeded.

Better Browser MCP fixes this with explicit __origClose binding.

---

Development

# Install deps
npm install

# Typecheck
npm run typecheck

# Build (ESM via tsup)
npm run build

# Test (manual)
BROWSER_MCP_AGENT_ID=hermes BROWSER_MCP_PORT=9099 \
  npm start
# in another shell:
curl http://127.0.0.1:9099/
# {"name":"Better Browser MCP (agent: hermes)","bind":"127.0.0.1","port":9099, ...}

Project structure

src/
  config.ts           env var resolution, WS URL helpers, hub/loopback config
  context.ts          per-agent Context (one WebSocket = one agent's tabs)
  registry.ts         AgentRegistry (agentId → Context, hub mode)
  events.ts           bounded per-agent tab-event ring buffer (cap 200)
  messaging.ts        WS message protocol (inlined from upstream)
  server.ts           MCP server, tool routing (shared by both transports)
  toolset.ts          the full tool list (stdio + HTTP MCP)
  http.ts             MCP over Streamable HTTP at /mcp(/<agentId>)
  tools/              tool implementations (navigate, click, etc.)
  utils.ts            helpers (wait, port check)
  ws.ts               WebSocket server + hub routing + health JSON
  index.ts            entry point (single-agent stdio / hub daemon)
  types.ts            Zod schemas (inlined from upstream's monorepo)

Patched bugs from upstream

• server.close() recursion (src/server.ts: in createServerWithTools): capture originalClose before override
• killProcessOnPort murder (removed entirely — src/utils.ts: only isPortInUse remains)
• Workspace monorepo deps (inlined into single-package repo)

---

Credits

Better Browser MCP is a fork of browsermcp/mcp with the multi-agent fixes needed for the Hermes + OMP + Codex multi-agent workflow. Originally adapted from Microsoft's Playwright MCP server.

By Nbiish — first repo, but probably not the last.