Firefox and Zen support

Firefox and Zen have two connection options. The Firefox extension shares existing tabs and signed-in sessions through the same dashboard as Chromium. Developer mode launches a separate profile through WebDriver BiDi. Both keep the same MCP tool names, with different capability limits.

Install the Firefox extension

Use Firefox 153 or later, or a Zen build based on Firefox 153 or later. Build the current source:

git clone https://github.com/uncaughterrs/browspark.git
cd browspark
bun install
bun run package

This creates dist/firefox-extension/ and dist/browspark-firefox-extension.zip. The separate dist/browspark-extension.zip is for Chromium.

Open about:debugging#/runtime/this-firefox in Firefox or Zen.
Choose Load Temporary Add-on and select dist/firefox-extension/manifest.json or the Firefox ZIP.
Register the companion from the same source revision with your MCP client: use command bun and the absolute path to companion/src/index.ts as its argument. This keeps the extension and companion protocol versions aligned before a release is published.
Open the Browspark toolbar icon. If shown, choose Allow website access, then Enable Firefox automation to grant user-script permission. Share the HTTP or HTTPS tabs the agent may access.
Ask the agent to call browser_status, then use the listed tabId or choose the Firefox profile’s browserId when opening a new tab.

The package is unsigned. Temporary installation lasts until the browser restarts; reload it through about:debugging afterwards. Permanent installation in standard Firefox needs Mozilla signing. See Mozilla’s temporary installation instructions. The extension requests access to all websites (<all_urls>) because Firefox requires this permission for native tab screenshots, plus user-script execution for page automation. Browspark still limits automation to shared HTTP/HTTPS tabs and checks sharing before each command. It connects to your local companion; content returned to your MCP client may be processed by your chosen AI provider. Firefox browser pages, add-on pages, protected Mozilla sites and local files are unavailable.

Extension tool coverage

The extension provides shared-tab automation through Firefox WebExtension APIs and a sandboxed user-script world. It does not expose a native debugger. See the coverage notes below before choosing between an existing shared tab and a separate developer profile.

Area	Firefox and Zen extension behavior
Tabs	List, open, close and activate shared tabs; navigation, reload, back and forward.
Page content	Snapshots and refs, reading, extraction, waits and DOM inspection/editing. Same-origin frame DOM is accessible; cross-origin frames are not.
JavaScript	Evaluation in an isolated user-script world, with DOM access but without the page’s JavaScript globals or extension APIs.
Interaction	Ordinary left clicks, simulated keyboard events, filling, selection and scrolling. Hover, drag, non-left clicks, multiple clicks and click modifiers are unavailable. Events are untrusted (`isTrusted: false`); websites that require native input can reject them.
Screenshots	Capture the selected tab through Firefox’s tab-capture API.
Stop controls	Unshare or stop access in the dashboard. The in-page agent overlay is unavailable.
Network, cookies and console	Network capture/interception, network-backed policies, browser cookie APIs and console collection are unavailable. Page DOM APIs remain available through evaluation.
Files and dialogs	Download tracking, PDF printing, native file upload and JavaScript dialog handling are unavailable.
Developer tools	Raw CDP, Lighthouse, debugger control, early-document scripts, Chrome tracing/profiling and other native DevTools operations are unavailable.

All 43 tool names remain registered. Unsupported actions return explicit errors for the selected Firefox extension tab. Use a separate Firefox or Zen developer session when you need supported BiDi capabilities such as native input or network inspection; that session has its own profile and logins. Use Chromium developer mode for CDP or Lighthouse.

Launch a separate Firefox or Zen developer browser

Install the browser, register the companion, and ask your agent to open a Firefox or Zen developer session. For Firefox it calls browser_session with:

{
  "action": "launch",
  "browser": "firefox",
  "context": "firefox",
  "userRequested": true,
  "url": "https://example.com"
}

