Skip to content

setup.md

Latest commit

 

History

History
255 lines (166 loc) · 18.4 KB

setup.md

File metadata and controls

255 lines (166 loc) · 18.4 KB
Raw

Installation and configuration

For the recommended npm + Chrome Web Store installation, follow the README quick start.

What setup does

npm install -g @jackwener/browsermcp installs the software. browsermcp setup configures the two connections it needs:

  1. Chrome → local program: writes the Native Messaging registration so Chrome can start the program when the extension connects.
  2. MCP client → local program: asks you to select claude, codex, opencode, pi, or a combination when their CLIs are on your PATH. Only selected clients are configured; their browsermcp entry is set to the managed launcher. Other server entries are unchanged. Pi requires pi-mcp-adapter. Choose manual (the default) for a ready-to-copy configuration using absolute paths, or none to configure only the browser connection.

It then checks the live browser connection. If disconnected, it opens the Chrome Web Store and waits for the extension to connect. The extension retries automatically, so you can install it before or after running setup. Already connected? No store page is opened.

setup never installs an extension silently. Add it through the Chrome Web Store or from the manual-install zip in GitHub Releases. Rerunning setup updates the managed launcher. Selecting a client also replaces its browsermcp entry, so setup can repair an incorrect command.

Setup options

In a terminal, enter client IDs separated by commas at the prompt. Press Enter to show manual configuration without modifying any client.

For scripts, select clients explicitly. Without --clients, non-interactive setup prints manual configuration and leaves all MCP client settings unchanged:

browsermcp setup --clients codex
browsermcp setup --clients claude,codex
browsermcp setup --clients opencode
browsermcp setup --clients pi
browsermcp setup --clients manual  # show configuration for any MCP client
browsermcp setup --clients none    # configure only the browser connection
browsermcp setup --no-open       # print the store link without opening it
browsermcp setup --wait 60       # wait up to 60 seconds (default: 180)
browsermcp setup --no-open --wait 0  # save registration, then check the connection once

A timeout leaves the configuration in place: enable the extension and rerun setup. In particular, --wait 0 can exit with code 1 after printing Browser connection registered and Your registration has been saved: registration succeeded, but the extension was not connected at the one-time check. Exit code 0 means both the live connection check and any selected client registrations succeeded. A detected client registration failure is reported as incomplete even if the browser is connected. If a selected CLI is unavailable, setup reports it before writing any configuration. In an interactive terminal, invalid input can be corrected and Ctrl+C cancels without making changes.

browsermcp doctor checks registration and the live connection without changing settings. It is for troubleshooting; it is not a required setup step.

Stable launch entrypoint

Both Chrome and MCP clients use ~/.browsermcp/bin/browsermcp-launcher (.cmd on Windows). Chrome starts the launcher in host mode; MCP clients pass stdio. Paths and arguments are printed by setup, so desktop apps do not need your terminal's npm PATH.

Setup records the Node executable and package entry in ~/.browsermcp/installation.json and generates the launcher from that record. Treat both as setup-managed files. Doctor checks the runtime, program entry, launcher, browser registration, and live connection separately. A running host does not hide missing files needed at the next start.

For Homebrew installations, setup uses the corresponding formula's stable opt path when it resolves to the current file. This applies to both Node and the package entry. Other installations use their current absolute paths. The launcher does not search version managers, download Node, or fetch an npm package on startup.

OpenCode

Run browsermcp setup --clients opencode. Setup adds a local MCP server to your global OpenCode config (~/.config/opencode/opencode.json, or opencode.jsonc if that is your existing file). It updates the browsermcp entry while preserving comments outside that entry and other settings. Restart OpenCode, then use opencode mcp list to check the connection. The launcher path is absolute, so OpenCode does not need your terminal's npm PATH.

DeepSeek Harness (dsh)

After installing the Chrome extension and browsermcp globally, connect the browser without configuring another MCP client, then add the dsh bundle to your active profile:

browsermcp setup --clients none
dsh plugin --profile web add @jackwener/browsermcp

Restart dsh web. The main package's bundle inserts one @deepseek-ai/dsh-mcp-client entry using the launcher created by setup, so dsh discovers the same MCP tools without depending on npm's PATH. To remove the dsh registration, run dsh plugin --profile web remove @jackwener/browsermcp. Replace web with your active dsh profile when needed.

Pi

Pi does not include an MCP client. Install the community pi-mcp-adapter, then select Pi in setup:

pi install npm:pi-mcp-adapter
browsermcp setup --clients pi

Restart Pi. Setup adds one entry to Pi's own global mcp.json (normally ~/.pi/agent/mcp.json) using absolute paths, without changing other servers. Use the adapter's mcp tool to discover and call browser tools.

Other Chromium browsers

Setup recognizes Chrome, Chromium, Edge, and Brave on macOS and Linux, plus Chrome Beta, Canary, Chrome for Testing, and Arc on macOS. On Windows it registers the Chrome Native Messaging host. Extension availability depends on the browser.

