CLI and environment

Entry point

bunx browspark-mcp@latest [--port <n>] [--http-only]

or the compiled dist/browspark with the same flags.

Flag	Effect
`--port <n>`	Listen on this port instead of `9223` for the extension bridge, the HTTP MCP endpoint and the live view.
`--http-only`	Do not connect MCP over stdio and do not exit when stdin closes. For URL-based clients when no stdio client is running.

Environment variables

Variable	Default	Purpose
`BROWSPARK_PORT`	`9223`	Same as `--port`.
`BROWSPARK_CHROME`	auto-detected	Executable for `browser: "chrome"` or `"chromium"`.
`BROWSPARK_BRAVE`	auto-detected	Brave executable for `browser_session` with `browser: "brave"`.
`BROWSPARK_FIREFOX`	auto-detected	Firefox executable for `browser_session` with `browser: "firefox"`.
`BROWSPARK_ZEN`	auto-detected	Zen executable for `browser_session` with `browser: "zen"`.
`BROWSPARK_PROFILE`	`~/.browspark/profile`	Profile directory of the `default` Chrome developer context.
`BROWSPARK_PROFILES`	`~/.browspark/profiles`	Parent of named Chrome profiles and the `.brave/<context>`, `.firefox/<context>` and `.zen/<context>` profiles.
`BROWSPARK_ARTIFACTS`	`~/.browspark/artifacts`	Output directory for traces, profiles, snapshots, HAR, PDFs, reports and flows.
`BROWSPARK_UPDATE_CHECK`	on	`0` stops the companion from checking GitHub for extension releases and installing them.
`BROWSPARK_RELEASES_URL`	GitHub’s latest-release API for `outofmemry/browspark`	Release metadata endpoint for extension updates, for mirrors and tests.
`BROWSPARK_EXTENSION_DIR`	unset	Extra extension folders to consider when updating, separated by `:` (`;` on Windows). Folders that receive an update are remembered in `~/.browspark/extensions.json`.

Recorder exports read flow parameters from environment variables named after the parameter in upper case ({{email}} → EMAIL). On browser_session launch, browserPath overrides the executable for the chosen browser. Legacy chromePath and firefoxPath options remain supported. "chrome" and the default "chromium" selection share the existing Chrome profile paths. Several extension browsers can connect to the same port. Select an extension instance by the browserId returned by browser_status; select a developer session by context. Tab tools use globally unique tabId values. See using multiple browsers.

Package scripts

Script	What it does
`bun run build`	Bundle the shared background process and dashboard into `dist/chromium-extension/` and `dist/firefox-extension/`.
`bun run package`	Build `dist/browspark-chrome-extension.zip` and the unsigned `dist/browspark-firefox-extension.zip`.
`bun run compile`	Single-file companion binary at `dist/browspark`.
`bun run start`	Run the companion from source.
`bun run typecheck`	Type-check companion and extension.
`bun test`	Unit and bridge tests (no browser).
`bun run test:e2e`	Run Chromium acceptance scenarios, including simultaneous extension instances. Build the extension first.
`bun run test:firefox`	Run Firefox developer-session acceptance tests through BiDi.
`bun run test:multi-browser`	Run Chrome, Brave, Firefox and Zen developer sessions together. Install all four or set their executable environment variables.
`bun run capabilities`	Regenerate the capability matrix by probing both Chromium modes.
`bun run docs:tools`	Regenerate the tool reference pages and their navigation from the tool registrations.

What the companion prints

Everything goes to stderr, because stdout is the MCP stdio channel.

browspark: ready on ws://127.0.0.1:9223; MCP over HTTP at http://127.0.0.1:9223/mcp
browspark: extension connected: ext:<id> (Google Chrome <version>)
browspark: agent connected: claude-code
browspark: http client session 5f1e9c0a
browspark: relaying stdio to the companion already running on port 9223
browspark: agent disconnected: claude-code
browspark: extension disconnected: ext:<id>
browspark: updated the chromium extension in ~/browspark-extension to <version>

Exit behaviour

The companion exits when stdin closes (the stdio client went away), on SIGINT or SIGTERM. On exit it closes the bridge and every developer browser it launched. Relays exit when their stdin closes; when the owner they relay to stops answering they take the port over instead.

Get started

Connect an agent

Concepts

Dashboard

Guides

Reference

CLI and environment

Entry point

Environment variables

Package scripts

What the companion prints

Exit behaviour

​Entry point

​Environment variables

​Package scripts

​What the companion prints

​Exit behaviour

Entry point

Environment variables

Package scripts

What the companion prints

Exit behaviour