Releases and compatibility

Install the native CLI, select a version and understand platform limitations.

Current release: 0.3.18

Unified native CLI, managed/community images and community-only Helm chart. Native protocol remains 3; there is no database schema change. Chart templates and configuration are unchanged.

• Downloads stay in the dedicated browser’s private download folder. Up to 0.3.17 the CLI set Chrome’s download location through the window’s first tab; once that tab was closed, Chrome saved later downloads, including blob: attachments such as Outlook’s, to its normal Downloads folder and capture failed at browser-file with ENOENT. A browser-level session now owns download routing for the browser’s lifetime, applies the download limits to every tab, and reports outside-spool if a file is ever saved elsewhere.
• Every download in that folder can be retrieved. Downloads survive tab close and handoff, so popups that close themselves keep theirs. Downloads from user tabs, or that no tab surfaced, are shared with every session (owner: "user"); a session’s own downloads stay private to it. browser_open_tab or browser_navigate on an attachment URL reports downloadStarted: true and the download belongs to that session.
• Concurrent or interrupted downloads no longer close the browser: capacity is reserved for measured bytes when Chrome finishes a file. Retention and the copy deadline start at completion, so downloads that take Chrome more than two minutes are no longer cancelled.

Use matching CLI/server 0.3.18. Stop the old CLI before updating and restart the same named profile to preserve sign-ins and pairing. Publication does not upgrade an existing server; do not replay uncertain website actions. Manual verification is focused Linux coverage, not a claim of exhaustive macOS or fault-race acceptance.

Previous release: 0.3.17

Unified native CLI, managed/community images and community-only Helm chart. Native protocol remains 3; there is no database schema change. Chart templates and configuration are unchanged.

• Background screenshots use Chrome’s new capture surface without stealing focus. All screenshot modes have a 15-second capture timeout, sanitized stage/timing diagnostics and bounded delivery; settled failures remain visible in scoped runtime health.
• Eligible failed downloads retain their original completed browser source, original five-minute expiry and quota reservation. browser_retry_download_capture retries capture only, in the originating scope, without fetching a URL or repeating a website action. Retrieval remains unavailable until byte/hash verification succeeds.
• Failed capture diagnostics expose only allowlisted operation/reason metadata and an opaque correlation ID. Cleanup verifies source absence; uncertain revocation cleanup closes the owned runtime rather than silently freeing its quota.

Use matching CLI/server 0.3.17. Stop the old CLI before updating and restart the same named profile to preserve sign-ins and pairing. Publication does not upgrade an existing server; do not replay uncertain website actions. Manual verification is focused Linux coverage, not a claim of exhaustive macOS or fault-race acceptance.

Previous release: 0.3.16

Unified native CLI, managed/community images and community-only Helm chart. Native protocol remains 3; there is no database schema change.

• Local resume immediately acknowledges reconnecting/unpaused, without promising successful reconnection. Already-unpaused resume preserves the current state. Stale socket/initialization callbacks cannot publish connected state after pause, stop or transport replacement. Remote clients still cannot undo local pause; interrupted work is never replayed.
• Unscoped read_page queries search each captured frame’s document, including body/html. Explicit selector/ref scopes retain their boundaries. Visible DOM matches without rendered ARIA refs count toward matchCount and completeness.unrepresentedMatches, with complete:false and inspection guidance; pagination covers represented matches only.
• Server-published tool descriptions explain these query/scope and pagination semantics. The chart selects the matching server image; templates and configuration are unchanged.

Use matching CLI/server 0.3.16 for the fixes and current guidance. Stop the old CLI before updating and restart the same named profile to preserve sign-ins and pairing. Publication does not upgrade an existing server. Prior document-access security considerations below still apply.

Previous release: 0.3.15

Unified native CLI, managed/community images and community-only Helm chart. Native protocol remains 3; there is no database schema change. The chart advances the server image without changing templates or configuration.

