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 ```bash npm install firefox-mcp-server npx playwright install firefox ``` ### Basic Usage Add to your MCP client configuration: ```json { "mcpServers": { "firefox": { "command": "npx", "args": ["firefox-mcp-server"], "env": {} } } } ``` ### Example: Multi-User Testing ```javascript // 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 ```javascript // Get recent console activity await debug_console_logs({ sessionId: "user1", types: ["error", "warn"], limit: 20, since: Date.now() - 60000 // Last minute }) ``` ### Network Analysis ```javascript // Monitor API calls and responses await debug_network_activity({ sessionId: "user1", filter: "xhr", limit: 10 }) ``` ### WebSocket Debugging ```javascript // Perfect for Phoenix LiveView await debug_websocket_messages({ sessionId: "user1", limit: 5 }) ``` ### Performance Monitoring ```javascript // 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: ```bash # 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: ```bash # 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 ```javascript await session_create({ sessionId: "unique-id", url: "https://example.com", contextId: "optional-context", enableMonitoring: true // Enable real-time debugging }) ``` ### Screenshot Options ```javascript await page_screenshot({ sessionId: "user1", path: "screenshot.png", fullPage: true // Capture entire page }) ``` ### Drag Operations ```javascript 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.**