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 capabilitiesbrowser_close- Close browser and clean up all resources
Session Management
session_create- Create isolated browser session with independent statesession_list- List all active sessions with URLs and statussession_close- Close specific session and free resourcessession_set_active- Set default session for subsequent operations
Page Navigation
page_navigate- Navigate to any URLpage_reload- Refresh current pagehistory_back/history_forward- Browser history navigationurl_get_current- Get current page URL
Element Interaction
element_click- Click elements by selector or coordinateselement_drag- Drag and drop with smooth animationsinput_type- Type text into input fields and text areaskeyboard_press- Send keyboard events with modifier supportelement_wait- Wait for elements to appear or become visible
Content Extraction
html_extract- Extract HTML content from page or elementstext_extract- Get visible text contentpage_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 outputdebug_javascript_errors- Track JavaScript errors and exceptionsdebug_network_activity- Monitor HTTP requests and responsesdebug_websocket_messages- Capture WebSocket traffic (LiveView-friendly)debug_performance_metrics- Get timing and memory usage datadebug_activity_all- Combined feed of all debugging informationdebug_monitoring_start- Start comprehensive monitoringdebug_buffers_clear- Clear accumulated debug datadebug_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-controlserver is enabled inenabledMcpjsonServers - 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.