@fulldecent/firefox-devtools-mcp

Model Context Protocol server for automating Firefox via WebDriver BiDi (through Selenium WebDriver). Works with Claude Code, Claude Desktop, Cursor, Cline and other MCP clients.

Note: this MCP server requires a local Firefox browser installation and cannot run on cloud hosting services. Use npx @fulldecent/firefox-devtools-mcp@latest to run locally, or use Docker with the provided Dockerfile.

How this differs from upstream

This package is a fork of firefox-devtools-mcp (by freema) via @padenot/firefox-devtools-mcp. The following features are added on top of immediate upstream:

• Tabs are identified with robust UUIDs in all functions (instead of ephemeral tab index number). This means you can have multiple agents all accessing their own tabs in the same browser profile simultaneously.

The goal is to upstream features that prove useful.

Requirements

• Node.js ≥ 20.19.0
• Firefox 100+ installed (auto‑detected, or pass --firefox-path)

Install and use with Claude Code

Recommended: use npx so you always run the latest published version from npm.

Option A — Claude Code CLI

claude mcp add firefox-devtools npx @fulldecent/firefox-devtools-mcp@latest

Pass options either as args or env vars:

# Headless + viewport via args
claude mcp add firefox-devtools npx @fulldecent/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Or via environment variables
claude mcp add firefox-devtools npx @fulldecent/firefox-devtools-mcp@latest \
  --env START_URL=https://example.com \
  --env FIREFOX_HEADLESS=true

Option B — edit Claude Code settings JSON

Add to your Claude Code config file:

• macOS: ~/Library/Application Support/Claude/Code/mcp_settings.json
• Linux: ~/.config/claude/code/mcp_settings.json
• Windows: %APPDATA%\Claude\Code\mcp_settings.json

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

Option C — helper script (local dev build)

npm run setup
# Choose Claude Code; the script saves JSON to the right path

Try it with MCP Inspector

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

Then call tools like:

• list_pages, navigate_page (pass pageId from list_pages)
• take_snapshot then click_by_uid / fill_by_uid
• list_network_requests (always‑on capture), get_network_request
• screenshot_page, list_console_messages

CLI options

You can pass flags or environment variables (names on the right):

Note on --pref: when Firefox runs in WebDriver BiDi mode, it applies RecommendedPreferences that modify browser behavior for testing. The --pref option allows overriding these defaults when needed (e.g., for Firefox development, debugging, or testing scenarios that require production-like behavior).

Example: --pref "browser.ml.enable=true" enables Firefox's ML/AI features. This is essential when using this MCP server to develop or test AI-powered features like Smart Window, since RecommendedPreferences disables it by default.

Tool reference

All page-aware tools require an explicit pageId parameter — the stable window handle returned by list_pages. This handle is assigned by Firefox at tab-creation time and does not change if other tabs are opened or closed, making it safe to hold across multi-step workflows.

Page management

list_pages — no parameters

new_page

navigate_page

close_page

DOM snapshot

UIDs are stable identifiers for DOM elements within a single snapshot. They become invalid after page navigation or DOM changes — call take_snapshot again to get fresh UIDs.

take_snapshot

resolve_uid_to_selector

clear_snapshot — no parameters

Input interaction

All input tools require valid UIDs from the current snapshot.

click_by_uid

hover_by_uid

fill_by_uid

drag_by_uid_to_uid

fill_form_by_uid

upload_file_by_uid

Network monitoring

Network requests are captured automatically. Use list_network_requests to browse and get_network_request to inspect individual requests in detail.

list_network_requests

get_network_request

Either id or url must be provided. If multiple requests match a URL, an error is returned listing the matching IDs.

Console

list_console_messages

All filters are combined with AND logic.

clear_console_messages — no parameters. Returns count of cleared messages.

Screenshots

Returns a native MCP image content item (PNG) for GUI clients, or saves to disk when saveTo is provided.

screenshot_page

screenshot_by_uid

Screenshot tip for Claude Code: base64 image data consumes significant context. Use the saveTo parameter to save screenshots to disk, then view the file with Claude Code's read tool.

Script evaluation

evaluate_script — execute JavaScript in page context.

evaluate_chrome_script — evaluate JavaScript in the current chrome (privileged) context. Requires MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1.

Chrome context (privileged)

These tools require MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 environment variable.

list_chrome_contexts — no parameters. Lists privileged browsing contexts with their IDs.

select_chrome_context

Firefox management

get_firefox_info — no parameters. Returns Firefox configuration: binary path, headless status, viewport, profile path, start URL, arguments, environment variables, preferences, output file path and size.

get_firefox_output — retrieve Firefox stdout/stderr output (including MOZ_LOG).

restart_firefox — restart Firefox with different configuration. All current tabs will be closed.

Firefox preferences (runtime)

These tools require MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1.

set_firefox_prefs

get_firefox_prefs

WebExtension management

install_extension

uninstall_extension

list_extensions — requires MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1.

Utilities

accept_dialog

dismiss_dialog

navigate_history

set_viewport_size

Local development

npm install
npm run build

# Run with Inspector against local build
npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720

# Or run in dev with hot reload
npm run inspector:dev

Troubleshooting

• Firefox not found: pass --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) or the correct path on your OS.
• First run is slow: Selenium sets up the BiDi session; subsequent runs are faster.
• Stale UIDs after navigation: take a fresh snapshot (take_snapshot) before using UID tools.
• Windows 10 — MCP error -32000: connection closed:

  • Solution 1: call using cmd (see https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310)

    {
      "mcpServers": {
        "firefox-devtools": {
          "command": "cmd",
          "args": ["/c", "npx", "-y", "@fulldecent/firefox-devtools-mcp@latest"]
        }
      }
    }
    

  • Solution 2: use the absolute path to npx:

    {
      "mcpServers": {
        "firefox-devtools": {
          "command": "C:\\nvm4w\\nodejs\\npx.ps1",
          "args": ["-y", "@fulldecent/firefox-devtools-mcp@latest"]
        }
      }
    }
    

    Adjust the path to match your installation. The extension might be .cmd, .bat, or .exe rather than .ps1. Use double backslashes (\\) as required by JSON.

Versioning

Use @latest with npx for the newest release.

License

MIT