Chrome is registered even before its first launch. Other browsers are detected from their existing profile directories, or can be selected explicitly:

browsermcp setup --browsers edge --no-open

Install the extension in that browser. For a browser launched with a custom user data directory:

browsermcp setup --user-data-dir /absolute/path/to/profile

Setup also detects running custom profiles on macOS and Linux.

From source

git clone https://github.com/jackwener/browsermcp.git browsermcp
cd browsermcp
npm install
node dist/src/main.js setup

npm install runs the build through prepare. The same setup flow works with the Web Store extension. For manual MCP client configuration, use the absolute paths printed by setup.

Developing the extension

Only extension developers need an unpacked build:

  1. Run node dist/src/main.js extension-path to find the built extension directory.
  2. In chrome://extensions, enable Developer mode, disable the store extension if installed, and Load unpacked from that directory.
  3. Run node dist/src/main.js setup --no-open to configure and verify the connection.

The development manifest uses the published extension's key, so it has the same ID. Use one build at a time. After changing extension code, run npm run build:ext and click Reload in Chrome.

Manual extension installation

Each new GitHub Release includes browsermcp-extension-manual-install-<extension-version>.zip. Older releases use the opencli-mcp-extension- filename prefix. The extension version is separate from the npm package version.

  1. Download and extract the zip. Select the extracted directory containing manifest.json; Chrome cannot load the zip directly.
  2. In chrome://extensions, enable Developer mode. Disable the Web Store copy if present, then choose Load unpacked and select that directory.
  3. Run browsermcp setup --no-open and browsermcp doctor to verify the connection.

Keep the extracted directory in place while using the extension. For an update, extract the newer zip to a stable directory and reload the extension in Chrome. The manual zip includes manifest.key, so Chrome uses the same extension ID as the Web Store copy. Do not use the separate Web Store upload zip with Load unpacked.

From a release tarball

Download a package from GitHub Releases, then run:

npm install -g ./jackwener-browsermcp-<version>.tgz
browsermcp setup

Install the Chrome extension from the Web Store or use the manual-install zip above.

Updating

npm install -g @jackwener/browsermcp@latest
browsermcp setup

Homebrew upgrades within the same formula normally need no configuration change: the opt path follows the installed version. This assumes the package is still installed at its recorded location. Switching formulas (for example, node@22 to node@24), switching version managers, moving the source checkout, or losing the global npm package requires installing the package under the chosen runtime and rerunning setup. Existing clients using the managed launcher keep the same command.

When configuring a client for the first time with the managed launcher, select it explicitly, for example browsermcp setup --clients claude,codex. For other clients, copy the configuration printed by --clients manual.

Chrome updates the store extension independently. If the old host is still running, disable and re-enable the extension to start the updated program, the running MCP launcher reconnects automatically. Use doctor to check both the live connection and the files needed for the next startup.

Runtime names and clean setup

Component Name or location
Data and settings ~/.browsermcp
User adapters ~/.browsermcp/adapters
Launcher ~/.browsermcp/bin/browsermcp-launcher (.cmd on Windows)
Native Messaging host com.browsermcp.host
MCP client entry browsermcp
MCP resource URIs browsermcp://docs/{name}, browsermcp://sites
Adapter SDK @jackwener/browsermcp/adapter-sdk

Install the matching updated extension and run browsermcp setup to register this host and launcher. Old directories, environment variables, SDK aliases, and client entries are not migrated. Remove obsolete client entries manually. The new extension storage keys start fresh, including the browser ID; choose a new ID with browsermcp doctor --json if selecting a particular profile.

Local connections and browser selection

MCP clients use the managed launcher's standard stdio command. The launcher connects to the Chrome-owned host through a Unix domain socket (macOS/Linux) or a named pipe (Windows). There is no HTTP endpoint, network port, bearer token, or remote MCP mode to configure.

Each connection owns one MCP/REPL session. Closing the client releases that session's resources. A host restart does not kill the client's stdio connection: the launcher reconnects to the same browser profile, reports session_restarted before running another tool, and requires fresh REPL bindings and Tab handles. Calls interrupted by a disconnect return an unknown-outcome error and are never automatically replayed.

A single connected browser is selected automatically. If several profiles are connected, browsermcp doctor --json lists their browserId values and endpoints. Set browserId in the configuration below to choose one. Each extension profile keeps its browser ID across host restarts; reinstalling the extension can change it. Once connected, a launcher remains pinned to that browser even if another profile opens or closes.

Configuration

BrowserMCP requires no product-specific environment variables. Setup registers the launcher, and a single connected browser is selected automatically.

Settings live in ~/.browsermcp/config.json. For example:

{
  "cursor": false,
  "sites": ["twitter", "reddit"],
  "sitesWrite": []
}
Setting Effect
browserId Optional profile selection when several browser hosts are connected; listed by doctor --json
cursor Show the agent cursor overlay (default: false; enabling it inserts a visible DOM overlay)
sites Site commands to enable at startup, read-only
sitesWrite Sites whose write commands should also be enabled

