FoxBridge MCP

<p align="center"> <img src="https://raw.githubusercontent.com/sinamohsenifar/foxbridge-mcp/main/assets/wordmark.png" width="460" alt="FoxBridge — drive your real Firefox from an AI assistant"> </p>

<p align="center"> <a href="https://www.npmjs.com/package/foxbridge-mcp"><img src="https://img.shields.io/npm/v/foxbridge-mcp?color=FF7A18" alt="npm"></a> <img src="https://img.shields.io/badge/license-MIT-2B2D31" alt="MIT"> <img src="https://img.shields.io/badge/MCP-server-FF7A18" alt="MCP"> <img src="https://img.shields.io/badge/Firefox-extension-F03B1E" alt="Firefox extension"> </p>

Read and drive your real, logged-in Firefox from an AI assistant — over the Model Context Protocol (MCP).

FoxBridge is two coordinated pieces:

• An MCP server (foxbridge-mcp, this npm package) — reads your on-disk Firefox profile (cookies, history, sessions, localStorage) with zero native dependencies (Node's built-in node:sqlite), and hosts a local WebSocket bridge.
• A Firefox extension ("FoxBridge") — runs inside your real browser and executes the server's commands with genuine WebExtension APIs, so the assistant drives your actual, logged-in tabs.

Everything runs locally. The extension sends nothing anywhere on its own.

⚠️ Security: FoxBridge grants total read/drive access to your logged-in browser sessions — live cookies (incl. httpOnly session tokens), storage, history, and the ability to act as you on any site. Only run it with an assistant you trust, and understand that any data the assistant reads goes to that assistant. Keep it local; treat cookie/token output as credentials.

What it can do

Drive your real Firefox (via the extension — ff_* tools): ff_status, ff_list_tabs, ff_open_tab, ff_activate_tab, ff_close_tab, ff_navigate, ff_reload, ff_read_page, ff_click, ff_type, ff_scroll, ff_wait_for, ff_eval, ff_fetch (call site APIs as you), ff_download (save files with your auth), ff_network (see the tab's live XHR/fetch calls), ff_get_cookies (incl. httpOnly).

Demo

Ask your MCP client (Claude, etc.) things like:

> Search Google for "playwright vs puppeteer" and summarize the top 5 results.
   → opens a tab, reads the results, returns a summary

> Open my exchange dashboard, wait for the balance to load, and read it.
   → ff_navigate + ff_wait_for + ff_read_page (as the logged-in you)

> What API calls does this page make? Then call the balances endpoint and give me the JSON.
   → ff_network to discover the endpoint, then ff_fetch it with your cookies

> Download the PDF linked as "Invoice" on this page.
   → ff_download saves it to ~/Downloads using your session

Read the on-disk profile (no browser needed): list_profiles, get_cookies, get_history, get_bookmarks, get_sessions, get_local_storage, get_cache_info, clear_disk_cache.

Optional standalone Playwright browser (playwright is an optional dependency): browser_start, navigate, read_page, eval_js, tab/interaction tools. Not required for the ff_* or on-disk tools.

Install — Windows, macOS & Linux

FoxBridge is fully cross-platform. You install two parts: the MCP server (Node) and the Firefox extension. Do both.

Prerequisites (all OSes): Node.js ≥ 22.5 (for the built-in node:sqlite) and Firefox.

1. The MCP server

Recommended — via npx (works on Windows, macOS, Linux): add this to your MCP client config:

{
  "mcpServers": {
    "foxbridge": { "command": "npx", "args": ["-y", "foxbridge-mcp"] }
  }
}

Where that config file lives (Claude Desktop):

OS	Config path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

For Claude Code (any OS): claude mcp add foxbridge -- npx -y foxbridge-mcp.

One-click (Claude Desktop, any OS): download the .mcpb bundle from Releases and open it.

From source (any OS):

git clone https://github.com/sinamohsenifar/foxbridge-mcp.git
cd foxbridge-mcp
npm install        # Playwright is OPTIONAL and not downloaded
npm run build
# then point your MCP config command/args at:  node /abs/path/foxbridge-mcp/dist/index.js

2. The Firefox extension

Firefox extensions are OS-agnostic — the same signed .xpi works on Windows, macOS, and Linux.

1. Download foxbridge-extension-<version>.xpi from Releases.
2. In Firefox: open about:addons → gear ⚙️ → Install Add-on From File… → pick the .xpi.

Firefox Add-ons store: FoxBridge is submitted to addons.mozilla.org/firefox/addon/foxbridge and is pending Mozilla review. Once approved you can install & auto-update it straight from the store — no manual .xpi needed.

For development (any OS): about:debugging → This Firefox → Load Temporary Add-on → pick extension/manifest.json.

The extension auto-connects to the server on ws://127.0.0.1:8787. Verify with the ff_status tool.

Usage

Ask your assistant things like:

• "List my open Firefox tabs and read the active one."
• "Open my dashboard, wait for the balance to load, and read it."
• "Call this site's API as me and give me the JSON."

Configuration

• BRIDGE_PORT (env) — override the bridge port (default 8787). Useful to run isolated instances.

Development

npm install        # playwright is optional and NOT downloaded automatically
npm run build      # compile TypeScript -> dist/
npm start          # run the server on stdio

Extension packaging/signing:

npm run ext:build           # build an unsigned .xpi into dist-ext/
npm run ext:submit          # submit to AMO (listed) — needs AMO API creds

License

MIT © Sina Mohsenifar