foxbidi
Drives Firefox over WebDriver BiDi, providing MCP tools for browser lifecycle and navigation, tab management, page snapshots and text extraction, screenshots, clicking and typing, key presses, scrolling, uploads, waiting, logs and network inspection, cookies, extensions, request interception, dialog handling, CAPTCHA status, and runtime capability probing.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
foxbidi
A Node MCP server that drives Firefox over WebDriver BiDi.
中文版:README.zh-CN.md
Firefox removed its experimental CDP implementation at the end of 2024, which left
WebDriver BiDi as the only protocol it exposes for automation. foxbidi
implements that protocol — WebSocket framing and the BiDi session layer are both
hand-rolled on node:net — and exposes the browser through 43 MCP tools.
It runs as a plain stdio MCP server, so any MCP client can attach to it. The same code is also packaged as a MiniMax Code plugin; the host side of that integration is documented separately in docs/mcode-plugin.md.
Design
No runtime npm dependencies. The only npm packages in the repository are ESLint and Prettier, and both are devDependencies.
The session runs against a copy of a Firefox profile. Cookies and logins in that profile are available to the session. Tabs are not shared with a running Firefox, and the copy is a snapshot.
Input is delivered as browser events. Clicks are pointer events (
pointerMove → pointerDown → pointerUp) and typing sends one key action per character, rather than synthetic DOM events.Every action returns an
effectblock.effect.verifiedistrueonly when the URL or the DOM fingerprint changed.Dialogs are closed and reported. A JavaScript
alert()blocks Firefox; the plugin closes it and returns what it said.Capabilities are probed at runtime. The tool set is probed against the running browser, so one build works on Firefox 118 and on Firefox 150. Missing features are reported as
capability_unavailable.
Related MCP server: foxwire
Requirements
Node ≥ 20 and Firefox 118+ (140 ESR is the verified configuration). The browser is launched on demand, on the first tool call that needs it.
Install
As a plain MCP server
{
"mcpServers": {
"foxbidi": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/foxbidi/server.js"]
}
}
}As a MiniMax Code plugin
Clone the repository into the host's plugin directory; the host scans that directory and starts the server itself:
git clone https://github.com/DsDG1/foxbidi.git ~/.minimax/plugins/foxbidiThe package layout, the host's package contract and the failure modes that keep a plugin from being loaded are documented in docs/mcode-plugin.md.
How it works
Package layout
foxbidi/
server.js # MCP server entry point
lib/bidi/ # WebDriver BiDi protocol layer
lib/firefox/ # profile handling, launching, the provider
lib/mcp/ # output schemas and the tool catalogue
skills/firefox-browser/ # the guide the agent reads
tools/ # CLI entry point and package tooling
docs/ # reference documentsThe MCP server
The server speaks MCP over stdin/stdout. It builds the tool catalogue from
lib/mcp/tools/, answers tools/list and tools/call, and starts the browser
on the first call that needs it.
The tool catalogue and presets
Every tool definition is injected into the model's context on every turn, so the catalogue is a permanent context cost rather than a one-off. The server therefore ships presets and picks one automatically:
Preset | Tools | Contents |
| 24 | the everyday loop |
| 36 | + fine-grained input, logs, assertions, cookies |
| 43 | + the Firefox-only family, CAPTCHA, egress |
| 43 | everything |
Switch with browser_config({preset: "all"}).
The agent guide
skills/firefox-browser/SKILL.md is read by the agent, not by the user. It
carries the operating rules: take a snapshot first, act on a ref, read the
effect block, branch on code rather than on error, never route around the
confirmation gate. REFERENCE.md next to it is the parameter reference and the
full error vocabulary.
Why a profile copy instead of attaching to a running Firefox
--remote-debugging-port is a startup flag: a running Firefox cannot be given
a BiDi endpoint afterwards, and the running instance holds an exclusive lock on
its profile. Copying the profile and launching a second instance against the
copy is therefore the only way to drive a Firefox that carries a real session.
The copy is a snapshot — tabs are not shared.
When the machine has no Firefox profile at all — Firefox installed but never
launched, so no profiles.ini and no profile directory — the plugin does not
give up: it creates a fresh, empty profile and drives that. A CI runner, a
container or a new laptop is a perfectly normal place to run this.
The CLI entry point
Tools normally reach the agent through an MCP client. The repository also ships a direct entry point that needs no client configuration:
node tools/ff-call.mjs browser_status '{}' # call any tool
node tools/ff-call.mjs --doctor # what works, what does not
node tools/ff-call.mjs --serve # start the long-lived server
node tools/ff-call.mjs --stop # stop itA call needs a server on the other end of the control socket. When none is running, the call starts one: a detached daemon that survives the shell that started it and keeps one Firefox alive across calls. The daemon is started with no stdin at all, because a stdio transport treats EOF as "the client is gone" — a server that reads stdin kills itself the moment it is detached.
The control socket is off by default for a stdio server. With
FIREFOX_BROWSER_CONTROL_SOCKET=1 the server also listens on control.sock
(0600) in the data directory, speaking the same JSON-RPC to the same provider —
the same Firefox, the same tabs. A server that finds the socket already served
by a live peer steps aside instead of taking it over: two servers would mean
two Firefoxes, and the BiDi session allows only one.
--doctor reports the plugin version, the control socket, the browser state and
whether this machine can resolve and reach the outside world. On MiniMax Code it
also compares the host's tool registry against this build; see
docs/mcode-plugin.md.
The runtime data directory
The profile copy, the control socket, the audit log and the screenshot server
live in a data directory outside the package. It is resolved in this order:
FIREFOX_BROWSER_PROFILE_COPY, then PLUGIN_DATA, then
<package root>/../.plugin-data/firefox-browser, then
~/.minimax/v2/plugin-data/agent-plugins/firefox-browser.
Screenshots
browser_screenshot returns the PNG as an MCP image content block, so the
model receives the image natively and the bytes never become text tokens. The
result also carries an imageUrl: the screenshot is served by a small HTTP
server bound to 127.0.0.1, under a path with a 192-bit random token. A client
that renders markdown turns
into a visible picture. Only the ~120-character URL travels through the model's reply.
Tools
43 tools, grouped by what they are for:
Group | Tools |
Lifecycle |
|
Reading |
|
Actions |
|
Workflow |
|
Firefox-only |
|
Network |
|
CAPTCHA |
|
Full parameter reference:
skills/firefox-browser/REFERENCE.md.
Firefox-only tools
These exist because the server drives Firefox itself:
Tool | What it does |
| Firefox containers — isolated cookies, localStorage and cache per identity |
| Install and uninstall WebExtensions |
| Read and write cookies, including HttpOnly ones |
| Block requests by URL; every request is released again, so the page never freezes |
| Measure how detectable this session is |
The working loop
browser_snapshot → act on a ref → read the effect blockSafety and the error contract
The confirmation gate. Actions that cannot be undone — submitting a form, downloading, uploading, installing an extension, writing a cookie — are refused unless the caller passes
confirm: true. Classification uses DOM facts, not button text, because a Chinese site labels a search button 搜索 and an English site labels a harmless button OK.The error contract. A failure carries both
code(a fixed, machine-readable word) anderror(a human-readable sentence). Branch oncode; matching an English sentence means matching its wording.Redaction. Cookies, passwords, one-time codes and tokens are redacted on every outbound channel.
Untrusted page content. If a page hides instructions in the DOM for the agent — off-screen text, white-on-white, 1px fonts — the plugin reports it as untrusted content instead of acting on it.
Configuration
All settings are environment variables; the MCP server inherits HOME, PATH
and the rest from the host.
Variable | Default | Meaning |
| auto-detected | Path to the Firefox binary. |
|
| Preferred BiDi port; occupied ports are probed upward. |
|
| Set to |
| auto-detected | Source profile; prefers the one a running Firefox holds. |
| — | Base directory for the profile copy. |
|
| Per-BiDi-command timeout. |
|
|
|
| — | JSON object of prefs applied to the profile copy only. |
|
| Where |
Development
npm test # unit + integration tests
npm run test:unit # unit tests only — no browser needed
npm run test:integration# launches a real Firefox
npm run lint # ESLint
npm run format:check # Prettier
npm run validate # validate the plugin packageNo runtime npm dependencies; ESLint and Prettier are devDependencies only.
Documentation
Document | What it covers |
Which Firefox version each feature needs | |
The optional solver | |
Host integration and package contract | |
How an agent should drive it |
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
Unofficial Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server for the Firefox you actually use: an add-on plus a small native helper, so an agent gets your real profile, tabs and logged-in sessions instead of a blank headless browser. 45 tools for tabs, accessibility snapshots with refs, clicking, typing, screenshots, bookmarks, history and downloads.9Mozilla Public 2.0
- AlicenseNot gradedqualityBmaintenanceEnables an MCP client to drive a real, already-logged-in Firefox session through a WebExtension rather than a WebDriver connection, so tabs, cookies and logins work as-is without relaunching the browser under remote-control flags. Exposes tools for tab listing and selection, navigation, accessibility-style snapshots, clicking, filling, typing, key presses, file uploads, screenshots and waiting, with per-origin permission grants and opt-in script evaluation.MIT
- AlicenseNot gradedqualityAmaintenanceExposes a 47-tool browser automation surface to MCP clients, enabling AI agents to navigate, interact with, observe, and extract content from web pages across multi-tab sessions. Runs on Camoufox-based anti-detection behavior so agents can automate sites that block conventional headless browsers, with session persistence, cookie import, and stdio or HTTP transport.581 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables an LLM to drive a real browser by declaring one desired outcome at a time, while a separate typesafe decision model picks the element, action, value, and whether the step is done, blocked, or irreversible. Exposes tools for navigation, acting, checking, reading page content, screenshots, and invoking page-registered WebMCP tools.1,464 npmMIT