firefox-mcp-server

JediLuke/firefox-mcp-server

3.3

If you are the rightful owner of firefox-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This MCP server provides Firefox browser automation capabilities through Playwright, allowing you to control Firefox from within your MCP-enabled applications.

Tools

  1. launch_firefox_multi

    Launch Firefox browser with multi-tab support and debugging.

  2. create_tab

    Create a new tab with isolated session and debugging.

  3. list_tabs

    List all active tabs with their URLs and status.

  4. close_tab

    Close a specific tab.

  5. set_active_tab

    Set the active tab for subsequent operations.

Firefox MCP Server

This MCP server provides Firefox browser automation capabilities through Playwright, allowing you to control Firefox from within your MCP-enabled applications. Features both basic automation and advanced multi-tab debugging capabilities.

Features

Basic Automation

  • Launch Firefox browser (headless or visible)
  • Navigate to URLs
  • Click elements by selector or coordinates
  • Type text into input fields
  • Take screenshots
  • Get page content and text
  • Execute JavaScript
  • Browser navigation (back, forward, reload)
  • Wait for elements to appear

Multi-Tab Session Support

  • Create multiple isolated browser tabs with unique contexts
  • Independent session management for multiplayer testing
  • Switch between active tabs
  • List all active tabs
  • Close specific tabs

Advanced Debugging & Monitoring

  • Console Log Monitoring: Capture all console.log, error, warn, info, debug messages
  • JavaScript Error Tracking: Monitor unhandled errors and promise rejections with stack traces
  • WebSocket Traffic Monitoring: Real-time capture of WebSocket messages (perfect for Phoenix LiveView)
  • Network Activity Monitoring: HTTP requests/responses with headers and timing
  • Performance Metrics: DOM timing, paint events, memory usage tracking
  • Combined Debug Feed: Unified view of all debugging activity
  • Real-time Event Capture: Automatic monitoring without manual injection

Installation

  1. Install dependencies:
npm install
  1. Install Firefox browser for Playwright:
npx playwright install firefox

Configuration

Standard Configuration

Add this server to your MCP configuration file (usually ~/.config/mcp/cline.json or similar):

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

Debug-Enhanced Configuration (Recommended)

For full debugging capabilities, use the enhanced server:

{
  "mcpServers": {
    "firefox-control": {
      "type": "stdio",
      "command": "node", 
      "args": ["/path/to/firefox-mcp-server/index-multi-debug.js"],
      "env": {"DISPLAY": ":1"}
    }
  }
}

Note: After updating configuration, restart Claude Code to activate new debug tools.

Available Tools

Basic Browser Control

launch_firefox_multi

Launch Firefox browser with multi-tab support and debugging

  • headless (boolean): Run in headless mode (default: false)
  • enableDebugLogging (boolean): Enable debug logging (default: true)
create_tab

Create a new tab with isolated session and debugging

  • tabId (string, required): Unique identifier for the tab
  • url (string): Initial URL to navigate to (default: "about:blank")
  • enableMonitoring (boolean): Enable real-time monitoring (default: true)
  • contextId (string): Browser context ID for isolation
list_tabs

List all active tabs with their URLs and status

close_tab

Close a specific tab

  • tabId (string, required): Tab ID to close
set_active_tab

Set the active tab for subsequent operations

  • tabId (string, required): Tab ID to make active
navigate

Navigate to a URL

  • url (string, required): URL to navigate to
  • tabId (string): Specific tab to navigate (uses active tab if not specified)
click

Click on an element

  • selector (string): CSS selector to click
  • coordinates (object): Alternative - click at specific x,y coordinates
  • tabId (string): Target tab ID
type_text

Type text into an input field

  • selector (string, required): CSS selector of input field
  • text (string, required): Text to type
  • tabId (string): Target tab ID
send_key

Send keyboard events

  • key (string, required): Key to send
  • modifiers (array): Modifier keys (ctrl, shift, alt, meta)
  • repeat (number): Number of times to repeat (default: 1)
  • selector (string): Target element selector
  • tabId (string): Target tab ID
drag

Perform drag operation

  • selector (string): Element to drag
  • fromCoordinates (object): Starting coordinates {x, y}
  • toCoordinates (object): Ending coordinates {x, y}
  • offsetX (number): X offset for drag
  • offsetY (number): Y offset for drag
  • duration (number): Drag duration in ms (default: 0)
  • steps (number): Number of intermediate steps (default: 1)
  • tabId (string): Target tab ID

