# mozilla/firefox-devtools-mcp: Firefox automation for MCP clients

> An MCP server that drives Firefox over WebDriver BiDi so Claude Code, Codex, Cursor and Cline can inspect pages, network traffic and console output. It needs a local Firefox and a dedicated profile.

**mozilla/firefox-devtools-mcp** — Model Context Protocol server for Firefox DevTools - enables AI assistants to inspect and control Firefox browser through the Remote Debugging Protocol

- Repository: https://github.com/mozilla/firefox-devtools-mcp
- Stars: 452 · Forks: 65
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/mozilla-firefox-devtools-mcp

## The gap it fills: an agent that can see the browser

An MCP client can read files and run shell commands, but it has no view of a rendered page. Firefox DevTools MCP closes that gap by exposing browser inspection and control as MCP tools. The README describes it as a Model Context Protocol server for automating Firefox via WebDriver BiDi, through Selenium WebDriver, and lists Claude Code, Claude Desktop, Cursor and Cline as clients.

The audience is narrow and specific. You are a developer or QA engineer who already runs an MCP-capable assistant and wants it to open pages, read console messages, inspect network requests and take snapshots of the DOM. The project is not a test runner and not a replacement for Playwright or Selenium in CI. It is a bridge between an assistant's tool-calling loop and a live Firefox instance on your machine.

## How the server talks to Firefox: BiDi, Selenium and tool presets

The transport is WebDriver BiDi driven through Selenium WebDriver, not the older Remote Debugging Protocol despite the repository description mentioning RDP. The README's own wording is WebDriver BiDi, and the CLI flag for attaching to a running browser is --connect-existing with --marionette-port defaulting to 2828, which is the Marionette listener Firefox exposes for automation.

Tool exposure is modular. The --tool-preset flag selects which tool modules are enabled, with values slim, basic (the default), developer, mozilla and all. The README states the default basic preset already includes evaluate_script, and that slim drops it. The developer preset adds debugging, network, console and profiler modules; mozilla adds a privileged context and requires MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1. You can bypass presets entirely with --tools, which takes an explicit module list such as pages network script.

Two captures are always on: network requests and downloads. The README lists list_network_requests as always-on capture, alongside list_downloads and set_download_behavior. That means the agent can read traffic and download events without you enabling a module first, which is convenient and also the reason the security section is worth reading before you point this at anything you do not control.

The typical tool sequence the README gives is list_pages, select_page, navigate_page, then take_snapshot followed by click_by_uid or fill_by_uid. The uid-based interaction model matters: the agent snapshots the page, receives stable identifiers, and acts on those rather than guessing selectors. Screenshots and console reads are separate tools, screenshot_page and list_console_messages.

## Installing it and taking a first snapshot

The prerequisites are Node.js 20.19.0 or later and Firefox 100 or newer, auto-detected or supplied through --firefox-path. The README recommends npx so you always run the latest published version.

For Claude Code, the CLI form registers the server and passes extra flags after a double dash. This command adds a headless server with a fixed viewport:

```bash
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720
```

The same registration can be done through environment variables instead of flags, using START_URL and FIREFOX_HEADLESS. Codex has an equivalent codex mcp add command in the README:

```bash
codex mcp add firefox-devtools -- npx @mozilla/firefox-devtools-mcp@latest
```

If you prefer editing configuration directly, Claude Code reads an mcp_settings.json entry. This is the shape the README gives, with the start URL set to about:blank:

```json
{
  "mcpServers": {
    "firefox-devtools": {
      "command": "npx",
      "args": ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "env": {
        "START_URL": "about:blank"
      }
    }
  }
}
```

Before connecting an assistant, the README suggests exercising the server with MCP Inspector. This launches the inspector against the published package with a start URL and headless mode:

```bash
npx @modelcontextprotocol/inspector npx @mozilla/firefox-devtools-mcp@latest --start-url https://example.com --headless
```

