Firefox MCP Server

How to use

Start by launching the multi-tab capable Firefox controller, then create isolated tabs for your scenarios. Switch between tabs to drive multiple users or players, navigate to pages, interact with elements, and capture debugging feeds for each tab independently. Use the combined debug feed to monitor everything in one place and enable targeted monitoring for specific types of events like console logs, network activity, or WebSocket messages.

How to install

Prerequisites you need before running the server:

• Node.js 18+ is required
• Firefox will be installed automatically by Playwright
• A MCP-compatible client is used to control the server
• A display server is required for non-headless mode (set DISPLAY)

Install dependencies and set up Firefox for Playwright:

npm install
npx playwright install firefox

Configuration

Configure the MCP server to run locally using the standard or debug-enhanced setup. The standard setup runs a simple Node process, while the debug-enhanced setup runs a multi-debug variant with extra monitoring. You can start either configuration and restart the client to activate the new tools.

{
  "mcpServers": {
    "firefox-control": {
      "command": "node",
      "args": ["index.js"],
      "cwd": "/home/luke/workbench/drabardi/firefox-mcp-server"
    }
  }
}

Examples and usage patterns

Launch the browser with debugging, create a tab, and perform interactions in a single flow.

// Launch browser with debugging
mcp__firefox-control__launch_firefox_multi({headless: false, enableDebugLogging: true})

// Create tab and navigate
mcp__firefox-control__create_tab({tabId: "main", url: "https://example.com", enableMonitoring: true})

// Interact with page
mcp__firefox-control__click({selector: "button#submit", tabId: "main"})
mcp__firefox-control__type_text({selector: "input[name='search']", text: "hello world", tabId: "main"})

// Take screenshot
mcp__firefox-control__screenshot({path: "page.png", fullPage: true, tabId: "main"})

// Close
mcp__firefox-control__close_browser()

Security note

This server provides browser automation with extensive debugging access. Use it only in trusted environments. It can execute arbitrary JavaScript in browser contexts and monitor all network and WebSocket activity, so treat it as a powerful tool and safeguard access accordingly.

Advanced debugging and monitoring features

The server collects a rich set of debugging data automatically, including console logs, JavaScript errors, WebSocket traffic, network activity, and performance metrics. You can filter and query these streams per tab to build a precise picture of client-side behavior.

Tools and endpoints overview

The server exposes a wide range of actions for browser control and debugging, including launching the browser, creating tabs, navigating, interacting with elements, taking screenshots, and retrieving debug data such as console logs, errors, network activity, WebSocket messages, and performance metrics. Each action targets a specific tab context to keep sessions isolated.

Architecture

The debug-enhanced server runs on Playwright for Firefox automation with per-tab isolation. It captures events in real time and timestamps them for precise debugging, maintaining separate browser contexts for each tab so cookies, local storage, and session data do not cross between sessions.

Requirements

Node.js 18+ is required. Firefox is installed automatically by Playwright. You need a MCP-compatible client and a display server for non-headless mode.

Troubleshooting and notes

If you modify configuration, restart the MCP client to activate the new debugging tools. Ensure the DISPLAY environment variable is set when running in non-headless mode and that the correct path to the debug script is used in the debug-enhanced configuration.

browser_launch

Launch Firefox with debugging capabilities to start an automation session.

browser_close

Close the active Firefox browser instance and release resources.

session_create

Create an isolated browser session with independent state for multi-user testing.

session_list

List all active sessions along with their URLs and status.

session_close

Close a specific session and free its resources.

session_set_active

Set the default session for subsequent operations.

page_navigate

Navigate to a specified URL within a session.

page_reload

Refresh the current page in a session.

history_back

Navigate back in the browser history for a session.

history_forward

Navigate forward in the browser history for a session.

url_get_current

Retrieve the current page URL of a session.

element_click

Click elements by selector or coordinates within a session.

element_drag

Drag and drop interactions with smooth animations.

input_type

Type text into input fields and text areas.

keyboard_press

Send keyboard events with optional modifiers.

element_wait

Wait for elements to appear or become visible.

html_extract

Extract HTML content from the page or specific elements.

text_extract

Extract visible text content from the page.

page_screenshot

Capture screenshots with configurable options.

javascript_execute

Run custom JavaScript in the browser context.

debug_console_logs

Monitor and retrieve browser console output.

debug_javascript_errors

Track JavaScript errors and exceptions with stack traces.

debug_network_activity

Monitor HTTP requests, responses, and timings.

debug_websocket_messages

Capture WebSocket traffic for real-time debugging.

debug_performance_metrics

Collect timing, rendering, and memory usage metrics.

debug_activity_all

Provide a combined feed of all debugging information.

debug_monitoring_start

Start comprehensive monitoring across browser sessions.

debug_buffers_clear

Clear accumulated debugging data and reset buffers.

debug_helpers_inject

Inject custom debugging utilities into the browser context.