• Ordinary concurrent work uses a bounded FIFO queue with scope/document revalidation before dispatch, explicit queue refusals and cancellation, and no automatic replay of uncertain actions.
• Broader document/PDF access respects Chrome’s interface limits rather than blanket URL exclusions. Capability support can be null when unprobed; that is not a success or failure claim.
• Native downloads capture completed browser files with byte/hash evidence. Empty-document warnings can return ready-with-warning; transport completion alone does not prove document completeness.
• Snapshot reads restore static text and explain zero-match queries.
• Unavailable retained-download lookups return a known resource_unavailable refusal before creating a link. Retry safety does not authorize repeating the source website action.
• Local control validates Unix socket paths in UTF-8 bytes before startup and reports sanitized stage/reason diagnostics. See path limits.

Security/upgrade notice: internal pages, file: documents and Browser MCP’s own dashboard are no longer blanket-blocked. Local documents may expose files readable by Chrome’s OS user. A signed-in dashboard can grant administrative authority through its cookies; revoking one MCP token does not undo other credentials already created. Keep administrative sign-ins in a separate non-automated profile unless deliberately delegating that authority. See Security.

Use matching CLI/server 0.3.15 for complete queue and download behavior. Stop the old CLI, update it, and restart the same named profile to retain sign-ins and pairing. Publication does not automatically upgrade an existing server.

Previous release: 0.3.14

Unified native CLI, managed/community images and community Helm chart; protocol 3 and database schema remain unchanged.

• Downloads, page exports and script artifacts return short-lived ordinary HTTPS bearer URLs, usable with curl without headers/cookies or a chat adapter. Reissue from retained bytes, never replay the source action automatically.
• Stable download IDs connect events to retained files/status; navigation no longer silently revokes downloads. Capture failures and bounded terminal expiry/revocation records are explicit.
• PDF page printing reports unverified content completeness and native-export/print-view guidance.
• Normal runtime contention reports busy/in-progress, distinct from deadline quarantine. Serialized execution and conservative unknown-outcome semantics remain.

Use matching server/CLI 0.3.14. Stop the old CLI and restart the same named profile to preserve sign-ins. See manual verification and release record for publication and rollout status. No automated suites were run for this owner-approved release.

Previous release: 0.3.13

Version 0.3.13 unifies the native CLI, managed/community server images and community-only Helm chart. It retains native protocol 3 and introduces no database schema change.

• Independent runtime health remains available during stalled page execution. Caller deadlines quarantine unresolved operations; subsequent commands reject immediately instead of queueing or replaying mutations. Explicitly approved recovery can close only the blocked tab owned by that session.
• Sanitized failure categories and correlation IDs distinguish unsupported targets, closed tabs, disconnects, timeouts, script errors and transfer failures without exposing page content or exception details.
• Authorized Chrome downloads, page exports and binary script artifacts share one scoped, short-lived HTTPS transfer route. Tool-only clients can import files without model-visible bytes; the CLI download helper verifies exact size and SHA-256. PDF-viewer limitations provide document-transfer guidance rather than repeated page inspection.
• The advertised tool schema is compact enough for model grammar compilers while complete canonical and semantic validation remains enforced before admission. No tools are hidden or truncated.
• The npm distribution remains one cross-platform Node package, @ricsam/browser-mcp, not platform-specific packages. Browser hosting remains supported on Linux/macOS with installed Chrome.

Use matching 0.3.13 server and CLI for these flows. Older runtimes report missing-capability/update-required errors for new operations; protocol 3 alone does not guarantee feature support. Stop the old CLI and restart the same named profile after upgrading to retain sign-ins and pairing credentials. Do not delete the profile or replay interrupted actions. See the manual verification and recovery/transfer guide for evidence and limits; source verification is not a claim that publication or deployment has completed.

Previous CLI release: 0.3.12

CLI 0.3.12 enables WebMCP by default on every owned Chrome launch.

