Firefox MCP Server

Firefox MCP Server

Advanced Firefox browser automation with comprehensive debugging capabilities

A powerful Model Context Protocol (MCP) server that provides sophisticated Firefox browser automation through 28 specialized tools. Designed for AI assistants and automation workflows requiring multi-session management, real-time debugging, and comprehensive web interaction capabilities.

🌟 Key Features

Multi-Session Architecture

• Isolated Browser Sessions: Each session runs in a completely separate context with independent cookies, storage, and debugging
• Perfect for Multiplayer Testing: Test multiplayer games and multi-user applications seamlessly
• Concurrent Operations: Manage multiple browser sessions simultaneously from a single interface

Comprehensive Debugging Suite

• Real-time Console Monitoring: Capture all console output (log, error, warn, info, debug)
• JavaScript Error Tracking: Monitor unhandled errors with full stack traces
• Network Activity Monitoring: Track HTTP requests, responses, and timing data
• WebSocket Traffic Capture: Perfect for Phoenix LiveView and real-time application debugging
• Performance Metrics: Monitor DOM timing, paint events, and memory usage

Advanced Interaction Capabilities

• Precise Element Interaction: Click, type, and interact with any web element
• Keyboard Event Simulation: Send complex key combinations and shortcuts
• Drag & Drop Operations: Smooth drag operations with customizable timing and steps
• JavaScript Execution: Run custom JavaScript in browser contexts

🚀 Quick Start

Installation

npm install firefox-mcp-server
npx playwright install firefox

Basic Usage

Add to your MCP client configuration:

{
  "mcpServers": {
    "firefox": {
      "command": "npx",
      "args": ["firefox-mcp-server"],
      "env": {}
    }
  }
}

Example: Multi-User Testing

// Launch browser and create isolated sessions
await browser_launch({headless: false})
await session_create({sessionId: "user1", url: "https://app.example.com"})
await session_create({sessionId: "user2", url: "https://app.example.com"})

// User 1 creates a game
await element_click({sessionId: "user1", selector: "button.create-game"})

// User 2 joins the game
await element_click({sessionId: "user2", selector: "button.join-game"})
await input_type({sessionId: "user2", selector: "input.game-code", text: "ABC123"})

// Monitor both sessions for real-time updates
await debug_websocket_messages({sessionId: "user1", limit: 10})
await debug_websocket_messages({sessionId: "user2", limit: 10})

🛠️ Complete Tool Reference

Browser Management

• browser_launch - Launch Firefox with debugging capabilities
• browser_close - Close browser and clean up all resources

Session Management

• session_create - Create isolated browser session with independent state
• session_list - List all active sessions with URLs and status
• session_close - Close specific session and free resources
• session_set_active - Set default session for subsequent operations

Page Navigation

• page_navigate - Navigate to any URL
• page_reload - Refresh current page
• history_back / history_forward - Browser history navigation
• url_get_current - Get current page URL

Element Interaction

• element_click - Click elements by selector or coordinates
• element_drag - Drag and drop with smooth animations
• input_type - Type text into input fields and text areas
• keyboard_press - Send keyboard events with modifier support
• element_wait - Wait for elements to appear or become visible

Content Extraction

• html_extract - Extract HTML content from page or elements
• text_extract - Get visible text content
• page_screenshot - Capture screenshots with flexible options

Advanced Capabilities

• javascript_execute - Run custom JavaScript in browser context

Comprehensive Debugging Tools

• debug_console_logs - Monitor browser console output
• debug_javascript_errors - Track JavaScript errors and exceptions
• debug_network_activity - Monitor HTTP requests and responses
• debug_websocket_messages - Capture WebSocket traffic (LiveView-friendly)
• debug_performance_metrics - Get timing and memory usage data
• debug_activity_all - Combined feed of all debugging information
• debug_monitoring_start - Start comprehensive monitoring
• debug_buffers_clear - Clear accumulated debug data
• debug_helpers_inject - Inject custom debugging utilities

🎯 Use Cases

Web Application Testing

• Automated UI testing with visual verification
• Form submission and validation testing
• Cross-browser compatibility verification
• Performance monitoring and optimization