Element refs and action targets are kept in the extension's isolated world, without DOM marker attributes. Screenshot annotations are also opt-in (annotate: true) and temporarily insert DOM overlays during capture. Leave cursor and annotations disabled when DOM overlays are unwanted.

The same state directory contains one discovery record per host under run/<instanceId>.json, and user-defined adapters under adapters/<site>/<name>.js. IPC endpoints are allocated automatically; do not put their paths in MCP client configuration.

Troubleshooting

Run browsermcp doctor first. It reports startup dependencies, browser registration, and whether the local host and extension are connected, with recovery steps for failures. Use doctor --json for machine-readable diagnostics.

Symptom What to check
Specified native messaging host not found. Chrome cannot find its Native Messaging registration; follow the Windows recovery path below
browser_unavailable or host unreachable Keep Chrome running, enable the extension, and verify the host registration
Web Store extension cannot connect Run browsermcp setup; if it stays disconnected, disable and re-enable the extension
No host manifest was written Rerun setup; for custom profiles, pass --user-data-dir
Node runtime or program entry missing Install Node/package as needed, then run browsermcp setup; select clients if their commands also need repair
MCP client cannot find browsermcp Use the absolute executable path in the client configuration
Development changes do not appear Rebuild the extension and click Reload on the extensions page

For runtime errors such as dialog_open or stale tabs, see browser troubleshooting and error codes.

Windows Native Messaging recovery

Chrome may report:

[browsermcp] native host disconnected after 4ms (attempt 1) Specified native messaging host not found.

An enabled MCP client entry does not establish the browser connection. The two connections are separate: the MCP client launches the MCP transport, while Chrome locates and launches the Native Messaging host through its own registration. On Windows, setup writes the host manifest and launcher, and registers the manifest path under HKCU\Software\Google\Chrome\NativeMessagingHosts\com.browsermcp.host for the current Windows user. Run setup as the same user who runs Chrome; administrator access is not required.

  1. If using an old package, update it with npm install -g @jackwener/browsermcp@latest. After an update or a Node.js installation change, refresh the browser registration:

    browsermcp setup --clients none --no-open --wait 0
browsermcp doctor --json

    --clients none preserves existing MCP client settings. Use browsermcp setup instead if the client also needs configuring. Check the setup output: exit code 1 together with Your registration has been saved means the live browser connection is still pending, not that registration was rolled back.

  2. Interpret the diagnostics by stage:

    Diagnostic Meaning and next step
    Manifest present: false, launcherExists: false, launcherMatches: false, or authorized: false The registration files are incomplete, point to an old launcher, or do not authorize the published extension. Rerun setup and resolve any error it prints.
    launch.ready: false Startup dependencies are missing or inconsistent. Read launch.errors; reinstall a missing Node runtime or package, then run setup from a working installation. A host that is still running does not prove its next launch will work.
    Registration fields and launch.ready true, but host.running: false / no host state file Startup files pass, but doctor has not reached a live host. Keep Chrome open, install or enable the extension, then disable and re-enable it in chrome://extensions if needed.
    host.running: true, extensionConnected: false The host is reachable but its extension connection is missing. Enable or restart the extension.
    ok: true Startup dependencies, registration files, and the live host/extension connection pass. Reconnect the MCP client and try opening and reading https://example.com/.

    For an unpacked extension, use Reload after updating its files. Chrome Web Store extensions update separately from the npm package.

  3. Run browsermcp doctor again after reconnecting. If Chrome still says Specified native messaging host not found., inspect the registration from the same Windows account:

    reg query "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.browsermcp.host" /ve

    The default value must point to the existing Chrome manifest reported by doctor. Doctor checks the runtime and program entry, launcher consistency, manifest file, authorized extension origin, and live connection; it does not currently verify the Windows registry value. A missing or stale registry value needs setup again under the Windows account running Chrome.

Duplicate hosts and recovery

A browserId identifies a browser profile; an instanceId identifies one host process. Discovery probes the extension round trip without opening an Agent session. For duplicate hosts of one browser, new clients choose the newest responsive instance automatically; existing sessions stay on their current host. Different available browser IDs still require browser selection.

doctor --json includes per-instance probes: readiness, selection and connection failures. Unselected hosts are not killed. Hosts retire after three consecutive failed extension checks (15-second intervals, 2-second ping timeout); shutdown is bounded to 5 seconds. Registry age and parent PID changes are not health signals.

After a host disconnects, the launcher reconnects to the same browser. session_restarted means the current call was not executed and REPL bindings must be recreated. command_outcome_unknown means a dispatched call may have taken effect: inspect browser state before retrying. Discovery never replays mutations.

The local IPC handshake changed: after upgrading the npm package, reload the extension to restart the native host, then restart the MCP client. The extension and host version numbers need not match.