firefox-mcp-server 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:

Enabled MCP Servers: The firefox-control server is enabled in enabledMcpjsonServers
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.