brawsr

brawsr MCP server

The authenticated local MCP bridge for brawsr browser sessions, checkpoints, rewind, and fork. It uses the official packaged @brawsr/sdk; it does not duplicate API models, poll orchestration, or browser/CDP behavior.

The v0.2 transport is local stdio and requires Node.js 22+.

Install and configure

MCP clients spawn the server locally. Pin the package version in client configuration so an MCP client restart cannot silently select a newer release:

{

"mcpServers": { "brawsr": { "command": "npx", "args": ["-y", "@brawsr/mcp-server@0.2.0"], "env": { "BRAWSR_API_KEY": "your-brawsr-api-key" } } } }

The npm package includes the official @brawsr/sdk; no second package install is required. BRAWSR_API_KEY is the only required environment variable. The production endpoint https://api.brawsr.io is built in.

For local development or another deployment, BRAWSR_BASE_URL may explicitly override that endpoint. BRAWSR_MCP_TIMEOUT_MS optionally changes the default bounded operation wait from 30 seconds and accepts an integer from 1 through 300000.

The API key is never a tool argument or result. Standard output is reserved for MCP protocol messages. Redacted lifecycle diagnostics use standard error. A direct shell launch uses the same executable:

BRAWSR_API_KEY=... npx -y @brawsr/mcp-server@0.2.0

Tools

• brawsr_create_session, brawsr_list_sessions, brawsr_get_session, brawsr_update_session_label, brawsr_close_session
• brawsr_close_sessions
• brawsr_create_checkpoint, brawsr_get_checkpoint, brawsr_list_checkpoints, brawsr_delete_checkpoint
• brawsr_list_rewindable_checkpoints, brawsr_list_session_activity, brawsr_get_session_lineage
• brawsr_rewind, brawsr_fork
• brawsr_get_operation, brawsr_wait_operation

Session creation accepts an optional display_label. The same label can be changed or cleared with one brawsr_update_session_label call. Session lists are newest-first, bounded, and may include retained closed or expired sessions. brawsr_get_session includes a CDP URL only while the session is attachable.

brawsr_list_checkpoints is capture history: it can include deleted captures for audit and dashboard views. Use brawsr_list_rewindable_checkpoints when choosing a valid rewind or fork target. Lineage returns one session, its optional parent fork edge, and one bounded page of direct children; callers can follow child session IDs to browse a nested fork tree. Pagination cursors are opaque and may be passed back unchanged.

Checkpoint, rewind, and fork are one high-level tool call. The packaged SDK hides ordinary 202 polling. Rewind returns as soon as its result is CDP-usable; the operation may finish bounded post-restore work in the background. A timeout stops only local waiting and returns the operation/idempotency recovery fields; server work continues.

Fork children are independent peer sessions, not implicit winners or losers. There is no browser-state merge and no automatic sibling cleanup. Rewind restores browser/client state, not remote website side effects, and makes old CDP/browser handles stale. Long-lived WSS/SSE/WebRTC streams may need application-level reconnection.

CDP URLs are sensitive structured outputs. The MCP server never returns the Authorization header. Use the ordinary SDK or a supported framework to attach; the MCP server does not proxy CDP.

Remote Streamable HTTP, OAuth, hosted multi-tenancy, legacy HTTP+SSE, and resumable MCP sessions are deferred beyond the local v0.2 stdio boundary.

Development

npm ci

npm run verify

Release archives are built reproducibly with the pinned Node 24 and npm 11.5.1 toolchain. CI also exercises the server and its real MCP client boundary on Node 22 and Node 24. npm hosts the executable package; the official MCP Registry hosts discovery metadata for io.github.brawsr/brawsr.