Firefox DevTools MCP for AI Agent Testing
Overview
The firefox-devtools-mcp is a Model Context Protocol (MCP) server that
enables AI assistants (such as Claude Code) to automate and interact with
Firefox through WebDriver protocols (BiDi and Classic). This tool is
particularly useful for:
Automating browser interactions for testing and debugging
Attempting to reproduce issues on live websites
Capturing Firefox debug logs (MOZ_LOG) while controlling the browser
Dynamically changing Firefox configuration without restarting
The MCP server provides programmatic access to a Firefox build, including DevTools capabilities such as page navigation, DOM inspection, network monitoring, console logs, user input simulation, and Firefox logging. It isn’t complete yet, but can already be useful.
This documentation refers to a Mozilla-specific fork with enhanced logging capabilities: https://github.com/padenot/firefox-devtools-mcp
Key Features
WebDriver BiDi Protocol: Uses the modern WebDriver BiDi protocol via Selenium WebDriver
WebDriver Classic Fallback: Uses WebDriver Classic (Marionette) for features not yet ported to BiDi (notably Chrome context usage)
Local Firefox Support: Can connect to custom Firefox builds (e.g., local development builds), or typical release/beta/nightly/esr builds, present on the machine
Real-time Interaction: Provides live access to browser state and network activity
Firefox Output Capture: stdout/stderr capturing, including setting and reading MOZ_LOG
Prerequisites
Required Software
Node.js: Version 20.19.0 or higher
Firefox: system installation (all channels supported) or local build
Claude Code (or compatible MCP client): For AI-assisted automation
Installation and Configuration
Claude Code can install and configure the MCP server with a single command:
claude mcp add firefox-devtools npx @padenot/firefox-devtools-mcp
This command registers the MCP server with your Claude Code configuration for
the current project (typically project/.claude/).
If a global installation is preferred (so that it works from multiple project directories), it can be installed at the user scope:
claude mcp add firefox-devtools npx @padenot/firefox-devtools-mcp --scope user
This changes ~/.claude.json, either in the project section, or in the global
section (if installed at the user scope).
After installation and/or configuration restart Claude Code to load the new MCP server:
# Exit Claude Code, then restart it, continuing the last session
claude -c
The MCP server will automatically start when Claude Code initializes.
Configuration options
The MCP server supports several command-line options. It’s preferable to start with no options, but they exist:
Option |
Description |
|---|---|
|
Path to Firefox executable (system Firefox used if not specified) |
|
Run Firefox without UI (useful for automated testing) |
|
Set initial viewport size (e.g., |
|
Use a specific Firefox profile directory |
|
Initial URL to load (default: |
|
Ignore TLS certificate errors (use with caution) |
|
Additional arguments to pass to Firefox |
|
Set environment variables for Firefox (can be used multiple times) |
|
Path where Firefox output (stdout/stderr) will be captured (optional) |
Example with multiple options:
{
"type": "stdio",
"command": "@padenot/firefox-devtools-mcp",
"args": [
"--firefox-path",
"/home/developer/firefox/obj-x86_64-pc-linux-gnu/dist/bin/firefox",
"--headless",
"--viewport",
"1920x1080",
"--env",
"MOZ_LOG=HTMLMediaElement:5"
]
}
Available Capabilities
The firefox-devtools-mcp provides tools through the MCP protocol. Tool names
are generally self-describing. Simply ask your AI assistant to perform tasks - it
will use the appropriate tools. This list may not be complete as the server is
under active development.
Importantly, you can instruct the agent to run a different Firefox than the one it picked, e.g. your own build, or some specific version, by telling it the path: it isn’t necessary to configure it.
Page Management:
list_pages, new_page, navigate_page, select_page, close_page
DOM Interaction:
take_snapshot, resolve_uid_to_selector, click_by_uid, hover_by_uid,
fill_by_uid, fill_form_by_uid, drag_by_uid_to_uid, upload_file_by_uid
Network & Console:
list_network_requests, get_network_request, list_console_messages,
clear_console
Screenshots:
screenshot_page, screenshot_by_uid
Dialogs & Navigation:
accept_dialog, dismiss_dialog, navigate_history, set_viewport_size
Firefox Management:
get_firefox_info, get_firefox_output, restart_firefox
Script Evaluation:
evaluate_script (content), evaluate_chrome_script (privileged)
Chrome Context (privileged code):
list_chrome_contexts, select_chrome_context, evaluate_chrome_script
Working with MOZ_LOG
Firefox’s MOZ_LOG system provides detailed debug output from various modules.
The firefox-devtools-mcp captures this output automatically when environment
variables are set.
You can enable MOZ_LOG with something like this:
Developer: "Enable HTMLMediaElement logging at level 5"
AI uses: restart_firefox(env=["MOZ_LOG=HTMLMediaElement:5"])
Common MOZ_LOG Modules
For a useful list of available MOZ_LOG modules and their descriptions, see
toolkit/content/aboutLogging/aboutLogging.mjs in the Firefox repository, or search
searchfox.org with something like this searchfox query.
Chrome Context Access
For debugging privileged Firefox code (chrome/XUL), enable system access:
restart_firefox(env=["MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1"])
Then use list_chrome_contexts, select_chrome_context, and
evaluate_chrome_script to access gBrowser, Components, and other
privileged APIs.
At the moment, the MCP relies on WebDriver Classic (Marionette) for Chrome context APIs. While WebDriver BiDi and Classic are meant to work seamlessly together, some WebDriver BiDi features might not work when getting executed for chrome browsing contexts. Chrome support for WebDriver BiDi is tracked on the following meta bug.