Inside the inspector you should see the tool list for the active preset. Call list_pages, then navigate_page, then take_snapshot, and confirm that click_by_uid and fill_by_uid accept the identifiers the snapshot returned. If the tool list is shorter than you expected, check TOOL_PRESET; if the browser never appears, check --firefox-path and whether a Firefox instance is already holding the profile.

For a source checkout, the package.json defines npm run setup, which the README describes as a helper script that saves JSON to the right path, and npm run dev, which runs src/index.moz.ts under tsx watch:

```bash
npm run setup
npm run dev
```

## Docker, Android and the modes that change the blast radius

A Dockerfile and docker-compose.yml ship in the repository. The image builds on node:22-bookworm, installs firefox-esr, runs as a non-root user with uid 1001, and starts with node dist/index.js over stdio, so no port is exposed by the server itself. The compose file sets FIREFOX_HEADLESS=true, AUTO_LAUNCH_FIREFOX=false, VIEWPORT=1280x720 and RDP_PORT=6000, and includes an optional selenium/standalone-firefox service publishing 6000 and 7900 for VNC. The README is explicit that cloud hosting services such as glama.ai cannot run this server because a local Firefox installation is required.

Android mode is a separate path. --android-device takes an ADB device serial such as emulator-5554, --android-package defaults to org.mozilla.firefox, and --android-wipe-app-data must be passed alongside --android-device as confirmation that the target app's data will be wiped. That wipe is not a side effect you can opt out of while staying in Android mode; the README treats the flag as the acknowledgement.

Two more flags widen what the agent can touch. --accept-insecure-certs ignores TLS errors. --unrestricted-save-paths lets the saveTo parameter write anywhere on disk instead of the default roots, and the README points at SECURITY.md for that note. Both are the kind of switch that is easy to add while debugging and easy to forget afterwards.

## The security model is the real adoption cost

The README's security section is unusually direct for a tool of this kind, and it should be read as a design constraint rather than boilerplate. Three practices are named: use a dedicated Firefox profile, be cautious about which sites you visit, and enable only the tool modules you need.

The reasoning is stated plainly. The agent has access to whatever the browser can reach, including cookies and saved sessions, so running the server against your regular profile hands an assistant your logged-in state. Pages can return content designed to manipulate the agent, which the README calls prompt injection. The default preset is not the smallest one: basic includes evaluate_script, and only slim removes it. If your agent does not need to execute arbitrary script in the page, slim is the safer starting point, and the README treats the presets as a ladder rather than a menu of equals.

The privileged preset raises the ceiling again. --tool-preset mozilla enables a privileged context and requires MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1, and the deprecated --enable-privileged-context flag maps to the same preset. That is a deliberate gate, not a bug, and it is the point at which this stops being a page-inspection tool and becomes something closer to browser-level control.

Where it is the wrong tool: shared or multi-tenant environments, CI systems where the browser must be isolated per job without a dedicated profile, and any workflow where the agent is expected to browse untrusted sites unattended. The README's own guidance rules those out.

## How it differs from Playwright MCP and from writing your own BiDi client

The closest comparison is Playwright's MCP server. The difference is the engine and the control surface. Playwright MCP drives Chromium, Firefox and WebKit through Playwright's own abstraction and is built around accessibility-tree snapshots for agent interaction. Firefox DevTools MCP is Firefox-only and sits on WebDriver BiDi through Selenium WebDriver, which is why the flags look like browser-automation flags: --marionette-port, --firefox-arg, --pref name=value passed through moz:firefoxOptions, and --connect-existing for attaching to a browser you started yourself.

That attach mode is the practical distinction. With --connect-existing and a Marionette port, the agent joins a Firefox session that already exists, including one on an Android device reached over ADB, rather than launching a fresh browser per session. Playwright's model assumes it owns the browser lifecycle. If your workflow is debugging a running browser, the attach path is the reason to pick this one; if your workflow is repeatable end-to-end tests in CI, Playwright is the better fit and this project does not claim to replace it.

