README.md•14.2 kB
# 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:
```bash
npm install
```
2. Install Firefox browser for Playwright:
```bash
npx playwright install firefox
```
## Configuration
### Standard Configuration
Add this server to your MCP configuration file (usually `~/.config/mcp/cline.json` or similar):
```json
{
"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:
```json
{
"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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// 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