BrowserMesh – isolated Playwright sessions for MCP clients

BrowserMesh, an open-source local browser runtime for external AI clients, lets MCP-compatible tools such as Claude Code, Codex, Cursor, and Qwen control multiple isolated Chromium sessions via explicit sessionId and pageId addressing, with each session running in its own BrowserContext to prevent state sharing. Version 0.1, targeting Node.js 22+, includes features like semantic locators, per-session serialization, and parallel execution, and is designed to be configured once and driven by the AI client, not manually operated.

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 specification /scrollDynasty/multi-agent-browser-mcp/blob/master/docs/SPEC.md Architecture /scrollDynasty/multi-agent-browser-mcp/blob/master/docs/architecture.md Development /scrollDynasty/multi-agent-browser-mcp/blob/master/docs/development.md Contributing /scrollDynasty/multi-agent-browser-mcp/blob/master/CONTRIBUTING.md Release process /scrollDynasty/multi-agent-browser-mcp/blob/master/docs/releasing.md Security policy /scrollDynasty/multi-agent-browser-mcp/blob/master/SECURITY.md Architecture decisions /scrollDynasty/multi-agent-browser-mcp/blob/master/docs/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 /scrollDynasty/multi-agent-browser-mcp/blob/master/LICENSE . 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.