The other alternative is writing a BiDi client yourself against the Firefox remote agent. That gives you full control and no preset ladder, at the cost of reimplementing page listing, navigation, snapshots, network capture and download handling. The value here is the tool surface and the presets, not the protocol work.

## Maintenance, licensing and what an upgrade actually costs

The last push to the default branch was on 2026-09-10, and the most recent release is v0.10.2 from 2026-09-04, following v0.10.1 on 2026-08-21 and v0.10.0 on 2026-08-18. The repository is not archived. On the evidence of those dates the project is moving, but the version numbers also tell you something about upgrade cost: three minor-line releases inside a month means the CLI surface is still settling.

That shows up in the flag list. --enable-script and --enable-privileged-context are both marked deprecated in the README, with --tool-preset developer and --tool-preset mozilla as the replacements. If you pinned an early configuration, expect to rewrite it. The environment variable names are stable enough to be worth preferring: TOOL_PRESET, FIREFOX_HEADLESS, START_URL, CONNECT_EXISTING, MARIONETTE_PORT and UNRESTRICTED_SAVE_PATHS all appear in .env.example or the CLI options list.

Licensing is dual: the repository carries LICENSE-MIT and LICENSE-APACHE, and package.json declares "MIT OR Apache-2.0". The GitHub metadata reports the licence as NOASSERTION, which conflicts with the files in the tree; if the licence matters to your legal review, read the two licence files rather than the metadata badge. This is a description of what the repository contains, not legal advice.

## Conclusion

Adopt it if your agent workflow already runs in a terminal next to a Firefox install and you want page, network and console inspection without building your own BiDi client. Skip it if you need a hosted, multi-user browser service, because the README states a local Firefox installation is required and cloud hosting is not supported. Before wiring it into an agent, verify three things: that Node.js is at least 20.19.0, that the profile you point at is not your everyday one, and which tool preset you actually need, since the default basic preset already exposes evaluate_script.

## FAQ

### What is Firefox DevTools MCP?

It is a Model Context Protocol server from Mozilla that automates Firefox through WebDriver BiDi via Selenium WebDriver, letting MCP clients such as Claude Code, Claude Desktop, Cursor and Cline inspect and control the browser. It requires a local Firefox installation and cannot run on cloud hosting services.

### What does the Firefox DevTools MCP server do in a browser?

It exposes tools for listing and selecting pages, navigating, taking DOM snapshots, clicking and filling by uid, reading console messages, capturing screenshots, and inspecting network requests and downloads, which the README describes as always-on capture. It also supports Android devices over ADB and an attach mode for an already-running Firefox.

### How do I install firefox-devtools-mcp for Claude Code?

The README recommends registering it with claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest, optionally passing --headless and --viewport after a double dash, or setting START_URL and FIREFOX_HEADLESS as environment variables. The same server can be added to Codex with codex mcp add, or configured by editing mcp_settings.json directly.

### Which tool preset should I choose for firefox-devtools-mcp?

The default is basic, which already includes evaluate_script; slim drops it. The developer preset adds debugging, network, console and profiler modules, while mozilla adds a privileged context and requires MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1. The README advises enabling only the modules you need.

### Does firefox-devtools-mcp work with an already-running Firefox?

Yes. The --connect-existing flag attaches to a running Firefox instead of launching a new one, and --marionette-port sets the Marionette port for that mode, defaulting to 2828. The environment variable equivalents are CONNECT_EXISTING and MARIONETTE_PORT.

## Sources

- [Issues](https://github.com/mozilla/firefox-devtools-mcp/issues)
- [mozilla/firefox-devtools-mcp on GitHub](https://github.com/mozilla/firefox-devtools-mcp)
- [README](https://github.com/mozilla/firefox-devtools-mcp/blob/main/README.md)
- [Releases](https://github.com/mozilla/firefox-devtools-mcp/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mozilla-firefox-devtools-mcp