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.

Related MCP server: ruyipage-mcp

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.