Content & Media

get_page_content

Get HTML content of the page

  • selector (string): Optional CSS selector for specific element
  • tabId (string): Target tab ID
get_page_text

Get visible text content of the page

  • selector (string): Optional CSS selector for specific element
  • tabId (string): Target tab ID
screenshot

Take a screenshot

  • path (string): File path to save screenshot (default: "screenshot.png")
  • fullPage (boolean): Capture full page (default: false)
  • tabId (string): Target tab ID
wait_for_element

Wait for an element to appear

  • selector (string, required): CSS selector to wait for
  • timeout (number): Timeout in milliseconds (default: 30000)
  • tabId (string): Target tab ID
execute_script

Execute JavaScript in the browser

  • script (string, required): JavaScript code to execute
  • tabId (string): Target tab ID

Navigation

get_current_url

Get the current page URL

  • tabId (string): Target tab ID
back

Navigate back in browser history

  • tabId (string): Target tab ID
forward

Navigate forward in browser history

  • tabId (string): Target tab ID
reload

Reload the current page

  • tabId (string): Target tab ID
close_browser

Close the Firefox browser and all tabs

Advanced Debugging Tools

get_console_logs

Get captured console logs from browser

  • tabId (string): Target tab ID
  • limit (number): Max number of logs to return (default: 50)
  • since (number): Timestamp to filter logs since
  • types (array): Filter by log types ["log", "error", "warn", "info", "debug"]
get_javascript_errors

Get captured JavaScript errors

  • tabId (string): Target tab ID
  • limit (number): Max number of errors to return (default: 20)
  • since (number): Timestamp to filter errors since
get_network_activity

Get captured network requests and responses

  • tabId (string): Target tab ID
  • limit (number): Max number of requests to return (default: 30)
  • since (number): Timestamp to filter requests since
  • filter (string): Filter by request type ["all", "xhr", "websocket", "fetch"] (default: "all")
get_websocket_messages

Get captured WebSocket messages (perfect for LiveView debugging)

  • tabId (string): Target tab ID
  • limit (number): Max number of messages to return (default: 50)
  • since (number): Timestamp to filter messages since
get_performance_metrics

Get performance metrics (timing, memory usage)

  • tabId (string): Target tab ID
get_all_debug_activity

Get combined feed of all debug events

  • tabId (string): Target tab ID
  • limit (number): Max number of events to return (default: 100)
  • since (number): Timestamp to filter events since
inject_debugging_helpers

Inject debugging helper functions into the page

  • tabId (string): Target tab ID
  • includeWebSocketMonitoring (boolean): Include WebSocket monitoring (default: true)
start_monitoring

Start/restart monitoring for a tab

  • tabId (string): Target tab ID
  • types (array): Types to monitor ["console", "errors", "network", "websocket", "performance"] (default: all)
clear_debug_buffers

Clear debug event buffers for a tab

  • tabId (string): Target tab ID
  • types (array): Buffer types to clear ["console", "errors", "network", "websocket"]

Usage Examples

Basic Browser Automation

// 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()

Multi-Player Game Testing

// Launch browser and create multiple player tabs
mcp__firefox-control__launch_firefox_multi({headless: false, enableDebugLogging: true})
mcp__firefox-control__create_tab({tabId: "player1", url: "http://localhost:4000/squid-ball", enableMonitoring: true})
mcp__firefox-control__create_tab({tabId: "player2", url: "http://localhost:4000/squid-ball", enableMonitoring: true})

// Player 1 creates game
mcp__firefox-control__set_active_tab({tabId: "player1"})
mcp__firefox-control__click({selector: 'button[phx-click="create_game"]', tabId: "player1"})

// Player 2 joins game (assuming game ID is available)
mcp__firefox-control__set_active_tab({tabId: "player2"})
mcp__firefox-control__type_text({selector: 'input[name="game_id"]', text: "GameID123", tabId: "player2"})
mcp__firefox-control__click({selector: 'button[type="submit"]', tabId: "player2"})

// Monitor both players independently
mcp__firefox-control__get_all_debug_activity({tabId: "player1", limit: 10})
mcp__firefox-control__get_all_debug_activity({tabId: "player2", limit: 10})

