Firefox DevTools MCP

Firefox DevTools MCP

一个 Model Context Protocol 服务，可让 AI Agent 使用 Firefox。它有两种主要用途：

• Agent 式浏览：Agent 使用浏览器执行常规任务，例如阅读页面、填写表单，以及完成网站上的多步骤流程。
• Agent 辅助 Web 开发：Agent 加载你正在开发的页面，并使用开发者工具检查页面，例如控制台、网络请求、调试器和性能分析器。

它通过 WebDriver BiDi（借助 Selenium WebDriver）控制 Firefox，并支持 Claude Code、Claude Desktop、Cursor、Cline 和其他 MCP 客户端。

代码仓库：https://github.com/mozilla/firefox-devtools-mcp

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

安全

浏览器 MCP 服务存在固有风险。以下是几项重要做法：

• 使用专用的 Firefox 配置文件。 切勿让服务使用你的常用配置文件运行——Agent 可以访问浏览器能够访问的所有内容，包括 Cookie 和已保存的会话。
• 谨慎选择访问的网站。 页面可能会返回旨在操纵 Agent 的内容（提示词注入）。请只访问你控制或信任的网站。
• 仅启用所需的工具模块。 默认的 basic 预设已包含 evaluate_script；--tool-preset slim 会移除它。更高阶的预设（例如 --tool-preset developer，包含调试、网络、控制台和性能分析器）以及 --tool-preset mozilla（特权上下文）会进一步扩大 Agent 的能力。

请参阅 SECURITY.md，了解完整的风险说明以及漏洞报告方式。

要求

• Node.js ≥ 20.19.0
• 已安装 Firefox 100+（自动检测，或传入 --firefox-path）

使用 npx 与 Claude Code 或 Codex 安装并使用

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

选项 A — CLI

Claude Code

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

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

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

Codex

codex mcp add firefox-devtools -- npx @mozilla/firefox-devtools-mcp@latest

# Headless + viewport via args
codex mcp add firefox-devtools -- \
  npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720

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

选项 B — 编辑配置文件

Claude Code

添加到 Claude Code 的 mcp_settings.json：

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

Codex

添加到 ~/.codex/config.toml：

[mcp_servers.firefox-devtools]
command = "npx"
args = ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"]

[mcp_servers.firefox-devtools.env]
START_URL = "about:blank"

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

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

使用 MCP Inspector 试用

npx @modelcontextprotocol/inspector npx @mozilla/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
• list_downloads（始终捕获）、set_download_behavior
• screenshot_page、list_console_messages

CLI 选项

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

• --firefox-path — Firefox 二进制文件的绝对路径
• --headless — 无界面运行（FIREFOX_HEADLESS=true）
• --viewport 1280x720 — 初始窗口大小
• --profile-path — 使用指定的 Firefox 配置文件。Firefox 会在该路径的 firefox_devtools_mcp_profile 子文件夹中运行，并以 .firefox-devtools-mcp 文件标记；如果 --profile-path 指向已标记的配置文件，则会直接复用
• --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）
• --idle-timeout — 连接现有实例的会话在无工具调用后释放 Firefox 前等待的秒数，默认为 1800。Firefox 一次只接受一个客户端，因此只有在释放后其他客户端才能连接。下次调用工具时会重新连接，并选中届时在 Firefox 中处于活动状态的标签页（IDLE_TIMEOUT）
• --pref name=value — 在启动时通过 moz:firefoxOptions 设置 Firefox 首选项（可重复指定）
• --tool-preset — 选择要启用的工具模块：slim、basic（默认）、developer、mozilla 或 all。请参阅工具模块和预设。（TOOL_PRESET）
• --tools — 明确指定要启用的工具模块列表，完全覆盖 --tool-preset（例如 --tools pages network script）。请参阅工具模块和预设。
• --enable-script — 已弃用，请改用 --tool-preset developer 或 --tools ... script debugging。 选择 developer 工具预设。（ENABLE_SCRIPT=true）
• --enable-privileged-context — 已弃用，请改用 --tool-preset mozilla 或 --tools ... privileged prefs。 选择 mozilla 工具预设。需要 MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1（ENABLE_PRIVILEGED_CONTEXT=true）
• --android-device — 启用 Firefox for Android 模式；值为 ADB 设备序列号（例如 emulator-5554）。运行 adb devices 可列出已连接的设备。省略该值或使用 auto，可自动选择唯一已连接的设备。
• --android-wipe-app-data — 确认 Android 模式会清除目标应用的所有数据。必须与 --android-device 一起使用。（ANDROID_WIPE_APP_DATA=true）
• --android-package — Android 应用包名称，默认为 org.mozilla.firefox。其他包：Firefox Beta 使用 org.mozilla.firefox_beta，Firefox Nightly 使用 org.mozilla.fenix，Firefox Nightly Debug 使用 org.mozilla.fenix.debug，geckoview 使用 org.mozilla.geckoview_example（ANDROID_PACKAGE）
• --unrestricted-save-paths — 允许 saveTo 参数将文件写入磁盘上的任意位置，而不是默认目录。请参阅将大量输出保存到磁盘和 SECURITY.md 中的安全说明。（UNRESTRICTED_SAVE_PATHS=true）
• --log-file — 将 MCP 服务日志写入文件，而不是 stderr。适用于使用会隐藏服务输出的 MCP 客户端进行调试。设置 DEBUG=* 还可包含详细调试日志。示例：--log-file /tmp/firefox-mcp.log

