fire-fodex

fire-fodex is a local Firefox bridge for MCP agents.

It lets an agent see open Firefox tabs, claim one, read a compact page snapshot, click, type, scroll, take screenshots, and run a small set of page-side actions.

This is not a Chrome plugin clone. It is a separate Firefox setup built with a WebExtension, Firefox native messaging, and a local MCP server.

v1 is still shaped like a local dev tool. You load the extension manually, run the MCP server yourself, and should read the code before pointing it at anything important.

What works

• Lists open Firefox tabs.
• Opens or claims a tab for an agent session.
• Navigates, reloads, goes back, and goes forward.
• Reads a compact DOM snapshot from the visible page.
• Finds visible text.
• Clicks, types, pastes, focuses, selects text, and sends keypresses.
• Moves the mouse, scrolls, and drags.
• Waits for text or selectors.
• Captures screenshots, including full-page screenshots.
• Exposes the actions as MCP tools.

What it does not do

• It does not read Firefox cookies, saved passwords, profile databases, or localStorage directly.
• It does not send browser data to a remote service by itself.
• It does not include cloud sync, account auth, recording, or a permission UI.
• It is not packaged for AMO yet.

firefox_eval exists for local page automation. It blocks obvious cookie, storage, and password extraction patterns, but do not treat that as a real sandbox. If you run random agent code against your main browser profile, that is on you.

Requirements

• Windows
• Firefox Stable
• Node.js 24+
• npm 11+

Setup

cd path\to\fire-fodex
npm install
npm run build
npm run install:host

Load the extension:

1. Open Firefox.
2. Go to about:debugging#/runtime/this-firefox.
3. Click Load Temporary Add-on....
4. Select extension\manifest.json from this repository.

Start the MCP server:

npm run mcp

MCP client config:

{
  "mcpServers": {
    "fire-fodex": {
      "command": "node",
      "args": [
        "path\\to\\fire-fodex\\dist\\mcp-server\\index.js"
      ]
    }
  }
}

Tools

• firefox_list_tabs
• firefox_claim_tab
• firefox_open_tab
• firefox_navigate
• firefox_snapshot
• firefox_screenshot
• firefox_find
• firefox_wait_for
• firefox_mouse_click
• firefox_mouse_move
• firefox_scroll
• firefox_drag
• firefox_focus
• firefox_select_text
• firefox_paste
• firefox_eval
• firefox_click
• firefox_type
• firefox_keypress
• firefox_back
• firefox_forward
• firefox_reload
• firefox_close_tab
• firefox_release

The free-operation tools are meant to let an agent work closer to how a person uses a browser:

• Use firefox_snapshot or firefox_find to discover visible controls.
• Use firefox_focus, firefox_paste, firefox_type, firefox_select_text, and firefox_keypress for form work.
• Use firefox_mouse_move, firefox_mouse_click, firefox_scroll, and firefox_drag for pointer-style interaction.
• Use firefox_wait_for after actions that change the page.
• Use firefox_screenshot with fullPage or crop coordinates when visual state matters.
• Use firefox_eval for local page automation scripts. It blocks obvious cookie, storage, and password extraction patterns.

Verification

npm run typecheck
npm test
npm run lint:extension
npm run check
powershell -ExecutionPolicy Bypass -File scripts\smoke.ps1

smoke.ps1 requires the native host to be installed and the Firefox extension to be loaded.

Permission Model

The extension asks for <all_urls> because the goal is to operate normal tabs across normal sites.

That is a big permission. This project is meant to be run from source by people who understand that tradeoff.

Architecture

AI agent / MCP client
        |
        | stdio MCP
        v
fire-fodex MCP server
        |
        | localhost JSON request
        v
native messaging host
        |
        | Firefox native messaging stdio
        v
Firefox WebExtension
        |
        | tabs + content scripts
        v
Firefox tabs

The native host listens on 127.0.0.1:17365 while the extension is connected.