Phoenix LiveView Debugging

// Monitor WebSocket traffic for LiveView
mcp__firefox-control__get_websocket_messages({tabId: "player1", limit: 5})

// Get console logs with filtering
mcp__firefox-control__get_console_logs({tabId: "player1", types: ["error", "warn"], limit: 10})

// Monitor network activity
mcp__firefox-control__get_network_activity({tabId: "player1", filter: "xhr", limit: 20})

// Get performance metrics
mcp__firefox-control__get_performance_metrics({tabId: "player1"})

// Combined debug feed for comprehensive monitoring
mcp__firefox-control__get_all_debug_activity({tabId: "player1", limit: 50})

Real-time Game State Monitoring

// Capture real-time game ticks and delta state
mcp__firefox-control__get_websocket_messages({tabId: "player1", limit: 3})
// Returns: Ball position, paddle movement, tick numbers, player states

// Monitor console for LiveView updates
mcp__firefox-control__get_console_logs({tabId: "player1", types: ["log"], limit: 5})
// Returns: Phoenix LiveView update logs with game state changes

// Clear buffers and restart monitoring
mcp__firefox-control__clear_debug_buffers({tabId: "player1", types: ["console", "websocket"]})
mcp__firefox-control__start_monitoring({tabId: "player1", types: ["console", "websocket"]})

Use Cases

Game Development & Testing

  • Multiplayer Testing: Create multiple browser sessions to simulate different players
  • Real-time Debugging: Monitor WebSocket traffic, console logs, and game state changes
  • Client-side Prediction: Track timing and synchronization between client and server
  • Performance Monitoring: Measure frame rates, memory usage, and network latency

Phoenix LiveView Development

  • LiveView Debugging: Monitor Phoenix LiveView WebSocket messages and state updates
  • Real-time Applications: Track bidirectional communication and state synchronization
  • Error Tracking: Capture JavaScript errors and console warnings
  • Performance Analysis: Monitor DOM updates and rendering performance

Web Application Testing

  • Cross-tab Testing: Simulate multiple users in different browser contexts
  • Session Management: Test isolated sessions and user interactions
  • Network Monitoring: Track API calls, responses, and error handling
  • UI Testing: Automate interactions and capture screenshots

Requirements

  • Node.js 18+
  • Firefox (installed automatically by Playwright)
  • MCP-compatible client (Claude Code, etc.)
  • Display server for non-headless mode (DISPLAY environment variable)

Debugging Features

Automatic Monitoring

  • Console Logs: All console.log, error, warn, info, debug messages captured automatically
  • JavaScript Errors: Unhandled errors and promise rejections with full stack traces
  • WebSocket Traffic: Real-time capture of all WebSocket messages (send/receive)
  • Network Activity: HTTP requests/responses with headers, timing, and status codes
  • Performance Metrics: DOM timing, paint events, memory usage, and navigation timing

Data Filtering

  • Time-based Filtering: Filter events since a specific timestamp
  • Type Filtering: Filter console logs by type (error, warn, info, debug)
  • Network Filtering: Filter network requests by type (xhr, websocket, fetch)
  • Limit Control: Control the number of returned events to manage data volume

Multi-tab Support

  • Isolated Contexts: Each tab runs in its own browser context with independent debugging
  • Session Management: Maintain separate sessions for different users/players
  • Independent Monitoring: Each tab captures its own debug events without interference
  • Easy Switching: Switch between tabs for testing different user interactions

Architecture

Debug-Enhanced Server (index-multi-debug.js)

  • Built on Playwright for Firefox automation
  • Real-time event capture using Chrome DevTools Protocol
  • Independent monitoring per browser tab/context
  • Automatic buffer management with configurable limits
  • Event timestamping for precise debugging

Browser Context Isolation

  • Each tab gets its own browser context for complete isolation
  • Independent cookie storage, local storage, and session data
  • Separate network monitoring and debugging per context
  • No cross-contamination between different player sessions

Security Note

This server provides browser automation capabilities with extensive debugging access. Use with caution and ensure you trust the MCP client that will be controlling Firefox. The server can:

  • Execute arbitrary JavaScript in browser contexts
  • Monitor all network traffic and WebSocket messages
  • Access page content and user interactions
  • Take screenshots and access media devices