Firefox DevTools MCP

用于通过 WebDriver BiDi（经由 Selenium WebDriver）自动化 Firefox 的模型上下文协议 (MCP) 服务器。适用于 Claude Code、Claude Desktop、Cursor、Cline 及其他 MCP 客户端。

仓库地址：https://github.com/mozilla/firefox-devtools-mcp

注意：此 MCP 服务器需要本地安装 Firefox 浏览器，无法在 glama.ai 等云托管服务上运行。请使用 npx firefox-devtools-mcp@latest 在本地运行，或使用提供的 Dockerfile 通过 Docker 运行。

要求

• Node.js ≥ 20.19.0

• 已安装 Firefox 100+（自动检测，或通过 --firefox-path 指定）

安装并与 Claude Code (npx) 一起使用

推荐：使用 npx，以便始终运行 npm 上发布的最新版本。

选项 A — Claude Code CLI

claude mcp add firefox-devtools npx firefox-devtools-mcp@latest

通过参数或环境变量传递选项。示例：

# Headless + viewport via args
claude mcp add firefox-devtools npx firefox-devtools-mcp@latest -- --headless --viewport 1280x720

# Or via environment variables
claude mcp add firefox-devtools npx firefox-devtools-mcp@latest \
  --env START_URL=https://example.com \
  --env FIREFOX_HEADLESS=true

选项 B — 编辑 Claude Code 设置 JSON

添加到您的 Claude Code 配置文件中：

• macOS: ~/Library/Application Support/Claude/Code/mcp_settings.json

• Linux: ~/.config/claude/code/mcp_settings.json

• Windows: %APPDATA%\Claude\Code\mcp_settings.json

{
  "mcpServers": {
    "firefox-devtools": {
      "command": "npx",
      "args": ["-y", "firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "env": {
        "START_URL": "about:home"
      }
    }
  }
}

选项 C — 辅助脚本（本地开发构建）

npm run setup
# Choose Claude Code; the script saves JSON to the right path

使用 MCP Inspector 进行尝试

npx @modelcontextprotocol/inspector npx firefox-devtools-mcp@latest --start-url https://example.com --headless

然后调用如下工具：

• list_pages, select_page, navigate_page

• take_snapshot 然后 click_by_uid / fill_by_uid

• list_network_requests（常驻捕获）, get_network_request

• screenshot_page, list_console_messages

CLI 选项

您可以传递标志或环境变量（右侧为名称）：

• --firefox-path — Firefox 二进制文件的绝对路径

• --headless — 在无界面模式下运行 (FIREFOX_HEADLESS=true)

• --viewport 1280x720 — 初始窗口大小

• --profile-path — 使用特定的 Firefox 配置文件

• --firefox-arg — 额外的 Firefox 参数（可重复）

• --start-url — 启动时打开此 URL (START_URL)

• --accept-insecure-certs — 忽略 TLS 错误 (ACCEPT_INSECURE_CERTS=true)

• --connect-existing — 连接到已运行的 Firefox 而不是启动新实例 (CONNECT_EXISTING=true)

• --marionette-port — 用于连接现有模式的 Marionette 端口，默认为 2828 (MARIONETTE_PORT)

• --pref name=value — 通过 moz:firefoxOptions 在启动时设置 Firefox 首选项（可重复）

• --enable-script — 启用 evaluate_script 工具，在页面上下文中执行任意 JavaScript (ENABLE_SCRIPT=true)

• --enable-privileged-context — 启用特权上下文工具：列出/选择特权上下文、评估特权脚本、获取/设置 Firefox 首选项以及列出扩展。需要 MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)

关于 --pref 的说明：当 Firefox 在自动化模式下运行时，它会应用 RecommendedPreferences，这些首选项会修改浏览器行为以进行测试。--pref 选项允许在需要时覆盖这些默认值。

连接到现有的 Firefox

使用 --connect-existing 来自动化您真实的浏览会话——保持 Cookie、登录状态和打开的标签页不变：

# Start Firefox with Marionette enabled
firefox --marionette

# Run the MCP server
npx firefox-devtools-mcp --connect-existing --marionette-port 2828

或者在 about:config（或 user.js）中将 marionette.enabled 设置为 true，以便在每次启动时启用 Marionette。

依赖 BiDi 的功能（控制台事件、网络事件）在连接现有模式下不可用；所有其他功能均可正常工作。

