firefox-devtools-mcp

官方

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

GitHub

311

你可以用 Firefox DevTools MCP 做什么？

导航与管理浏览器标签页 — 使用 navigate_page、select_page 和 list_pages 打开、关闭、切换标签页及浏览页面。
检查并与页面内容交互 — 通过 take_snapshot 捕获文本快照，然后使用 click_by_uid 和 fill_by_uid 根据唯一 ID 点击或填写表单字段。
监控网络活动 — 使用 list_network_requests 列出所有捕获的网络请求，并通过 get_network_request 查看单个请求详情。
捕获截图 — 使用 screenshot_page 截取全页截图，或通过 screenshot_by_uid 针对特定元素截图，并可选择保存到磁盘。
在页面中执行 JavaScript — 当 --enable-script 标志激活时，使用 evaluate_script 在页面上下文中运行任意脚本。
控制现有的 Firefox 会话 — 使用 --connect-existing 附加到正在运行的 Firefox 实例，以自动化当前标签页、Cookie 和登录信息。

文档

Firefox DevTools MCP

通过 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 配置文件。 切勿在您的常规配置文件上运行服务器——代理可以访问浏览器能触及的任何内容，包括 Cookie 和已保存的会话。
谨慎选择访问的网站。 页面可能返回旨在操纵代理的内容（提示注入）。请仅访问您控制或信任的网站。
除非必要，避免启用额外标志。 --enable-script 和 --enable-privileged-context 会显著扩展代理的能力范围。

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

环境要求

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

安装并与 Claude Code (npx) 配合使用

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

选项 A — Claude Code CLI

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

选项 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", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "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
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）和调试工具（列出脚本、检查源代码、设置日志点）。调试工具需要 Firefox 153+。（ENABLE_SCRIPT=true）
--enable-privileged-context — 启用特权上下文工具：列出/选择特权上下文、执行特权脚本、获取/设置 Firefox 首选项以及列出扩展。需要 MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1（ENABLE_PRIVILEGED_CONTEXT=true）
--android-device — 启用 Firefox for Android 模式；值为 ADB 设备序列号（例如 emulator-5554）。运行 adb devices 列出已连接的设备。省略该值或使用 auto 可自动选择单个已连接的设备。
--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）
--log-file — 将 MCP 服务器日志写入文件而非 stderr。适用于调试那些隐藏服务器输出的 MCP 客户端会话。设置 DEBUG=* 可同时包含详细的调试日志。示例：--log-file /tmp/firefox-mcp.log

有用的首选项（`--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。需要 adb 在您的 PATH 中以及 geckodriver，后者会自动管理。

# List connected devices
adb devices

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

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

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

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

连接到现有的 Firefox

使用 --connect-existing 自动化您真实的浏览会话——保留 Cookie、登录信息和打开的标签页：

# Start Firefox with Marionette enabled
firefox --marionette

# Run the MCP server
npx @mozilla/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（可选 saveTo 用于 CLI 环境）
脚本：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
性能分析器：profiler_is_active、profiler_start（预设或显式配置）、profiler_stop（将性能分析文件保存到下载目录）
实用工具：接受/关闭对话框、历史记录后退/前进、设置视口

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

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

故障排除

找不到 Firefox：传递 --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox"（macOS）或您操作系统上的正确路径。
首次运行缓慢：Selenium 正在建立 BiDi 会话；后续运行会更快。
导航后 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 开头。使用 @latest 配合 npx 获取最新版本。

贡献

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

作者

由 Mozilla 维护。

许可证

根据您的选择，遵循 MIT 或 Apache 2.0 许可证。