Multiplayer Game Development

• Multi-player session simulation
• Real-time state synchronization testing
• WebSocket message flow debugging
• Client-side prediction validation

Phoenix LiveView Development

• LiveView event flow monitoring
• Real-time update verification
• WebSocket connection debugging
• Multi-user interaction testing

E-commerce and SaaS Testing

• Multi-user checkout flows
• Session isolation for different user roles
• Real-time inventory updates
• Payment flow testing

📊 Debugging Capabilities

Console Monitoring

// Get recent console activity
await debug_console_logs({
  sessionId: "user1",
  types: ["error", "warn"],
  limit: 20,
  since: Date.now() - 60000  // Last minute
})

Network Analysis

// Monitor API calls and responses
await debug_network_activity({
  sessionId: "user1",
  filter: "xhr",
  limit: 10
})

WebSocket Debugging

// Perfect for Phoenix LiveView
await debug_websocket_messages({
  sessionId: "user1",
  limit: 5
})

Performance Monitoring

// Get comprehensive performance data
await debug_performance_metrics({
  sessionId: "user1"
})

⚙️ Troubleshooting

Playwright Browser Not Found Error

If you encounter an error like:

browserType.launch: Executable doesn't exist at /home/luke/.cache/ms-playwright/firefox-1482/firefox/firefox

Solution: The Playwright browsers need to be installed. Run:

# From the firefox-mcp-server directory
./node_modules/.bin/playwright install firefox

This downloads the Firefox browser binary that Playwright uses for automation. This issue was resolved on 2025-08-03 when the MCP server failed to launch due to missing browser binaries.

🔧 Claude Code Configuration

Local Configuration

Claude Code uses a project-specific configuration located at:

/home/luke/workbench/drabardi/.claude/settings.local.json

This configuration includes:

1. Enabled MCP Servers: The firefox-control server is enabled in enabledMcpjsonServers
2. Permissions: Various tool permissions are whitelisted including all Firefox MCP tools

MCP Server Configuration

The Firefox MCP server is configured in Claude Code using:

# Check configured MCP servers
claude mcp list

# Output shows:
firefox-control: node /home/luke/workbench/firefox-mcp-server/index.js
tidewave: http://localhost:4000/tidewave/mcp (SSE)

The server runs from /home/luke/workbench/firefox-mcp-server/ using the main index.js file (which internally uses the index-multi-debug.js implementation).

🔧 Configuration Options

Session Creation

await session_create({
  sessionId: "unique-id",
  url: "https://example.com",
  contextId: "optional-context",
  enableMonitoring: true  // Enable real-time debugging
})

Screenshot Options

await page_screenshot({
  sessionId: "user1",
  path: "screenshot.png",
  fullPage: true  // Capture entire page
})

Drag Operations

await element_drag({
  sessionId: "user1",
  selector: ".slider",
  offsetX: 100,
  duration: 1000,  // Smooth 1-second animation
  steps: 20        // 20 intermediate positions
})

📁 Project Structure

firefox-mcp-server/
├── index.js              # Main MCP server implementation
├── package.json           # Project configuration
├── README.md             # This file
├── CLAUDE.md             # Claude Code integration guide
├── examples/             # Usage examples
│   ├── demo-tibia-simple.js
│   ├── demo-tibia.js
│   └── demo-multiplayer.js
├── tests/                # Test files
│   └── test.js
└── docs/                 # Additional documentation
    ├── ENHANCEMENT_USAGE.md
    └── README-multi.md

🤝 Contributing

We welcome contributions! This project is designed to be:

• LLM-Friendly: Tool names and descriptions optimized for AI assistant discovery
• Extensible: Easy to add new browser automation capabilities
• Well-Documented: Comprehensive examples and documentation

📋 Requirements

• Node.js: 18.0.0 or higher
• Firefox: Automatically installed via Playwright
• MCP Client: Claude Code, Cline, or other MCP-compatible tools

🔒 Security

This server provides comprehensive browser automation capabilities. Use with trusted MCP clients only. 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

📄 License

MIT License - see LICENSE file for details.

---

Perfect for AI assistants working with web applications, multiplayer games, and real-time debugging scenarios.