警告：请勿在正常浏览时保持 Marionette 启用。它会将 navigator.webdriver 设置为 true 并更改其他浏览器指纹信号，这可能会触发 Cloudflare、Akamai 等受保护网站的机器人检测。仅在需要 MCP 自动化时启用 Marionette，之后请正常重启 Firefox。

工具概览

• 页面：列出/新建/导航/选择/关闭

• 快照/UID：获取/解析/清除

• 输入：点击/悬停/填充/拖拽/上传/表单填充

• 网络：列出/获取（ID 优先，过滤器，常驻捕获）

• 控制台：列出/清除

• 屏幕截图：页面/按 UID（对于 CLI 环境，可选 saveTo）

• 脚本：evaluate_script

• 特权上下文：列出/选择特权（“chrome”）上下文，evaluate_privileged_script（需要 MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1）

• WebExtension：install_extension, uninstall_extension, list_extensions（列出需要 MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1）

• Firefox 管理：get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs

• 实用工具：接受/关闭对话框，历史记录后退/前进，设置视口

针对 Claude Code 的屏幕截图优化

在 Claude Code CLI 中使用屏幕截图时，base64 图像数据可能会占用大量上下文。请使用 saveTo 参数将屏幕截图保存到磁盘：

screenshot_page({ saveTo: "/tmp/page.png" })
screenshot_by_uid({ uid: "abc123", saveTo: "/tmp/element.png" })

然后可以使用 Claude Code 的 Read 工具查看该文件，而不会影响上下文大小。

本地开发

npm install
npm run build

# Run with Inspector against local build
npx @modelcontextprotocol/inspector node dist/index.js --headless --viewport 1280x720

# Or run in dev with hot reload
npm run inspector:dev

测试

npm run test:run          # all tests once (unit + integration)
npm test                  # watch mode

有关运行特定测试套件、端到端场景覆盖范围和已知问题的完整详细信息，请参阅 docs/testing.md。

故障排除

• 未找到 Firefox：请传递 --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox"（macOS）或您操作系统上的正确路径。

• 首次运行缓慢：Selenium 需要设置 BiDi 会话；后续运行会更快。

• 导航后 UID 过期：在使用 UID 工具之前，请获取新的快照 (take_snapshot)。

• Windows 10：MCP 服务器 'firefox-devtools' 发现期间出错：MCP error -32000: Connection closed

  • 解决方案 1 使用 cmd 调用（更多信息请见 https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310）

    "mcpServers": {
      "firefox-devtools": {
        "command": "cmd",
        "args": ["/c", "npx", "-y", "firefox-devtools-mcp@latest"]
      }
    }

    关键更改：在 Windows 上，通过 npx 运行 Node.js 包通常需要 cmd /c 前缀才能从 VSCode 扩展宿主等其他进程中正确执行。因此，"command": "npx" 被替换为 "command": "cmd"，实际的 npx 命令被移至 "args" 数组中，并在前面加上 "/c"。此修复允许 Windows 正确解释命令并启动服务器。

  • 解决方案 2 您可以写入 npx 的绝对路径，而不是使用另一层 shell：

    "mcpServers": {
      "firefox-devtools": {
        "command": "C:\\nvm4w\\nodejs\\npx.ps1",
        "args": ["-y", "firefox-devtools-mcp@latest"]
      }
    }

    注意：上述路径仅为示例。您必须根据机器上 npx 的实际位置进行调整。根据您的设置，文件扩展名可能是 .cmd、.bat 或 .exe，而不是 .ps1。此外，请确保使用双反斜杠 (\\) 作为路径分隔符，这是 JSON 格式的要求。

版本控制

• 1.0 之前的 API：版本从 0.x 开始。请在 npx 中使用 @latest 以获取最新版本。

CI 和发布

• 包含用于 CI、发布和 npm 发布的 GitHub Actions。有关详细信息和所需密钥，请参阅 docs/ci-and-release.md。

问题与贡献

问题在 Bugzilla 上进行跟踪，产品为 Developer Infrastructure，组件为 AI for Development。

• 提交新问题

• 元 Bug（跟踪所有 firefox-devtools-mcp 问题）

如需提问和讨论，请加入 #firefox-devtools-mcp Matrix 聊天室。

作者

由 Mozilla 维护。