LibreWolf Agent Bridge

Local-first Model Context Protocol (MCP) browser automation for LibreWolf. It wraps the pinned Mozilla @mozilla/firefox-devtools-mcp process; it is not a LibreWolf or Firefox fork and is not affiliated with Mozilla, LibreWolf, OpenAI, or Anthropic.

Current status

The controlled-profile design is the supported path. It launches a dedicated, app-owned LibreWolf profile and exposes a deliberately small browser_* MCP surface. Browser data stays on the local machine except for normal browser traffic to sites you choose.

The repository contains a locally verified source distribution and reproducible release assembly. Build the declared MCP CLI before configuring a client; the preflight in the setup below confirms that the server and its Windows process supervisor were produced.

The optional companion package can connect an explicitly approved existing LibreWolf session on Windows. It must be installed from a complete native-host payload: its secure helper enforces same-user named-pipe checks, and browser_status reports the final capability state. Linux, macOS, and Flatpak LibreWolf should use controlled mode because this hardened companion transport is Windows-only.

No artifact is deployed by this project.

Fastest path: Claude Desktop one-click

npm ci
npm run package:all

Open the resulting artifacts/librewolf-agent-bridge-<version>.mcpb with Claude Desktop, then call browser_status. No config file to edit and no dependency install: the bundle carries the server, the pinned Mozilla upstream, GeckoDriver, and the Windows secure helper. Use the manual setup below for Codex, Claude Code, ChatGPT Desktop, or when you want the checkout itself to be the server.

Five-minute controlled setup (Windows)

1. Install LibreWolf and Node 20.19.0 or newer. The compatibility check was run with LibreWolf 146.0-2; Node 20.18.2 is known to be too old for the pinned Mozilla dependency.

2. In an elevated-free PowerShell window, clone the repository and install its locked dependencies:

   git clone <your-fork-or-checkout-url> librewolf-agent-bridge
   Set-Location librewolf-agent-bridge
   node --version
   npm ci
   npm run build
   Test-Path .\apps\mcp-server\dist\cli.js
   Test-Path .\apps\mcp-server\dist\native\secure-pipe-helper.exe
   

   Both checks must print True. If either does not, stop and inspect the build output before configuring a client.

3. Configure one of the clients below, replacing the absolute path. Each example launches a local process over stdio and creates a separate controlled profile; it does not attach to your everyday browser profile.

   For Codex, add this to %USERPROFILE%\.codex\config.toml:

   [mcp_servers.librewolf-agent-bridge]
   command = "node"
   args = ['C:/absolute/path/to/librewolf-agent-bridge/apps/mcp-server/dist/cli.js']
   startup_timeout_sec = 90
   

   For Claude Desktop, add this server to its MCP configuration:

   {
     "mcpServers": {
       "librewolf-agent-bridge": {
         "command": "node",
         "args": ["C:\\absolute\\path\\to\\librewolf-agent-bridge\\apps\\mcp-server\\dist\\cli.js"]
       }
     }
   }
   

4. Restart or reconnect your MCP client, then call browser_status. Confirm the reported mode is controlled and inspect its capabilities before browsing.

See Windows installation, security, and troubleshooting before using credentials or downloads. ACCEPTANCE.md records what has been verified, how to re-run it, and what remains open.

What the server can do

The public surface contains status and tab control, navigation, compact snapshots and text lookup, UID-based input, screenshots, console and network inspection, downloads, and bounded batches. Its exact names and input contracts are documented in the protocol reference. State-changing actions, uploads, downloads, tab closing, and batches deserve explicit user confirmation in the MCP client.

Controlled mode supports delta snapshots. Companion actions briefly highlight their target in the page; controlled-mode highlighting is limited to native hover state and is reported as degraded. Screen recording is explicitly unavailable on the tested LibreWolf 146.0-2 because the pinned upstream screencast requires Firefox 154 or newer. The extension popup and options page show connection and permission state; an optional persistent sidebar is not shipped.

Distribution inputs

• packaging/codex-plugin/ — Codex plugin template.
• packaging/claude-mcpb/ — Claude Desktop MCPB source using manifest 0.3. npm run package:all turns it into a self-contained installable .mcpb carrying the server, the pinned Mozilla upstream, GeckoDriver, and the secure helper.
• packaging/windows/ — native host and secure-helper installation/removal scripts (dry-run by default).
• packaging/linux/ and packaging/macos/ — per-user native-messaging registration templates; they do not add Windows-only secure companion transport.
• scripts/package-artifacts.mjs — deterministic local artifact collector. It makes no installation, registry, network, or deployment changes.

Run npm run package:all only from a build-ready checkout. It emits an artifact manifest and SHA-256 checksums under artifacts/, or exits with a specific missing-prerequisite error. The complete release matrix is assembled on Windows because the npm, Codex, MCPB, and Windows archives include the compiled Windows Job Object/secure-pipe helper. Linux and macOS users can build and run controlled mode locally, but their source hosts do not produce that complete release matrix.

Development

Read architecture, performance profiling, contributing, and compatibility evidence. Source code is Apache-2.0; see third-party notices.