mcp-firefox

An MCP server that connects to Firefox's Remote Debugging Protocol (RDP) over TCP, exposing browser DevTools capabilities as tools for LLMs.

How It Works

Firefox ships with a built-in Remote Debugging Protocol that speaks length-prefixed JSON over TCP. This server holds a persistent connection to that port, translates MCP tool calls into RDP messages, and returns the results:

LLM ↔ MCP (HTTP :8090) ↔ Firefox RDP (TCP :6000)

A background reader task owns the socket and dispatches every inbound packet:

• a packet without a type field is a response (or an error), and resolves the oldest pending request for the addressing actor;

• a packet with a type field is an unsolicited event.

That distinction is the only reliable correlation mechanism — Firefox does not echo a requestId to this protocol version, and actors emit both responses and events on the same connection. Getting it wrong is subtle: an event can resolve a request (hanging the caller), or a response can be swallowed as an event (hanging it and losing the data).

Actor model

Firefox has two overlapping actor generations: the legacy surface (listTabs, tabDescriptor.getTarget, navigateTo) that Mozilla is retiring, and the watcher/target surface (getWatcher, watchTargets, target-available-form) used by its own DevTools front-end.

This server uses the watcher/target surface as the single source of truth for per-tab actors, so resolution, navigation and target switching all go through one code path. Two legacy calls remain deliberately, because they are still the best API for what they do:

Sessions are keyed by the stable tab descriptor actor, not by browsingContextID — Firefox allocates a new browsing context id when it switches targets on navigation, so a bcID-keyed session would be orphaned mid-navigation and silently drop the replacement target. Target events are correlated by their sender (the tab's watcher actor), which is stable across navigation.

Navigation is transactional: navigate waits for the replacement target before returning, so the very next call works instead of racing a dead actor.

Requests are capped per actor (back-pressure), and a cancelled request is removed from its queue so it cannot consume the next response meant for someone else.

Promises are awaited for you, and a literal top-level await is automatically re-wrapped in an async function, because Firefox's console rejects a bare top-level await in a plain script.

Related MCP server: Firefox DevTools MCP

Requirements

• Python 3.11+

• Firefox with the remote debugging server enabled (see below)

• uv for dependency management

Installation

uv venv
uv pip install -e ".[dev]"    # omit [dev] for a runtime-only install

Firefox Setup

1. Enable Remote Debugging

In about:config, set:

Without devtools.chrome.enabled, screenshot capture cannot reach the privileged APIs it needs.

2. Start the Debug Listener

# Native install
firefox --start-debugger-server 6000

# Flatpak
flatpak run org.mozilla.firefox --start-debugger-server 6000

Firefox will not start a second instance against a profile that is already open, so launch it with the flag, or use a dedicated debug profile:

# Flatpak, isolated profile (recommended — avoids lock contention with your normal browser)
flatpak run org.mozilla.firefox --no-remote \
  --profile ~/.var/app/org.mozilla.firefox/config/mozilla/firefox/debug \
  --start-debugger-server 6000

Flatpak path note: the --profile path is resolved outside the sandbox, so pass the host path (~/.var/app/org.mozilla.firefox/config/...). Flatpak maps the sandbox's ~/.config onto that directory, so sandbox-style paths like ~/.config/mozilla/firefox/debug do not work.

Snap note: snap-packaged Firefox builds do not support --start-debugger-server.

3. Verify

ss -tln | grep 6000

You should see Firefox listening on 127.0.0.1:6000.

Running

.venv/bin/firefox-mcp

Starts a streamable-HTTP MCP server. By default it binds 127.0.0.1:8090.

Security: this server grants unauthenticated JavaScript execution, page reading and screenshots of a browser that is typically logged into everything. It binds to loopback only. Change FIREFOX_MCP_HOST only if you fully understand the exposure.

MCP Client Configuration

{
  "mcpServers": {
    "firefox-devtools": {
      "url": "http://127.0.0.1:8090/mcp"
    }
  }
}

Tools

Most tools accept an optional tab_index to target a specific tab, using the index reported by list_tabs.

Usage Examples

Page Content & Screenshots

# Read article text from a news site you're logged into
> read_page

# Screenshot a specific element
> screenshot(selector=".article-body")

# Full-page screenshot, written straight to disk (keeps the result small)
> screenshot(fullpage=True, save_path="/tmp/page.png")

screenshot returns a data:image/...;base64,... URL by default. Passing save_path writes the decoded image to disk and returns {path, bytes, width, height} instead, which avoids pushing megabytes of base64 through the model context.

Tab Targeting

> list_tabs
> select_tab(index=2)          # all later calls now target tab 2
> evaluate_js("document.title")

Network Capture

Capture API traffic from web apps (SPAs, streaming services, etc.):

# Start recording network traffic (before triggering it, for full coverage)
> start_capture

# Navigate and trigger app behaviour
> navigate("https://www.example.com/home")

# See what requests were made
> read_capture

# Include response bodies
> read_capture(include_bodies=True)

# Only failures
> read_capture(only_errors=True)

# Done
> stop_capture

Raw RDP Exploration

> raw_rdp_command({"to": "root", "type": "listTabs"})
> raw_rdp_command({"to": "<consoleActor>", "type": "getCachedMessages",
                   "messageTypes": ["PageError", "ConsoleAPI"]})

Use list_tabs first to discover actor ids, then experiment with raw_rdp_command.

Troubleshooting

Development

uv pip install -e ".[dev]"

uv run ruff check .          # lint
uv run ruff format --check . # formatting
uv run mypy firefox_mcp      # types (strict)
uv run pytest                # tests

The test suite uses an in-process fake Firefox (tests/fake_firefox.py) that reproduces the protocol's real quirks — nested resource batches, responses lacking a type key, interleaved events, the watcher actor dying after unwatchResources, and Firefox allocating a new browsing context id on navigation — so most behaviour is covered without needing a browser.

Notes & Limitations

• Legacy actor protocol. Tab enumeration and the chrome console still use the older actor surface (listTabs, processDescriptor.getTarget). Everything else goes through the watcher/target protocol and works on current Firefox (verified against 156), but Mozilla is gradually retiring parts of the legacy surface in favour of the WebDriver BiDi-based Remote Agent.

• One connection per server process. All tabs are reached through a single RDP connection; tab targeting is by actor, not by separate sessions.

• Capture must start before the traffic. Network capture only sees requests made after start_capture.

• Object results are grips. Evaluating an expression that returns a non-primitive yields an RDP object grip (a reference with a small preview), not the full serialised value. For a plain value, return a JSON string (JSON.stringify(...)) or a primitive from your expression.

• No request pre-emption. Cancellation cleans up correctly (a cancelled request cannot steal the next response), but a request already sent to Firefox still runs to completion there.

• No authentication. See the security note under Running.