<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**](https://nodejs.org) (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:

```json
{
  "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](https://github.com/sinamohsenifar/foxbridge-mcp/releases) and open it.

**From source (any OS):**
```bash
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](https://github.com/sinamohsenifar/foxbridge-mcp/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](https://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

```bash
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:

```bash
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