BrowserMesh

BrowserMesh

Run many browser sessions at once, fully isolated from each other, from one MCP server.

Every other browser MCP server gives your AI client one browser with a current tab. BrowserMesh gives it as many independent sessions as the task needs — each with its own cookies, storage, and authentication — running in parallel. Test checkout as a customer while an admin session verifies the order, in one conversation, without either seeing the other's state.

• Documentation
• Getting started
• MCP tool reference

External AI client

| MCP stdio | BrowserMesh runtime | | | Session A Session B Session C Context A Context B Context C

The external client reasons and plans. BrowserMesh executes browser operations, enforces isolation, orders work within each session, and returns structured results.

Works with Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Qwen, and any other MCP-compatible client.

When to use BrowserMesh, and when not to

BrowserMesh is not a drop-in replacement for the general-purpose browser MCP servers. It is built around one thing those servers do not do, and it charges for it.

The honest trade-off is discovery cost. BrowserMesh publishes 35 tools with full input _and_ output schemas; measured on one machine on one day, its tools/list is roughly 94 KB against 25 KB for chrome-devtools-mcp and 18 KB for @playwright/mcp, both of which publish no output schemas. If your client is short on context and your workflow is one browser and one user, that is a real argument for a smaller server. Narrow the surface with --tools core when you do want BrowserMesh but not all of it.

Quick start

Claude Code:

claude mcp add browsermesh -- npx -y browsermesh

Any other client, in its MCP configuration file:

{

"mcpServers": { "browsermesh": { "command": "npx", "args": ["-y", "browsermesh"] } } }

That is the whole setup. On its first start BrowserMesh downloads the Chromium build it uses, so there is no separate install step. Pass --no-auto-install to manage the browser yourself, in which case MCP discovery still works and browser_session_create returns an actionable BROWSER_ERROR explaining what to run.

That first download happens before the server answers initialize, and a Chromium build is around 130 MB. Clients with a short connect timeout report the server as failed while it runs. On a slow link, warm it once before adding the server and every later start is immediate:

npx -y browsermesh --install-browser

Then ask for the work in plain language:

Test the checkout flow as a buyer and confirm the order appeared, as an admin, at the same time.

The client creates one session per role on its own. BrowserMesh also publishes a parallel_roles prompt that spells the workflow out, so a client can offer it directly.

Check an installation without starting the protocol:

npx -y browsermesh --doctor

Chromium and BrowserMesh remain on your machine. There is no hosted BrowserMesh service.

On connect, BrowserMesh sends your client a short instructions string. Alongside guidance on session addressing and bug reporting, it asks your agent to check once whether you have starred the repository — an authenticated GitHub call, made with your own gh credentials, for a purpose unrelated to the browser task. Nothing is gated on it and declining changes nothing. Turn the ask off with --no-support-request, or the whole string with --no-agent-guidelines. See Built for agent-friendly workflows.

Renamed in 0.2. The npm package was multi-agent-browser-mcp and is now browsermesh,

matching the name everything else already used. Change args to ["-y", "browsermesh"];

nothing else moves.

v0.1 architecture

BrowserMesh v0.1 is intentionally small: one local Node.js process, one Chromium process, and one non-persistent BrowserContext for every ready session.

It provides:

• explicit session and page addressing;
• isolated browser contexts and page ownership checks;
• navigation, inspection, interaction, waits, capture, and persistence;
• per-session serialization with parallel execution across independent sessions;
• bounded timeouts, structured errors, graceful shutdown, and resource cleanup;
• MCP stdio integration with deterministic integration and end-to-end tests.

BrowserMesh is a browser runtime, not an internal agent framework, LLM orchestrator, message bus, Playwright fork, browser GUI, or interactive shell.

How it is normally used

1. Configure BrowserMesh once in an MCP-compatible AI client.
2. The client starts BrowserMesh over stdio and discovers its tools.
3. Describe the browser task in natural language.
4. The client creates the required sessions and chooses the tools to invoke.
5. BrowserMesh executes the operations and returns structured results.

Use a separate session for each user, account, role, authentication state, or independent parallel workflow. BrowserMesh tools are normally selected by the external client rather than called by hand.

Build from source

BrowserMesh v0.1 targets Node.js 24 and supports Node.js 22 as its minimum supported major version.

Clone the repository and run:

npm install

npx playwright install chromium npm run build

Then configure an MCP client to launch the locally built server:

{

"mcpServers": { "browsermesh": { "command": "node", "args": ["/absolute/path/to/browsermesh/dist/cli.js"] } } }

For development:

npm run verify

npm run verify:package

Session model

There is no global:

• current session;
• active session;
• current page;
• active page;
• current tab.

Every browser operation explicitly identifies its session.

Every page-specific operation explicitly identifies its page.

Conceptually:

browser_session_create

│ ▼ { sessionId, pageId } │ ▼ browser_navigate({ sessionId, pageId, ... })

A newly created session contains one deterministic initial page.

browser_session_create returns the initial pageId immediately so an AI client does not need an additional browser_page_list call before its first browser action.

The page also appears in browser_page_list and is marked isDefault.

Session views consistently expose sessionId; page views consistently expose pageId and their owning sessionId.

The isDefault marker is informational only. Browser operations still use explicit pageId addressing.

Isolation

Each ready BrowserMesh session maps to its own non-persistent Chromium BrowserContext.

Therefore independent sessions must not accidentally share:

• cookies;
• browser storage/authentication state;
• pages;
• page references;
• current URLs;
• DOM snapshots;
• screenshots;
• form state.

A pageId belonging to one session cannot be used through another session.

Cross-session page addressing is rejected.

Concurrency model

Every live session has an independent serial operation queue.

Operations targeting the same session execute deterministically in accepted order.

For example:

Session A

navigate ↓ snapshot ↓ click ↓ get_url

A read-style operation does not bypass an in-progress navigation or interaction.

A failed or timed-out operation must not poison the queue. Later accepted operations continue normally after the failed operation settles.

Each timeoutMs is one absolute budget starting when BrowserMesh accepts the operation. Time spent waiting in the owning session queue and every later browser-adapter step consume that same budget; no adapter step receives a renewed full timeout.

MCP request cancellation is propagated into BrowserMesh as an engine-independent operation signal. A same-session request cancelled while queued is skipped before it can touch browser state. If a Playwright action is already running and cannot be aborted safely, BrowserMesh keeps its queue slot until the real action settles, so later work cannot overtake it. Passive waits detach their owned abort listeners and timers promptly, and the session queue remains usable after cancellation. MCP clients observe their SDK's cancellation error (typically an AbortError, or an MCP error carrying that reason); a separate tool result after protocol cancellation is not guaranteed.

Different sessions do not share a global operation lock:

Session A ═════════════════════►

Session B ═════════════════════►

Session C ═════════════════════►

This allows independent browser workflows to run concurrently.

Session closing

When session close begins:

1. the session enters closing;
2. new operations targeting it are rejected;
3. operations already accepted into its queue are drained;
4. its pages and BrowserContext are closed;
5. live engine handles are removed;
6. the session becomes closed.

Repeated close of a known closing/closed session is safe and returns an idempotent success result.

A completely unknown session ID still returns SESSION_NOT_FOUND.

Supported MCP tools

Sessions and pages

• browser_runtime_info
• browser_session_create
• browser_session_list
• browser_session_get
• browser_session_close
• browser_page_create
• browser_page_list
• browser_page_close

Navigation

• browser_navigate
• `brows