Quickstart

Connect a dedicated Chrome profile to your MCP client.

You need Node 22.14.0 or newer, installed Google Chrome on Linux or macOS, and an MCP client that supports Streamable HTTP with bearer authentication.

1. Choose a server

Sign in to browser-mcp.click with GitHub. To run your own server instead, follow the self-hosting or Helm guide and use your server’s URL below.

2. Install and start the CLI

Install the current 0.3.18 CLI release:

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

The CLI opens a dedicated Chrome profile, not your everyday browser. Sign in to the websites you want your MCP client to use in this profile. Keep the CLI running; stopping it closes this Chrome instance. Ctrl-C is safe during startup, and repeated termination signals wait for the same cleanup. If one cleanup step fails, the CLI still attempts the other independent safe steps before reporting the errors.

Need more than one browser? CLI 0.3.7 and newer support repeated --profile flags:

browser-mcp browser start --server https://browser-mcp.click --profile work --profile personal

Each profile pairs separately and has its own MCP URL/token. Local controls select one profile; Ctrl-C closes all browsers launched by that command. Separate terminals with different profiles also work. See multiple local browsers.

3. Approve the connection

Open the approval URL printed by the CLI in a separate non-automated browser profile. Check the hostname and browser name, sign in, and approve the request. Requests expire after ten minutes. Confirm that the dashboard shows the browser as connected.

4. Connect your MCP client

In the dashboard, create an expiring MCP token for the connected browser. Use the displayed /b/<browser-id>/mcp URL and Authorization: Bearer <mcp-token> header in your client’s secret settings. See native CLI setup for an example configuration.

MCP tokens grant broad access to the paired browser, including signed-in pages. Use only trusted clients and do not put tokens in URLs, chat, or source control.

Ask your client to list the tabs, open https://example.com in a new tab, and read its heading. Confirm the result before allowing it to act on sensitive websites.

5. Keep local control

From another terminal:

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

Remote clients cannot undo a local pause. Revoke unused MCP tokens in the dashboard.

If a crash leaves a named profile locked, first stop the prior CLI and Chrome, then use browser-mcp browser recover --profile work. Recovery preserves profile data and removes only stale lock/socket artifacts it can verify. It refuses live, reused or uncertain owners, unsafe artifacts, and orphan sockets; do not delete them blindly. Recovery is never automatic and does not reattach to the old Chrome process. See Native CLI recovery for the full procedure.

See security, file transfers and secrets, and forwarding before using those capabilities.