• The shared launcher passes --enable-features=WebMCP,WebMCPTesting,DevToolsWebMCPSupport, covering the current and earlier feature names behind chrome://flags/#enable-webmcp-testing and the older DevTools protocol gate.
• Persistent, ephemeral and multi-profile browsers all receive the flags. No manual Chrome flag or profile edit is required. Native WebDriver and sandbox defaults remain unchanged.
• Regression coverage registers a page tool and discovers it through Chrome’s WebMCP protocol on initial launch, persistent restart and ephemeral launch. Local Linux checks passed with Chrome for Testing 149, 153 and 156.
• Tool execution still requires user authorization; enabling the API neither calls tools automatically nor grants permissions.

This was a CLI-only release, tagged cli-v0.3.12. Native protocol 3 and server/chart 0.3.6 are unchanged. Stop the old CLI before upgrading, then restart the same named profile to apply the launch flags while retaining sign-ins.

Previous CLI release: 0.3.11

CLI 0.3.11 reports unexpected Chrome exits and retains safe local diagnostics (#10).

• Terminal summaries preserve timestamps, profile/instance, PID, exit code or signal, shutdown intent and the diagnostic location. Unexpected failures return a nonzero CLI status even when cleanup also fails.
• Requested shutdown, normal browser exit, abnormal child termination and transport/context disconnection remain distinct. A disconnected context alone is not labelled a Chrome crash.
• Private, bounded incident JSON survives cleanup and restart under ~/.browser-mcp/diagnostics/. Only fixed diagnostic classifications and counters are retained, never raw Chrome stderr, CDP URLs, credentials or page content. See Chrome exit diagnostics for limits, retention and platform reports.
• Startup failures retain a safe stage/reason; concurrent disconnect/exit events produce one incident without hiding the original cause.

This was a CLI-only release, tagged cli-v0.3.11. Native protocol 3 and server/chart 0.3.6 are unchanged. Stop the old CLI before upgrading, then restart the same named profile to retain sign-ins. This improves diagnosis; it does not fix upstream Chrome crashes.

Previous CLI release: 0.3.10

CLI 0.3.10 keeps Chrome’s native navigator.webdriver false without overriding the getter or injecting a stealth script. The npm package is @ricsam/browser-mcp; its command is browser-mcp.

• Chrome runs headed without --enable-automation, --headless, --remote-debugging-pipe or --remote-debugging-port=0.
• The CLI owns the Chrome child and connects only to the fresh nonzero loopback CDP endpoint announced by that child. Sandbox, profile locks, persistent sign-ins and local stop/pause controls remain supported; no reattachment to old browsers is introduced.
• The loopback CDP listener is unauthenticated. Other local processes can control the profile outside MCP permissions and pause controls. Use a trusted host and never expose or forward the listener. See Security.
• Regression coverage checks the native value in new tabs, page-load scripts and iframes, persistent restarts and ephemeral profiles, alongside input, screenshots, downloads and shutdown.

This was a CLI-only release, tagged cli-v0.3.10. Native protocol 3 is unchanged and server images, the community-only Helm chart and managed production remain at 0.3.6. Stop the old CLI before installing the new version, then restart the same named profile to retain sign-ins.

Use current stable Google Chrome. Older Chrome 152/153 builds used during development crashed on repeated-profile downloads; macOS Chrome for Testing 155.0.8059.84 stalled on navigation. Official Google Chrome stable 155.0.8059.85 passed the full macOS native suite. Native CI now installs the signed official stable browser on macOS; see macOS CI evidence. Candidates cli-v0.3.8 and cli-v0.3.9 were not published to npm after their macOS checks failed; their tags are retained rather than rewritten.

Previous CLI release: 0.3.7

CLI 0.3.7 added multiple local browsers in one foreground command.

browser-mcp browser start --profile work --profile personal --profile testing

• Repeat --profile for two or more isolated Chrome instances. Each profile has separate sign-ins, pairing credentials, dashboard registration and local controls. Approve each new profile separately and configure its own MCP URL/token.
• status, pause, resume and stop select one profile. Stopping one browser leaves its siblings running; Ctrl-C closes the whole foreground group. A launch/runtime failure cancels the group and waits for safe cleanup.
• Duplicate profile names are rejected before startup. Omitting --profile still selects default. Separate terminals with different profiles remain supported.
• --server, --chrome-path, --ephemeral and --live-view apply to every profile in a grouped launch. Existing sign-ins and pairing credentials are preserved on upgrade.

This CLI-only release was tagged cli-v0.3.7 and retained native protocol 3 with server/chart 0.3.6. See multiple local browsers for usage and lifecycle details.

Previous release: 0.3.6

Version 0.3.6 released the native CLI, managed and community server images, and community-only Helm chart. Release CI passed on Linux and macOS. The published npm package was fresh-installed and tested with a local synthetic relay; the managed/community images and exact public chart archive were independently verified. Its managed production rollout was verified healthy with its prior configuration preserved. Production checks covered health and configuration, not a live user browser pairing.

That release implements GH #8:

• Ctrl-C and termination signals are handled from the beginning of native browser startup. An interruption cancels remaining startup work, waits for any in-progress bounded Chrome launch, and closes resources already acquired. Repeated signals wait for the same cleanup rather than bypassing it.
• Independent cleanup stages continue even when one stage fails; the CLI reports the collected cleanup errors after attempting the other safe stages.
• browser-mcp browser recover --profile <name> is an explicit, conservative Linux/macOS operator command for verified stale runtime lock/control socket artifacts. It preserves profile data and refuses live, PID-reused or uncertain owners, possible surviving profile processes, live or uncertain sockets, unsafe or changed artifacts, foreign or unrecognized owners, and socket paths without lock provenance.
• There is no automatic crash cleanup and no detach or reattach to a prior Chrome process.

Install a specific version

Requires Node.js 22.14.0 or newer and an installed Google Chrome. npm installation does not download or start a browser.

npm install -g @ricsam/browser-mcp@0.3.17
browser-mcp --help
browser-mcp browser start --server https://browser-mcp.click --profile work

Or run without a global installation:

npx @ricsam/browser-mcp@0.3.17 --help

Follow Quickstart for pairing and Native CLI for profile and lifecycle controls. A Chrome extension is not required.

Platform compatibility

• Linux and macOS: native Chrome launch and page operations are supported. Linux needs a graphical display and a working Chrome sandbox. CI performs compiler/build checks only; product verification is supervised and manual, not a cross-platform suite guarantee.
• Windows: browser hosting and secret-file support are unavailable.
• Server: one replica is supported. Horizontal scaling, transparent stream resumption and zero-downtime failover are not available.
• Browser lifecycle: keep the CLI running while using its browser. Graceful signal cleanup and explicit browser recover --profile do not provide automatic crash cleanup or reattachment to a previous Chrome process.

These checks do not establish compatibility with every OS distribution, Chrome version or deployment configuration. Test your own environment before relying on it for important tasks.

Self-hosted versions and upgrades

Use the Helm installation guide for server installation and version selection. Pin the CLI, chart and server image versions in your deployment records; do not assume arbitrary combinations of versions are compatible. Use CLI, server and chart 0.3.17 together for the current release; native protocol remains 3 and the database schema is unchanged. The chart remains community-only. Older peers do not provide the complete current queue, document-access and download behavior.

An upgrade interrupts active browser connections. Back up persistent state first and follow Operations for restart, verification and recovery guidance. Reconnecting does not replay interrupted actions.

Help and security reports

For setup problems, include your CLI/server versions, operating system and a redacted error message when contacting your server operator. Do not include tokens, cookies, pairing credentials or private page content.

Report security concerns privately to [e-mail]. See Security for the browser-control boundaries and limitations.