Firefox MCP Server

Firefox MCP服务器

高级Firefox浏览器自动化，具有全面的调试功能

一个强大的模型上下文协议（MCP）服务器，通过28个专用工具提供复杂的Firefox浏览器自动化。专为需要多会话管理、实时调试和全面web交互功能的AI助手和自动化工作流程而设计。

🌟 主要特点

多会话架构

• 独立浏览器会话：每个会话都在一个完全独立的上下文中运行，具有独立的Cookie、存储和调试
• 非常适合多人游戏测试：无缝测试多人游戏和多用户应用程序
• 并行操作：从单个界面同时管理多个浏览器会话

综合调试套件

• 实时控制台监控：捕获所有控制台输出（日志、错误、警告、信息、调试）
• JavaScript错误跟踪：使用完整堆栈跟踪监视未处理的错误
• 网络活动监控：跟踪HTTP请求、响应和计时数据
• WebSocket流量捕获：非常适合Phoenix LiveView和实时应用程序调试
• 性能指标：监视DOM计时、绘制事件和内存使用情况

高级交互能力

• 精确的元素交互：单击、键入并与任何web元素交互
• 键盘事件模拟：发送复杂的组合键和快捷键
• 拖放操作：平滑拖动操作，可自定义时间和步骤
• JavaScript执行：在浏览器上下文中运行自定义JavaScript

🚀 快速开始

安装

npm install firefox-mcp-server
npx playwright install firefox

基本用法

添加到MCP客户端配置中：

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

示例：多用户测试

// 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})

🛠️ 完整的工具参考

浏览器管理

• browser_launch -启动具有调试功能的Firefox
• browser_close -关闭浏览器并清理所有资源

会话管理

• session_create -创建具有独立状态的隔离浏览器会话
• session_list -列出所有活动会话及其URL和状态
• session_close -关闭特定会话并释放资源
• session_set_active -为后续操作设置默认会话

页面导航

• page_navigate -导航到任何URL
• page_reload -刷新当前页面
• history_back / history_forward -浏览器历史导航
• url_get_current -获取当前页面URL

元素交互

• element_click -按选择器或坐标单击元素
• element_drag -带有流畅动画的拖放操作
• input_type -在输入框和文本区域中键入文本
• keyboard_press -使用修饰符支持发送键盘事件
• element_wait -等待元素出现或可见

内容提取

• html_extract -从页面或元素中提取HTML内容
• text_extract -获取可见文本内容
• page_screenshot -使用灵活的选项捕获屏幕截图

高性能

• javascript_execute -在浏览器上下文中运行自定义JavaScript

综合调试工具

• debug_console_logs -监控浏览器控制台输出
• debug_javascript_errors -跟踪JavaScript错误和异常
• debug_network_activity -监控HTTP请求和响应
• debug_websocket_messages -捕获WebSocket流量（LiveView友好）
• debug_performance_metrics -获取计时和内存使用数据
• debug_activity_all -所有调试信息的组合馈送
• debug_monitoring_start -开始全面监控
• debug_buffers_clear -清除累积的调试数据
• debug_helpers_inject -注入自定义调试实用程序

🎯 用例

Web应用程序测试

• 带有视觉验证的自动化UI测试
• 表单提交和验证测试
• 跨浏览器兼容性验证
• 性能监控和优化

多人游戏开发

• 多玩家会话模拟
• 实时状态同步测试
• WebSocket消息流调试
• 客户端预测验证

Phoenix LiveView开发

• LiveView事件流监控
• 实时更新验证
• WebSocket连接调试
• 多用户交互测试

电子商务和SaaS测试

• 多用户结账流程
• 不同用户角色的会话隔离
• 实时库存更新
• 支付流测试

📊 调试功能

控制台监控

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

网络分析

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

WebSocket调试

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

性能监控

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

⚙️ 故障排除

未找到Playwright浏览器错误

如果您遇到以下错误：

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

解决方案：需要安装Playwright浏览器。运行：

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

这将下载Playwright用于自动化的Firefox浏览器二进制文件。此问题已于2025-08-03解决，当时MCP服务器因缺少浏览器二进制文件而无法启动。

🔧 Claude代码配置

本地配置

Claude Code使用位于以下位置的项目特定配置：

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

此配置包括：

1. 启用MCP服务器：The firefox-control 服务器已启用 enabledMcpjsonServers
2. 权限：各种工具权限都被列入白名单，包括所有Firefox MCP工具

MCP服务器配置

Firefox MCP服务器在Claude代码中配置，使用：

# 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)

服务器从运行 /home/luke/workbench/firefox-mcp-server/ 使用main index.js 文件（内部使用 index-multi-debug.js 实施）。

🔧 配置选项

会话创建

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

屏幕截图选项

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

拖动操作

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

📁 项目结构

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

🤝 贡献

我们欢迎捐款！该项目旨在：

• LLM友好：针对AI助手发现优化的工具名称和描述
• 可扩展：易于添加新的浏览器自动化功能
• 有据可查：综合示例和文件

📋 需求

• Node.js：18.0.0或更高
• 火狐：通过Playwright自动安装
• MCP客户端：Claude Code、Cline或其他MCP兼容工具

🔒 安全

此服务器提供全面的浏览器自动化功能。仅与受信任的MCP客户端一起使用。服务器可以：

• 在浏览器上下文中执行任意JavaScript
• 监控所有网络流量和WebSocket消息
• 访问页面内容和用户交互
• 截取屏幕截图并访问媒体设备

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

______________________________________________________________________

非常适合使用web应用程序、多人游戏和实时调试场景的AI助手。