Agent Bridge for Tab Management in Firefox

简体中文

A local-first toolkit that gives trusted AI agents precise access to tabs and native tab groups in the user's live Firefox session.

This repository distributes three cooperating components:

The MCP server provides the capability. The Agent Skill provides behavior guidance. The browser extension is the only component that talks to Firefox. They are complementary, not alternatives.

What it can do

• List live tabs and native tab groups with stable IDs.

• Open explicit http:// and https:// URLs without stealing focus by default.

• Create an exactly named group from ungrouped tabs in one window.

• Move a precisely selected tab into an existing group.

• Ungroup a precisely selected tab.

• Reject ambiguous matches, duplicate group names, cross-window grouping, and implicit unpinning.

• Read Firefox state again after every write and report success only after verification.

It does not read page bodies, inject content scripts, execute arbitrary page JavaScript, inspect cookies, or send browser data to a project-operated remote service.

Related MCP server: mcp-browser

A practical workflow: collect now, read later

Suppose you come across useful articles, documentation, or research links while browsing a feed, chatting, or working on another device. You want to read them carefully later in desktop Firefox, but opening and organizing every page yourself would interrupt the current task and leave the browser full of loose tabs.

Send the URLs to a connected agent such as Hermes instead:

Open these URLs in Firefox in the background. Put every new tab in the exact
group "Reading Queue", creating that group only if it does not exist, and
verify the final tab and group IDs.

The agent opens the pages without taking focus and keeps them together in one dedicated group. You can continue what you are doing, then later sit down at the computer and work through the group as a focused reading queue. This turns Firefox tab groups into an inbox for the web: less clutter, less context switching, and less time spent manually organizing tabs.

Five-minute setup

Version 0.3.1 includes a Mozilla-reviewed and production-signed XPI in the GitHub Release. It upgrades v0.3.0 in place under the same signed Gecko ID, preserving the extension's local settings while adopting the current Tab Management Agent Bridge for Firefox name.

1. Install the signed extension

1. Download tab_management_agent_bridge_for_firefox-0.3.1-mozilla-signed.xpi from the v0.3.1 Release.

2. Open the XPI with Firefox and approve the installation prompt.

3. The Mozilla-signed extension remains installed after Firefox restarts.

2. Clone and prepare the MCP server and Skill

git clone https://github.com/Johnnyzlee/agent-bridge-for-tab-management-in-firefox.git
cd agent-bridge-for-tab-management-in-firefox
npm run quickstart

quickstart installs the locked dependencies, builds the MCP server and a development copy of the extension, preserves an existing local token when rerun, and generates:

• .local/bridge-token.txt

• .local/mcp-config.json

• dist/server/index.js

• dist/firefox-extension/manifest.json

The .local/ directory is ignored by Git. Treat its token as a local secret.

3. Configure the extension

Open Tab Management Agent Bridge for Firefox preferences, keep port 8765, paste the token from .local/bridge-token.txt, and select Save and reconnect.

For source development only, you may instead open about:debugging#/runtime/this-firefox, select Load Temporary Add-on, and choose dist/firefox-extension/manifest.json. Firefox removes that temporary build after each restart; do not load it alongside the signed extension on the same port.

4. Connect an MCP client

For clients using the common mcpServers JSON format, merge the generated .local/mcp-config.json into the client's configuration and restart the client.

For Codex, run the generated helper and then restart Codex:

.local/add-to-codex.sh

PowerShell users can run .local/add-to-codex.ps1. These ignored local files contain the token, so do not share them. If an MCP entry named firefox-tabs already exists, remove or update that old entry before running the helper.

The equivalent generic configuration is:

{
  "mcpServers": {
    "firefox-tabs": {
      "command": "node",
      "args": ["/absolute/path/to/agent-bridge-for-tab-management-in-firefox/dist/server/index.js"],
      "env": {
        "FIREFOX_TABS_BRIDGE_PORT": "8765",
        "FIREFOX_TABS_BRIDGE_TOKEN": "<same-token-as-the-extension>"
      }
    }
  }
}

Version 0.3.1 uses one bridge port, so only one stdio MCP client can own the connection at a time. Stop Codex before handing the same port to another client such as Hermes.

5. Optionally install the Agent Skill

MCP is sufficient for calling the tools. Install the Skill when the agent host supports SKILL.md packages and you want consistent exact matching, guarded failures, and post-operation verification.

For Codex:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/firefox-tab-manager "${CODEX_HOME:-$HOME/.codex}/skills/"

Restart the agent after installation. For another agent host, copy skills/firefox-tab-manager/ into that product's documented skills directory. Skill formats are not standardized across all agents; hosts without SKILL.md support should use the MCP server alone.

6. Verify the connection

Ask the agent:

Check whether the Firefox bridge is connected, list the current tab groups,
open https://example.com, place the new tab into an exact group named Research,
creating it only if it does not exist, and verify the final group ID.

Architecture

flowchart LR
    A["AI agent + optional Skill"] -->|"stdio / MCP"| B["Firefox Tab Management Agent MCP"]
    B <-->|"127.0.0.1 WebSocket + shared token"| C["Tab Management Agent Bridge for Firefox"]
    C <-->|"tabs + tabGroups APIs"| D["Live Firefox session"]

The WebSocket listener binds only to loopback and accepts authenticated connections from a moz-extension:// origin. See architecture, security policy, and privacy policy.

MCP tools

Development

Requirements: Firefox 142 or newer, Node.js 20 or newer, and npm.

npm ci
npm run check

The tests cover URL restrictions, exact matching, ambiguous-tab rejection, duplicate groups, cross-window grouping, pinned-tab protection, no-op success, ungrouping, WebSocket origin checks, token authentication, and request timeouts.

Maintainers should follow the release checklist and AMO reviewer guide. Build archives are release artifacts and are intentionally excluded from Git.

Contributing and license

Read CONTRIBUTING.md before opening a pull request. Security reports should follow SECURITY.md, not public issues.

Licensed under the Mozilla Public License 2.0. “Firefox” is used to identify compatibility with Mozilla Firefox; this project is independent and is not endorsed by Mozilla.