Native Chrome CLI

Pair a dedicated Chrome profile and retain local control.

Install and requirements

Requires Node 22.14.0 or newer and an installed stable Google Chrome on Linux or macOS. Linux needs a graphical display and a working Chrome sandbox. Windows browser hosting and secure file/secret output are not supported.

npm install -g @ricsam/browser-mcp@0.3.4

Installation does not download or launch Chrome. Agent-only help/file/secret/forward commands do not need a display or Chrome.

Start and pair

browser-mcp browser start --server https://your-server.example --profile work
# Explicit throw-away profile:
browser-mcp browser start --server https://your-server.example --ephemeral
# Explicit installed Chrome binary:
browser-mcp browser start --server https://your-server.example --profile work --chrome-path /path/to/chrome

The runtime owns a separate Chrome profile. Named profiles persist sign-ins; ephemeral profiles are explicit and cleanup is limited to owned files. Do not point it at a normal Chrome profile or copy daily-driver cookies. Concurrent profile owners are rejected. Local process/profile access is outside the security boundary: this is not a sandbox against malicious software running as you.

Open the printed device approval URL in your browser, verify its hostname and request name, sign in and explicitly approve. Managed uses GitHub; community uses local bootstrap or configured OIDC. Device requests expire after ten minutes. The random proof held by the CLI—not the approval URL alone—redeems the credential. Restart pairing if expired.

The native connection credential is distinct from a dashboard-created MCP client token. Protect credential files; do not supply literal credentials in arguments, URLs, tickets or chat. Device pairing is the supported setup; there is no manual connection-token import.

Visible local controls

Use another local terminal with the same profile:

browser-mcp browser status --profile work
browser-mcp browser pause --profile work
browser-mcp browser resume --profile work
browser-mcp browser stop --profile work

Remote agents cannot resume a local pause. Use the CLI status command to check whether the browser is paused or running. Revoking an MCP token removes that client. Rotating the browser credential invalidates its saved credential and disconnects the runtime. For recovery, stop it, revoke/delete the old registration as appropriate, identify and remove only the exact private credential file for that server/profile, then start and approve a new pairing. The new registration needs new MCP tokens. Do not remove the Chrome profile, directory trees or unrelated credential files. Deleting the registration removes its access credentials, not your personal Chrome files.

The runtime stays in the foreground and uses private-pipe Chrome control: Ctrl-C or stop closes its Chrome. There is no detach/reattach mode. Stop before replacing CLI binaries, then restart the same named profile to retain sign-ins. Live view requires explicit local --live-view on browser start and is off by default.

Relay reconnect, CLI restart and Chrome restart are different events. A reconnect never authorizes replaying uncertain clicks, form submissions, scripts or file attachments. Stale document refs/choosers must be reacquired. Forwarding and bulk streams do not transparently resume after disconnect. Read status and inspect results before retrying.

MCP client setup

Create an expiring token for the connected browser in the dashboard. Store the token in your client’s secret settings and use its Streamable HTTP transport:

{
  "mcpServers": {
    "browser": {
      "type": "http",
      "url": "https://your-server.example/b/<browser-id>/mcp",
      "headers": { "Authorization": "Bearer <mcp-token>" }
    }
  }
}

Client configuration keys vary. Token scope is broad browser control, not single-tab or read-only. Start with browser_list_tabs, then a temporary tab on https://example.com. File staging and secret export are separate explicit capabilities; see data and secrets.

Update safely

The dashboard shows native version, protocol, advertised capabilities and an update-required indicator. Protocol 3 is the native contract; unsupported commands fail closed. Stop the runtime, install a compatible CLI version, then restart the same named profile. Do not delete credentials or profiles as an update mechanism. There is no silent unrestricted auto-updater. Chrome itself should be maintained through its normal trusted update channel.

Troubleshooting

• Offline: check local status, approval, exact server URL, TLS and proxy WebSocket support.
• Update required: use a verified compatible CLI/server pair; do not bypass capability checks.
• Profile busy: stop the owning runtime; do not delete locks or another process’s files blindly.
• Control-plane or privileged page rejected: expected; use an ordinary website that you are authorized to access.
• Unknown action outcome: inspect before deciding any next action; never blindly replay.
• Clipboard/live view unavailable: these are capability/platform dependent and require local permission/opt-in, not automatic fallback.

For support use [e-mail], or your self-hosted operator. Include version and redacted failure metadata, never tokens or private page content.