工具模块和预设

工具按模块分组。你可以通过命名预设（--tool-preset）或显式列表（--tools）选择要公开的模块。两者同时指定时，以 --tools 为准，并忽略预设。

预设（每个预设都包含前一个预设的全部内容）：

• slim — 浏览和交互页面所需的最少工具
• basic（默认）— 添加常规浏览工具
• developer — 添加供 Web 开发者使用的工具
• mozilla — 添加供 Firefox 开发者使用的工具
• all — 包含所有模块

请参阅 docs/tools.md，了解模块列表以及每个预设包含的模块。

请注意，默认的 basic 包含 script，因此也包含 evaluate_script 工具。关于这对攻击面意味着什么，请参阅 SECURITY.md；如需移除该工具，请使用 --tool-preset slim 或显式指定 --tools 列表。

# Use the developer preset (adds network, console, debugging and profiler tools)
npx @mozilla/firefox-devtools-mcp --tool-preset developer

# Enable only the modules you need
npx @mozilla/firefox-devtools-mcp --tools pages network console

prefs 和 privileged 模块需要设置 MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1，且仅在 Mozilla 内部构建版本中可用。launch 模块也需要 Mozilla 内部构建版本：它会使用调用者指定的二进制文件、配置文件、环境和首选项重启 Firefox，而这属于应由操作员负责的配置更改。请改用 --pref、--firefox-path 和其他命令行选项。bidi 模块同样需要 Mozilla 内部构建版本：它可以发送任意 WebDriver BiDi 命令，因此能够访问其他模块公开的所有内容。即使请求了这些模块，公开发行包也会跳过它们，并记录一条警告，列出被跳过的模块。

实用首选项（--pref）

• remote.prefs.recommended=false。Firefox 在自动化运行时，会应用 RecommendedPreferences，以修改浏览器行为，便于测试。将 remote.prefs.recommended 设为 false，即可跳过这些首选项，使配置更接近日常使用的 Firefox 实例。
• remote.log.level=Trace。启用 Firefox 中详细的 WebDriver 协议日志。MCP 服务会自动向 geckodriver 传递相应的日志级别，使两端的日志详细程度一致。
• app.update.disabledForTesting=false。允许 Firefox 自动下载并安装更新。请注意，更新可能会中断会话。还必须同时设置 remote.prefs.recommended=false。

Android 版 Firefox

使用 --android-device 自动化运行在 Android 设备上的 Firefox。需要将 adb 添加到 PATH，geckodriver 则由系统自动管理。

警告： Android 模式会在每次会话开始前清除目标应用的所有数据。 标签页、历史记录、书签、密码、Cookie 和设置都会丢失。创建会话时，geckodriver 会运行 adb shell pm clear <package>，且不提供跳过此操作的方式；随后会在独立的临时配置文件中运行会话， 并在会话结束后删除该配置文件。 因此，--android-device 必须与 --android-wipe-app-data 一同使用；你应安装专用于自动化的构建版本，而不是自动化你日常使用的浏览器。 Bug 2064088 正在跟踪为 geckodriver 添加保留现有应用数据的选项。

# List connected devices
adb devices

# Launch Firefox for Android on the single connected device
npx @mozilla/firefox-devtools-mcp --android-device auto --android-wipe-app-data

# Target a specific device
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-wipe-app-data

# Use Firefox Nightly instead
npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix --android-wipe-app-data

主机与设备之间的端口转发由 geckodriver 自动处理。

连接到现有的 Firefox

