Browspark

Give your AI agent a real browser.
One local MCP server for Chrome, Brave, Firefox and Zen, running side by side.

Website · Documentation

Agent work stays in the background by default. Change Settings → Work in background if an operation needs foreground interaction.

Install

Note

Browspark is in early release. If something breaks, please open an issue.

Requires Bun and a supported browser. Chrome, Brave, Firefox and Zen can share existing tabs through their matching extension; all four also support separate developer sessions.

Option 1: one command

Downloads the extension, registers the companion with the agents you pick, and walks you through the last steps. Add --test for a dry run that changes nothing.

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

Option 2: by hand

1. Register the companion with your MCP client. It is published on npm as browspark-mcp; no clone needed.

claude mcp add browspark -- bunx browspark-mcp@latest

Codex, OpenCode, Cursor, Antigravity, Muse Code and Hermes are covered in the connect guide.

2. Get the extension. Download browspark-chrome-extension.zip from the latest release and unzip it, or clone this repo and run bun install && bun run build to use the dist/chromium-extension/ folder. Open chrome://extensions in Chrome or brave://extensions in Brave, turn on Developer mode, choose Load unpacked and select that folder. Repeat in each browser profile you want to connect; they can all use the same companion.

3. Share tabs. Open each extension dashboard and share the tabs the agent may use. The Graph page shows agents and browsers on a draggable canvas with logos and animated connections; toggle it in Settings. Ask the agent to call browser_status to select a listed tabId or use its browserId when opening a new tab. Sharing permissions stay separate in each browser profile.

Updates. When a new release is out, the extension dashboard offers it and installs it into the folder you loaded, then reloads itself. See Updating.

Using Firefox or Zen? With Firefox 153+ or a Zen build based on Firefox 153+, run bun install && bun run package in this checkout. Open about:debugging#/runtime/this-firefox → Load Temporary Add-on → dist/firefox-extension/manifest.json (or dist/browspark-firefox-extension.zip). Register the matching source companion with command bun and the absolute path to companion/src/index.ts. Open Browspark, enable user scripts when prompted and share your existing tabs. This unsigned build needs loading again after a browser restart. See Firefox extension setup and exceptions.

What it does

• Extension mode. The agent drives shared tabs in Chrome, Brave, Firefox and Zen at the same time, keeping your signed-in sessions. Each browser enforces its own sharing permissions. Firefox and Zen use a separate extension build with documented automation and debugging limits.
• Developer mode. Launch separate Chrome, Brave, Firefox or Zen contexts with persistent profiles. Chromium browsers provide CDP and Lighthouse; Firefox and Zen use the same tool names for supported BiDi operations and report unsupported actions explicitly.
• Developer tools as first-class tools. Console, Network, Sources, Debugger, Elements, Performance, CPU and memory profiling, storage, service workers, coverage, emulation, accessibility, security, Lighthouse and a recorder that exports Playwright tests.

The full tool reference is at docs.browspark.krishm.dev/tools.

Development

bun install
bun run build            # Chromium extension/ + dist/firefox-extension/
bun run typecheck
bun run --cwd frontend build # build landing page before its smoke tests
bun test                 # unit, bridge and landing-page tests; no browsers
bun run docs:tools       # schema-validated tool reference
bun run test:e2e         # launches throwaway Chromium browsers
bun run test:firefox     # Firefox acceptance scenarios
bun run test:multi-browser # Chrome, Brave, Firefox and Zen together
bun run package          # Chromium and Firefox extension ZIPs in dist/
cd docs && bunx mint dev # preview the docs site

Install the browsers needed for each acceptance suite; the development guide lists executable overrides. Run browser suites one at a time.

Layout: companion/ (MCP server, transports, devtools modules), extension/ (MV3 dashboard and worker: shared/ source plus chromium/ and firefox/ manifests), shared/ (wire protocol), docs/ (Mintlify site), frontend/ (landing page), test-apps/ (deterministic pages for tests).

Contributing

Before contributing, please read the guidelines in CONTRIBUTING.md.

Credits

We believe in open source

Browspark exists because other people published their work for anyone to build on, and it is published under the same terms. Every line of the companion, the extension, the docs and the landing page is in this repository, so you can read exactly what runs on your machine and what touches your browser.

Model Context Protocol

The tools and the server are built on the Model Context Protocol and its TypeScript SDK. MCP is what lets one companion serve Claude Code, Codex, Cursor and every other client through the same interface.

Chromium

Chromium support uses the Chrome DevTools Protocol and the extension debugger API. The developer tools it exposes are the same ones the DevTools panels use. Firefox and Zen developer sessions use WebDriver BiDi.

Supabase

The dashboard and landing page take their visual direction from Supabase: a neutral dark palette, a single green accent, and interfaces that stay out of the way. Thanks for showing that developer tools can be calm and good looking.

License

Browspark is licensed under the MIT License. See LICENSE.