Firefox MCP Server

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:

2. Install Firefox browser for Playwright:

Configuration

Standard Configuration

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

Debug-Enhanced Configuration (Recommended)

For full debugging capabilities, use the enhanced server:

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")
• 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

Multi-Player Game Testing

Phoenix LiveView Debugging

Real-time Game State Monitoring

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