使用 --connect-existing 自动化你的真实浏览会话，并保留 Cookie、登录状态和已打开的标签页：

# Start Firefox with Marionette and the Remote Agent (BiDi)
firefox --marionette --remote-debugging-port

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

这两个标志都必须设置，因为 MCP 同时使用 WebDriver Classic（--marionette）和 WebDriver BiDi（--remote-debugging-port）。如果 Firefox 仅使用 --marionette 启动，MCP 服务将无法连接，并会要求你同时设置这两个标志后重新启动 Firefox。

如果 Firefox 已使用相同配置文件运行，上述命令只会在该实例中打开一个新窗口：这些标志会被忽略，因此 Marionette 和 Remote Agent 都不会启动。

若要让日常使用的 Firefox 在不启用 Marionette 的情况下继续运行，请为 MCP 服务指定专用配置文件。Firefox 每个配置文件只运行一个进程，因此两个实例可以并行运行；Agent 只能访问你在该配置文件中登录的内容：

# Once: create a dedicated profile
firefox -CreateProfile firefox-mcp

# Start it with Marionette and the Remote Agent, next to your everyday Firefox
firefox -P firefox-mcp --marionette --remote-debugging-port

警告： 日常浏览时不要让 Marionette 保持启用状态。它会设置 navigator.webdriver = true 并更改其他浏览器指纹信号， 这可能触发 Cloudflare、Akamai 等网站的机器人检测。 仅在需要 MCP 自动化时启用 Marionette，然后正常重启 Firefox， 或按上文所示在专用配置文件中运行。

工具概览

请参阅 docs/tools.md，查看按模块整理的完整工具列表，以及工具说明和参数（根据源代码生成）。

将较大的输出保存到磁盘

较大的工具输出可能会占用 CLI 客户端（如 Claude Code）的大量上下文。多个 工具接受可选的 saveTo 参数，可将结果写入文件，而不是以内联形式返回。请参阅 docs/tools.md 查看支持该参数的工具列表。 saveTo 支持以下三种形式之一：

• 文件路径（相对于当前工作目录，或 ~/.firefox-devtools-mcp/output 内的绝对路径；会创建父目录）。指向 Firefox 配置文件或此服务会读取的文件的路径将被拒绝
• 已存在的目录（将在其中生成带时间戳的文件）
• true（将在 ~/.firefox-devtools-mcp/output/ 下生成带时间戳的文件）

响应会返回路径和字节大小。保存的文件始终包含完整、未经截断的数据：内联大小限制（控制台消息上限、网络标头截断、快照行数上限）均不适用于该文件。

生成文本的工具还接受 preview，用于指定保存输出中要以内联形式回显的字符数，作为简短摘录。docs/tools.md 中的列表会标明哪些工具支持此参数。

screenshot_page({ saveTo: "page.png" })
take_snapshot({ saveTo: true })
list_network_requests({ urlContains: "api", saveTo: "network.json" })
evaluate_script({ function: "() => performance.getEntries()", saveTo: true, preview: 2000 })

默认情况下，保存路径受到限制：相对路径以当前工作目录为基准解析，绝对路径仅允许位于 ~/.firefox-devtools-mcp 内。超出这些位置的路径会被拒绝。使用 --unrestricted-save-paths 启动服务，即可写入任意位置，包括该目录之外的绝对路径。

之后可以使用 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

有关本地开发、测试和 CI 的更多详情，请参阅 CONTRIBUTING.md。

故障排除

• 未找到 Firefox：传入 --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox"（macOS），或传入适用于你的操作系统的正确路径。
• 首次运行较慢：Selenium 会建立 BiDi 会话；后续运行会更快。
• UID 失效：UID 在元素被移除或页面导航之前一直有效；如果 UID 工具报告某个 UID 已失效，请获取新的快照（take_snapshot）。
• Windows 10：发现 MCP 服务“firefox-devtools”时出错：MCP 错误 -32000：连接已关闭

  • 解决方案 1 使用 cmd /c 包装（详情）：

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

  • 解决方案 2 使用 npx 的绝对路径（调整扩展名——.cmd、.bat、.exe 或 .ps1——以匹配你的设置）：

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

版本管理

• 1.0 之前的 API：版本以 0.x 开头。使用 npx 搭配 @latest 获取最新版本。

参与贡献

有关如何提交问题、运行测试以及在本地参与项目开发，请参阅 CONTRIBUTING.md。

作者

由 Mozilla 维护。

许可证

你可以选择采用 MIT 或 Apache 2.0 许可证。