BrowserMesh is a local, open-source browser runtime for external AI clients.
It lets Claude Code, Codex, Cursor, Qwen, and other MCP-compatible clients control multiple isolated browser sessions through one MCP server.
BrowserMesh replaces an implicit "current page" model with explicit sessionId
pageId
addressing.
Each session runs in its own Chromium BrowserContext
, so independent users, accounts, roles, and authentication states do not accidentally share cookies, storage, pages, or browser state.
User
↓
External AI client
↓ MCP
BrowserMesh
├── Session buyer → isolated BrowserContext
├── Session seller → isolated BrowserContext
└── Session admin → isolated BrowserContext
BrowserMesh does not perform LLM reasoning.
The external MCP client decides what to do. BrowserMesh provides deterministic browser capabilities.
A normal user configures BrowserMesh once and then asks their AI client things like:
Test the checkout flow as a customer while simultaneously verifying the order from the admin account.
The AI client can discover BrowserMesh tools through MCP, create separate sessions for the required identities, operate them independently, and report the result.
BrowserMesh is not:
- an internal AI-agent framework;
- an LLM orchestrator;
- a message bus;
- a Playwright fork;
- a browser GUI;
- an interactive shell that users must operate manually.
Version 0.1 is intentionally small:
one Node.js process
│
▼
one Chromium process
│
├── BrowserContext A
├── BrowserContext B
├── BrowserContext C
└── ...
BrowserMesh v0.1 includes:
- explicit session/page addressing;
- isolated Chromium contexts;
- session/page lifecycle;
- browser navigation and interaction;
- semantic locators;
- per-session operation serialization;
- parallel execution across independent sessions;
- bounded operation timeouts;
- structured application errors;
- Playwright storage-state persistence;
- MCP stdio integration;
- deterministic local integration/e2e testing;
- graceful shutdown and resource cleanup.
Reasoning and workflow orchestration remain in the external MCP client.
You normally do not call BrowserMesh tools manually.
The intended flow is:
- Configure BrowserMesh once in your MCP-compatible AI client.
- The client starts BrowserMesh as an MCP stdio process.
- The client discovers BrowserMesh tools.
- You describe the browser task in natural language.
- The AI client chooses and invokes the appropriate BrowserMesh tools.
- BrowserMesh executes the browser operations and returns structured results.
For tasks involving multiple users, accounts, roles, or authentication states, the external AI client should create a separate BrowserMesh session for each identity.
Once the npm package is published, the expected MCP configuration will use the package executable directly.
Install the Playwright-managed Chromium build once before starting BrowserMesh. This command uses the exact Playwright version bundled with the selected BrowserMesh package:
npx -y multi-agent-browser-mcp --install-browser
Playwright browser binaries are versioned separately from the npm package and may need to be
installed again after a BrowserMesh/Playwright update. If Chromium is missing, BrowserMesh keeps
MCP discovery available and browser_session_create
returns an actionable BROWSER_ERROR
instead of terminating the stdio connection.
Example:
{
"mcpServers": {
"browsermesh": {
"command": "npx",
"args": ["-y", "multi-agent-browser-mcp"]
}
}
}
The exact configuration format depends on the MCP client.
BrowserMesh itself remains local: Chromium and BrowserMesh run on the user's machine.
No BrowserMesh cloud server is required for the open-source local mode.
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
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.
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.
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.
Different sessions do not share a global operation lock:
Session A ═════════════════════►
Session B ═════════════════════►
Session C ═════════════════════►
This allows independent browser workflows to run concurrently.
When session close begins:
- the session enters
closing
; - new operations targeting it are rejected;
- operations already accepted into its queue are drained;
- its pages and
BrowserContext
are closed; - live engine handles are removed;
- 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
.
browser_session_create
browser_session_list
browser_session_get
browser_session_close
browser_page_create
browser_page_list
browser_page_close
browser_navigate
browser_back
browser_forward
browser_reload
browser_get_url
browser_get_title
browser_snapshot
browser_visible_text
browser_click
browser_fill
browser_press
browser_select_option
browser_screenshot
Screenshots are returned as MCP image content instead of being written to a caller-controlled filesystem path.
browser_state_save
browser_state_list
browser_state_remove
browser_session_create
accepts an optional stateId
.
Without stateId
, it creates a fresh isolated context.
With stateId
, it initializes the new context using a previously saved BrowserMesh state.
Example conceptually:
browser_session_create({
name: "buyer",
stateId: "buyer-auth"
})
A session may have:
- an optional human-readable
name
; - optional string metadata.
For example an external AI client may label sessions:
role=buyer
role=seller
account=work
These values are neutral workflow labels only.
They do not create:
- internal Agent entities;
- ownership principals;
- permissions;
- mailboxes;
- message channels;
- LLM identities.
BrowserMesh tool descriptions are part of the product contract.
Descriptions must explain both what a tool does and when an AI client should use it.
For example, the description for browser_session_create
must make it clear that separate sessions should be used for:
- different users;
- different accounts;
- different roles;
- different authentication states;
- independent parallel browser workflows.
The goal is that a user can say:
Test this application as a buyer and an administrator.
without having to manually instruct the AI to call browser_session_create
twice.
Browser actions prefer semantic locator strategies.
Supported v0.1 strategies include:
- role;
- text;
- label;
- placeholder;
- test ID;
- CSS as an escape hatch.
Common interactive role values are supported by the v0.1 public contract.
Role names use exact accessible-name matching by default. Set exact: false
only when partial
matching is intentional. If a locator resolves to multiple elements, BrowserMesh returns
LOCATOR_AMBIGUOUS
and keeps the session usable.
Accessibility snapshots redact non-empty values from input[type="password"]
elements before any snapshot content crosses the MCP boundary.
BrowserMesh does not expose Playwright Locator
objects through its public API.
BrowserMesh stores local persistence data beneath:
.browsermesh/
by default.
Saved browser state may contain authentication credentials or equivalent sensitive browser state.
Therefore:
.browsermesh/
is ignored by Git;- saved state must not be committed;
- saved state must not be published;
- logs must not contain storage-state contents;
- callers provide logical state IDs, not arbitrary filesystem paths.
Persistence represents serialized browser storage/auth state.
BrowserMesh never attempts to serialize a live BrowserContext
, open pages, pending operations, or live browser process state.
| Environment variable | Default | Meaning |
|---|---|---|
BROWSERMESH_TIMEOUT_MS |
||
10000 |
||
| Default bounded operation timeout | ||
BROWSERMESH_DATA_DIR |
||
.browsermesh |
||
| Private local data directory | ||
BROWSERMESH_LOG_LEVEL |
||
info |
||
debug , info , warn , error , or silent |
||
BROWSERMESH_MAX_SESSIONS |
||
50 |
||
| Active session limit | ||
BROWSERMESH_MAX_PAGES |
||
20 |
||
| Managed pages per session | ||
BROWSERMESH_PERSISTENCE |
||
true |
||
| Enable saved browser state |
Configuration is read and validated centrally.
The BrowserMesh CLI always launches Chromium in headed mode when the first browser session is
created so the user can observe browser automation. Browser startup is lazy so MCP discovery and
actionable setup errors remain available when Chromium has not been installed yet. Set a larger
per-tool timeoutMs
only for operations that are expected to take longer than the safe default.
Direct scattered process.env
access throughout the codebase is not allowed.
MCP stdio reserves stdout for protocol traffic.
BrowserMesh structured logs therefore go to stderr.
Logs may contain safe correlation information such as:
operationId
;sessionId
;pageId
;- tool/operation name;
- duration;
- safe error code.
Logs must not contain:
- cookies;
- tokens;
- saved state;
- page contents;
- screenshots;
- form values;
- passwords;
- arbitrary message payloads.
BrowserMesh does not silently reconstruct live sessions if Chromium unexpectedly disconnects.
Affected sessions transition to a failed state and their live handles are invalidated.
Existing sessions are never silently recreated because doing so would violate BrowserMesh state guarantees.
A fresh Chromium process may be started for future newly created sessions if the runtime can safely recover, but old live sessions remain failed.
npm run typecheck
npm run lint
npm run format:check
npm test
npm run test:integration
npm run test:e2e
npm run test:stress
npm run test:coverage
npm run build
npm run verify
Browser integration/e2e tests use real Chromium together with a deterministic loopback HTTP test server.
Tests do not depend on public websites.
See:
Technical specificationArchitectureDevelopmentContributingRelease processSecurity policyArchitecture decisions
Pull request titles follow Conventional Commits. Every PR is checked by the full test matrix, package-install smoke tests, semantic-title validation, and CodeQL. Releases are prepared by Release Please and published to npm through GitHub OIDC only after a maintainer merges the generated Release PR.
BrowserMesh is distributed under the Apache License 2.0.
BrowserMesh v0.1 intentionally does not include:
- Firefox/WebKit parity;
- remote Streamable HTTP;
- BrowserMesh-hosted cloud infrastructure;
- multi-tenant authentication;
- distributed browser workers;
- live-operation crash recovery;
- internal Agent entities;
- internal session ownership tied to LLM agents;
- Agent registries;
- mailboxes;
- agent-to-agent messaging;
- internal LLM calls;
- prompt orchestration;
- Claude/Codex/Qwen process spawning;
- arbitrary shell execution;
- arbitrary filesystem reads;
- caller-controlled screenshot paths;
- downloads;
- web dashboard;
- network allowlist;
- full Playwright API.
A future generic client/workflow lease may be introduced if real multi-client protection requires it.
Such a lease must remain independent of LLM/Agent abstractions.
Within one BrowserMesh runtime:
- sessions are explicitly addressed;
- pages are explicitly addressed;
- each session has an isolated browser context;
- different sessions may execute concurrently;
- operations targeting one session execute deterministically through that session's queue;
- failures do not poison future queued operations;
- persisted state is handled through controlled logical identifiers;
- shutdown cleans up live browser resources;
- BrowserMesh performs browser execution while reasoning remains outside the runtime.