For Zen, change browser to "zen" and use its own context, such as "zen". You can run both alongside Chrome and Brave. Use a returned tab ID with browser_snapshot, browser_click, browser_read, or another tool. When opening another tab, specify mode: "dev" and the intended context. See using multiple browsers. browserPath selects the executable for the chosen browser. Set BROWSPARK_FIREFOX for Firefox or BROWSPARK_ZEN for Zen in your MCP server’s environment; the existing firefoxPath option remains supported. Other Firefox-based browsers, such as LibreWolf, can be selected with browser: "firefox" and an executable path when their build enables WebDriver BiDi. Custom builds may disable remote automation or omit commands; an executable path does not guarantee the same capabilities in every fork. Profiles persist under ~/.browspark/profiles/.firefox/<context> for Firefox and ~/.browspark/profiles/.zen/<context> for Zen (under BROWSPARK_PROFILES when set). They are separate from each other and from Chromium profiles, including the default context. A context name can belong to only one running browser at a time. Pass the matching browser when deleting a stopped context.

Developer-mode tool coverage

Unsupported actions return an explicit error. They do not silently run in Chrome or substitute results from another browser.

Area	Firefox and Zen behavior
Tabs and navigation	Launch, list, open, close, activate, navigate, reload, back and forward.
Page content	Snapshots and refs, text/markdown/HTML reading, extraction, waits, and JavaScript evaluation.
Interaction	Mouse, keyboard, forms, selection, scrolling, file upload, and JavaScript dialogs.
Output	Viewport, full-page and element screenshots; PDF printing.
Downloads	Download tracking and saved file paths when the selected build supports BiDi download events.
Console	Console messages and exceptions collected during a devtools session; evaluation and inspection of live objects returned by `devtools_evaluate` with `returnByValue:false`. Logged objects have searchable snapshot previews; Firefox does not provide live handles for those logged snapshots.
Elements	Search, inspect and edit HTML/attributes by ref or selector; inline style edits and computed styles. Matched rules, box models, event listeners, forced pseudo states and DevTools overlays are unavailable.
Accessibility	`devtools_accessibility` with `action: "check"` runs DOM-based checks. Browser accessibility trees and Chrome issue reports are unavailable.
Network	Request/response logs, headers, status, timing, HAR, cache control, blocking, mocks, resource overrides, and domain policies. Response bodies depend on the browser’s BiDi data-collection support.
Storage	Cookies in the selected context; local/session storage, IndexedDB and Cache Storage through page APIs.
Sources and workers	Frame/context listing and resource overrides; page-based service-worker list/update/unregister. Script inventories, source maps and worker debugging are unavailable.
Page metrics	`devtools_performance` with `action: "vitals"` reports the metrics exposed by Firefox’s page APIs.
Raw CDP and Lighthouse	Unavailable. `devtools_cdp` and `devtools_lighthouse` require Chromium.
Advanced Chrome DevTools	Chrome traces, V8 heap snapshots and CPU profiles, debugger breakpoints/stepping, precise JS/CSS coverage, and Chrome-specific emulation or browser issue reports are unavailable.

Network capture does not include WebSocket/SSE frames, TLS certificate details, remote IPs, or Chrome initiator stacks. Network throttling and service-worker bypass are unavailable. Replaying a request with a body requires its body to be supplied explicitly when the original was not captured. Literal multiline text in browser_fill or the text argument of browser_key is unavailable in Firefox and Zen; it returns an error before typing. Ordinary text and explicit keyboard actions use native browser input. These developer-mode limits apply to both Firefox and Zen. The generated CDP capability matrix describes Chromium only. devtools_capabilities reports the selected tab’s backend and capabilities; a supported domain does not imply that every Chrome command in it is available.

Launch options

headless: true runs the browser without a window. Use screenshots to inspect it; the Chrome live screencast is unavailable.
proxy accepts an HTTP or SOCKS proxy without embedded credentials.
args passes additional command-line switches to the selected browser.
devtools: true and unpacked extensions are unavailable on Firefox and Zen and return an error.

Closing a session keeps its profile. The companion closes browsers it launched when it exits, as in developer mode.

Get started

Connect an agent

Concepts

Dashboard

Guides

Reference

Firefox and Zen support

Install the Firefox extension

Extension tool coverage

Launch a separate Firefox or Zen developer browser

Developer-mode tool coverage

Launch options

​Install the Firefox extension

​Extension tool coverage

​Launch a separate Firefox or Zen developer browser

​Developer-mode tool coverage

​Launch options

Install the Firefox extension

Extension tool coverage

Launch a separate Firefox or Zen developer browser

Developer-mode tool coverage

Launch options