Installation

Requirements

Requirement	Notes
Bun 1.x	Runtime, package manager, bundler and test runner. Nothing else is needed; there is no Node or npm step.
A supported browser	Chrome, Brave, Edge or Chromium; Firefox 153+ or a Zen build based on Firefox 153+ for the Firefox extension. Developer mode supports Chrome, Brave, Firefox and Zen.
An MCP client	Claude Code, Codex, OpenCode, Cursor, Antigravity, Muse Code, or anything that speaks MCP over stdio or Streamable HTTP.

One-command setup

The setup script covers everything on this page for the common case: it asks which extension you want (Chrome, Firefox, or both), lets you choose bun, pnpm or npm to run the companion, writes the MCP config for the agents you pick, and prints the final steps. If your client isn’t listed, pick Other and the script prints the server command to add by hand.

curl -fsSL https://browspark.krishm.dev/setup.sh | bash

bash setup.sh --test is a dry run: it prints every command and file it would write without touching anything. The script lives at setup.sh in the repo. The setup script downloads the release archives for the browsers you pick. To build from source instead, or to load Firefox from a checkout, use the packages below; both extension builds can connect to one companion at the same time.

The companion

The companion is the MCP server. It is published on npm as browspark-mcp (alias browspark) and runs with a single command, no clone or install step:

bunx browspark-mcp@latest

From a clone of the repo, bun companion/src/index.ts runs the same code from source. Use this source entry point when testing an extension built from the checkout: set the MCP command to bun and its argument to the absolute path to companion/src/index.ts. A published bunx package may be older than your local extension. Restart the old companion and its relays after changing the command; otherwise new clients still connect to the old process on the shared port. See connection troubleshooting. Started by an MCP client it speaks MCP over stdio. On every start it also opens 127.0.0.1:9223 for every extension’s WebSocket connection, the HTTP MCP endpoint and the live view. Chrome and Brave can connect to this same port simultaneously. If another companion already owns the port, the new process becomes a relay to it instead of failing. See Multiple agents and using multiple browsers.

Single-file build

Clients that run MCP servers in a sandbox without access to your source tree (some IDE sandboxes and hosted agents) can use a compiled binary:

bun run compile
# → dist/browspark

The binary has no dependencies and takes the same flags as the source entry point.

Flags and environment

Flag or variable	Default	Effect
`--port <n>` / `BROWSPARK_PORT`	`9223`	Bridge, HTTP and live-view port. Set the same port in the dashboard’s Settings.
`--http-only`	off	Do not open the stdio transport. Use when no client launches the companion and you only want the HTTP endpoint.
`BROWSPARK_CHROME`	auto-detected	Executable for `browser: "chrome"` or `"chromium"`.
`BROWSPARK_BRAVE`	auto-detected	Brave executable for `browser: "brave"`.
`BROWSPARK_FIREFOX`	auto-detected	Firefox executable for `browser: "firefox"`.
`BROWSPARK_ZEN`	auto-detected	Zen executable for `browser: "zen"`.
`BROWSPARK_PROFILE`	`~/.browspark/profile`	Profile directory of the default Chrome developer context.
`BROWSPARK_PROFILES`	`~/.browspark/profiles`	Parent directory for named Chrome profiles and the `.brave/<context>`, `.firefox/<context>` and `.zen/<context>` profiles.
`BROWSPARK_ARTIFACTS`	`~/.browspark/artifacts`	Where traces, profiles, snapshots, HAR files, PDFs and reports are written.

browserPath overrides executable detection for the selected browser. Existing chromePath and firefoxPath launch options remain supported. The full list is in the CLI and environment reference.

The extension

Use the Chromium package for Chrome and Brave, or the Firefox package for Firefox and Zen. The Firefox extension shares existing tabs with documented limits; separate developer sessions use WebDriver BiDi for broader browser automation.

Release zip
Unpacked from source
Packaged zip
Firefox or Zen

Download browspark-chrome-extension.zip from the latest release, unzip it, then chrome://extensions (Chrome) or brave://extensions (Brave) → Developer mode → Load unpacked → the unzipped folder. The setup script downloads and unzips it into ~/browspark-extension; load it in each browser profile you want to connect.

bun run build

Then chrome://extensions (Chrome) or brave://extensions (Brave) → Developer mode → Load unpacked → the dist/chromium-extension/ folder. Reload the extension in each profile after every bun run build.

