> ## Documentation Index
> Fetch the complete documentation index at: https://browser-mcp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

Install the current 0.3.7 CLI release:

```sh theme={null}
npm install -g @ricsam/browser-mcp@0.3.7
```

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

## Start and pair

```sh theme={null}
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.

## Multiple local browsers

Each browser needs a different profile name. You can run separate `browser start`
commands in separate terminals today:

```sh theme={null}
# Terminal 1:
browser-mcp browser start --server https://your-server.example --profile work
# Terminal 2:
browser-mcp browser start --server https://your-server.example --profile personal
```

CLI 0.3.7 and newer also accept repeated `--profile` flags to start two or more browsers in one foreground command:

```sh theme={null}
browser-mcp browser start --server https://your-server.example --profile work --profile personal --profile testing
```

Each profile has isolated Chrome data/sign-ins, pairing credentials, local
controls and a separate browser registration. Approve each new profile's labeled
pairing link and configure its own dashboard MCP URL/token. No profile's
credential is shared with another.

Use `status`, `pause`, `resume` or `stop` with one `--profile` to control only that
browser. Closing or stopping one browser leaves the others running. Ctrl-C in the
group's terminal closes every browser launched by that command. The command
stays running until all its browsers stop. A launch/runtime failure cancels the
group and waits for cleanup; an existing profile owner is never taken over.

`--server`, `--chrome-path`, `--ephemeral` and `--live-view` apply to every profile
in a grouped launch. For different options or independent CLI lifetimes, use
separate terminals. With `--ephemeral`, each logical name still selects its own
pairing and local controls, but its Chrome data is throw-away. No `--profile`
means `default`. Repeated names are rejected; a busy profile requires a different
name, not deleting its lock. Local control and recovery commands accept only one
profile at a time.

## Visible local controls

Use another local terminal with the same profile:

```sh theme={null}
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. Signal handlers are active from the beginning of startup. Ctrl-C during startup cancels remaining work, waits for an in-progress bounded Chrome launch, and then closes resources already acquired. Repeated Ctrl-C or other termination signals wait for the same cleanup instead of bypassing it. Pairing waits are cancelled. If one cleanup stage fails, the other independent safe stages are still attempted and the errors are reported afterwards.

There is no detach/reattach mode, and a restart creates a new runtime instance rather than attaching to an old Chrome process. 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.

## Explicit crash-artifact recovery

A crash can leave a named profile's runtime lock and local control socket behind. They are deliberately not removed automatically, and startup will not delete or take over an existing path. First stop the prior CLI and its dedicated Chrome and prevent concurrent startup or manual artifact changes. Then run the operator command with the logical profile name, never a filesystem path:

```sh theme={null}
browser-mcp browser recover --profile work
```

Recovery is limited to Linux and macOS. On success it removes only a verified stale control socket and runtime lock, in that order. The Chrome profile and its sign-ins, downloads, run data, and Chromium singleton artifacts are preserved. If no recovery artifacts exist, it leaves the profile unchanged.

Recovery is intentionally conservative. It refuses rather than guesses when the recorded PID is live or may have been reused, the owner or process scan is uncertain, a possible profile process survives, a control listener is live or cannot be proven stale, ownership or private permissions are unsafe, an ancestor or artifact is a symlink or other unexpected type, an artifact changes during checking, Chromium ownership is foreign or unrecognized, or a socket is orphaned without matching lock provenance. Do not work around refusal by deleting paths blindly or creating a replacement lock.

There is no automatic crash cleanup and no reattachment to the old Chrome process. If recovery refuses, retain the exact paths printed in the error and investigate the prior owner. Only a qualified operator who can independently prove exact path provenance, private ownership, unchanged artifact identity, and absence of every possible owner or listener should consider manually removing that exact stale socket; never remove profile directories or Chromium singleton files.

## 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:

```json theme={null}
{
  "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](native-data.md).

## 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: use a different `--profile` to launch another browser, or 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 [support@browser-mcp.click](mailto:support@browser-mcp.click), or your self-hosted operator. Include version and redacted failure metadata, never tokens or private page content.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.