firefox-devtools-mcp

官方

用于 Firefox 开发者工具的模型上下文协议服务器——使 AI 助手能够通过远程调试协议检查和操控 Firefox 浏览器

GitHub

389

试用此 MCP赞助

你可以用 Firefox DevTools MCP 做什么？

导航和检查页面 — 请求打开 URL、列出打开的标签页、切换页面，或通过 navigate_page、list_pages 和 get_page_text 提取页面文本。
与页面元素交互 — 使用 take_snapshot 获取无障碍快照，然后通过其 UID 使用 click_by_uid 和 fill_by_uid 点击、填写或悬停在元素上。
监控网络和控制台活动 — 使用 list_network_requests/get_network_request 检索捕获的网络请求，或通过 list_console_messages 读取控制台消息。
捕获截图和录制 — 使用 screenshot_page 保存页面截图，或使用 screencast_start/screencast_stop 将视口录制为视频。
运行自定义 JavaScript — 使用 evaluate_script 在页面上下文中执行任意脚本，可选地在隔离的 sandbox 领域中运行。
管理下载和浏览器状态 — 使用 list_downloads/clear_downloads 列出或清除下载，通过 set_download_behavior 控制下载行为，或使用 restart_firefox 重启 Firefox。

文档

Firefox DevTools MCP

用于通过 WebDriver BiDi（基于 Selenium WebDriver）自动化 Firefox 的 Model Context Protocol 服务器。适用于 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 配置文件。 切勿对日常使用的配置文件运行服务器——代理可以访问浏览器能访问的一切，包括 Cookie 和已保存的会话。
谨慎选择访问的网站。 网页可能返回旨在操纵代理的内容（提示注入）。只访问你控制或信任的站点。
只启用你需要的工具模块。 默认的 basic 预设已包含 evaluate_script；--tool-preset slim 可将其移除。更高的预设如 --tool-preset developer（调试、网络、控制台、性能分析器）和 --tool-preset mozilla（特权上下文）会进一步扩展代理的能力。

有关风险的完整说明以及如何报告漏洞，请参阅 SECURITY.md。

环境要求

Node.js ≥ 20.19.0
已安装 Firefox 100+（自动检测，或通过 --firefox-path 指定）

通过 npx 安装并与 Claude Code 或 Codex 一起使用

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

选项 A — 命令行

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

命令行选项

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

--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 偏好（可重复）
--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。其他包：org.mozilla.firefox_beta 用于 Firefox Beta，org.mozilla.fenix 用于 Firefox Nightly，org.mozilla.fenix.debug 用于 Firefox Nightly Debug，org.mozilla.geckoview_example 用于 geckoview（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 优先，预设被忽略。

模块：pages、snapshot、input、network、console、screenshot、downloads、 utilities、management、webextension、profiler、screencast、script、debugging、 prefs、privileged。

预设（每个都是前一个的超集）：

slim — pages、snapshot、input、screenshot
basic（默认）— slim 加上 downloads、script、utilities、management、webextension、screencast
developer — basic 加上 debugging、network、console、profiler
mozilla — developer 加上 prefs、privileged
all — 所有模块

请注意，默认的 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 内部构建中可用。公共包即使被请求也会跳过这些模块，并记录一条警告，说明被丢弃的模块名称。

有用的偏好设置（`--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。

Firefox for Android

使用 --android-device 自动化运行在 Android 设备上的 Firefox。需要 PATH 中有 adb，以及自动管理的 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。

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

工具概览

有关按模块划分的完整工具列表（含描述和参数，从源码生成），请参阅 docs/tools.md。

页面：list/new/navigate/select/close/get_page_text（get_page_text 支持可选的 saveTo）
快照/UID：take/resolve/clear（take 支持可选的 saveTo）
输入：click/hover/fill/drag/upload/form fill
网络：list/get（ID 优先、过滤器、始终开启捕获；两者都支持可选的 saveTo）
下载：list_downloads/clear_downloads（始终开启捕获）、set_download_behavior（allow/deny/default）
控制台：list/clear（list 支持可选的 saveTo）
截图：page/by uid（可选 saveTo 用于 CLI 环境）
脚本：evaluate_script（可选 sandbox 用于隔离 realm；可选 saveTo 用于大量结果）
特权上下文：list/select 特权（"chrome"）上下文、evaluate_privileged_script（需要 MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1）
WebExtension：install_extension、uninstall_extension、list_extensions（list 需要 MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1）
Firefox 管理：get_firefox_info、get_firefox_output、restart_firefox
Firefox 偏好：get_firefox_prefs、set_firefox_prefs（需要 MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1）
性能分析器：profiler_is_active、profiler_start（预设或显式配置）、profiler_stop（将分析文件保存到下载目录）
屏幕录制：screencast_start（将页面视口录制为下载目录中的视频文件）、screencast_stop（需要 Firefox 154+）
实用工具：accept/dismiss 对话框、history back/forward、设置视口

将大量输出保存到磁盘

大型工具输出会消耗 CLI 客户端（如 Claude Code）的大量上下文。screenshot_page、screenshot_by_uid、take_snapshot、list_console_messages、 list_network_requests、get_network_request、get_page_text、 evaluate_script 和 evaluate_privileged_script 工具接受可选的 saveTo 参数，将结果写入文件而不是内联返回。saveTo 接受三种形式之一：

文件路径（相对于当前工作目录，或 ~/.firefox-devtools-mcp 内的绝对路径；父目录会自动创建）
现有目录（在其中生成带时间戳的文件）
true（在 ~/.firefox-devtools-mcp/output/ 下生成带时间戳的文件）

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

生成文本的工具（除截图外的所有工具）还接受 preview，即保存输出中要内联回显的字符数，作为简短摘录。截图没有预览。

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 许可下使用。

firefox-devtools-mcp

你可以用 Firefox DevTools MCP 做什么？

文档

Firefox DevTools MCP

安全性

环境要求

通过 npx 安装并与 Claude Code 或 Codex 一起使用

选项 A — 命令行

Claude Code

Codex

选项 B — 编辑配置文件

Claude Code

Codex

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

使用 MCP Inspector 试用

命令行选项

工具模块与预设

有用的偏好设置（--pref）

Firefox for Android

连接到现有的 Firefox

工具概览

将大量输出保存到磁盘

本地开发

故障排除

版本控制

贡献

作者

许可证

有用的偏好设置（`--pref`）