bun run package
# → dist/browspark-chrome-extension.zip (Chromium)
# → dist/browspark-firefox-extension.zip (Firefox / Zen)

Unzip the Chromium archive anywhere and load that folder unpacked. Use the Firefox instructions in the next tab for its archive.

Build the current source with bun install && bun run package. Open about:debugging#/runtime/this-firefox, choose Load Temporary Add-on, and select dist/firefox-extension/manifest.json or dist/browspark-firefox-extension.zip.Use Firefox 153+ or a Zen build based on Firefox 153+. Register the companion from the same checkout with command bun and the absolute path to companion/src/index.ts. Open the dashboard, enable user scripts when prompted and share your tabs. This unsigned build must be loaded again after restarting the browser; permanent installation in standard Firefox needs Mozilla signing. See Firefox extension setup.

The Chromium extension asks for six permissions: debugger (drive tabs), tabs (list and open them), storage (settings and the shared list), alarms (idle detach timer and update checks), downloads (report downloads) and notifications (one notice per new release). It has no host permissions. The Firefox extension uses tabs, storage, alarms, downloads, notifications, access to all websites (<all_urls>) for Firefox’s native screenshot API, and an optional userScripts permission that you enable in the dashboard. Firefox automation remains limited to HTTP/HTTPS tabs. Both extensions enforce sharing before page commands. Load the matching extension in each browser profile you want to connect. Chrome, Brave, Firefox and Zen profiles can stay connected together. Each dashboard controls sharing for its own profile; connecting another browser does not replace an existing connection. browser_status and browser_tabs show the browserId to select when opening tabs. See using multiple browsers.

Connecting the extension

The extension connects to 127.0.0.1:9223 on its own as soon as it is loaded; there is nothing to enter. If you run the companion with --port, set the same port under Settings → Companion → Bridge port. There is no pairing token. The companion listens on localhost only and refuses connections that carry a web page’s Origin header, so sites you visit cannot reach it; extensions and native MCP clients can.

Updating

The companion updates itself: bunx browspark-mcp@latest resolves the newest version each time the client starts it. The extension updates from its dashboard. The companion checks Browspark’s GitHub releases (at most every 6 hours) and, when a newer release is out, the extension shows a NEW badge on its toolbar icon, one desktop notification, and an Update available dialog in the dashboard. Choose Update now and the companion downloads the archive for your browser (browspark-chrome-extension.zip or browspark-firefox-extension.zip), checks that it is that browser’s Browspark build of the announced version, and replaces the files in the folder the extension was loaded from. The extension then reloads itself and the dashboard comes back on the new version. Tabs you shared stay shared, and agents keep their tab IDs. The folder keeps its name and location, whatever it is: ~/browspark-extension from the setup script, an unzipped browspark-chrome-extension or browspark-firefox-extension folder in your home, Downloads, Desktop or Documents folder, or a folder you used before. Chromium names an unpacked extension after its folder, so the companion always updates the exact folder the browser loaded. If it cannot find the folder, the dialog asks for it; copy it from your browser’s extensions page (Loaded from) or from about:debugging in Firefox. Choose Later to postpone a release; Settings → Updates shows the version, the install location and a Check now button, and can turn checks off.

Chromium reloads an unpacked extension only while Developer mode is on in chrome://extensions; it is on whenever you load one. Firefox keeps temporary add-ons only until it restarts, and a newer extension can need a newer companion: restart your MCP client so bunx starts the latest one.

Builds from a source checkout are never updated from a release. Update those with:

git pull
bun install
bun run build

Then reload the extension in every connected browser profile (chrome://extensions in Chrome, brave://extensions in Brave, about:debugging in Firefox or Zen). The dashboard shows a banner when the extension files on disk are newer than the running background process. Set BROWSPARK_UPDATE_CHECK=0 in the companion’s environment to stop all update checks.

Get started

Connect an agent

Concepts

Dashboard

Guides

Reference

Requirements

One-command setup

The companion

Single-file build

Flags and environment

The extension

Connecting the extension

Updating

​Requirements

​One-command setup

​The companion

​Single-file build

​Flags and environment

​The extension

​Connecting the extension

​Updating

Requirements

One-command setup

The companion

Single-file build

Flags and environment

The extension

Connecting the extension

Updating