Firefox DevTools MCP 接入实操:给 AI 一个会用开发者工具的浏览器
给 AI 一个浏览器让它自己点——Firefox DevTools MCP 做的就是这件事,而且是 Mozilla 官方出品。装好之后 AI 可以替你打开页面、读正文、填表单、走完整的多步流程,也能切到开发者视角看网络请求、控制台报错和性能数据。这篇从安装前提醒讲到工具全景和 UID 操作模型,工具清单与报错行为都以本机实测为准。
本篇依据 mozilla/firefox-devtools-mcp 官方 README 与 docs/tools.md(0.10.5)整理,配图依据官方文档与本机实测绘制。系列总纲见 dbyun 教程中心。
先看两个硬前提
README 的 Requirements 节只有两行:Node.js ≥ 20.19.0,本机装有 Firefox 100+。第二行常被漏看——这个服务器自己不带浏览器,它通过 WebDriver BiDi 协议驱动你机器上的 Firefox,README 开头还专门加粗提醒:无法在 glama.ai 这类云端托管服务上运行,必须在本地跑(或者用它提供的 Dockerfile 自建容器)。Firefox 位置自动探测,找不到时用 --firefox-path 指定。
写这篇时本机正好卡在这两行上:Node 是 v20.16.0,低于要求的 20.19.0,npm 安装时直接给出 EBADENGINE 警告(Unsupported engine ... required node >=20.19.0);机器上也没有装 Firefox。结果是服务器照样能启动、工具列表照样能拿,但第一个需要浏览器的工具调用就失败——这段真实报错后面会展开,对判断「我这环境能不能用」很有参考价值。
版本与热度供参考:npm 最新 0.10.5(16 个已发布版本),GitHub star 实时 493(选题入池快照记 483),最近一次提交 2026-10-14。版本号还在 0.x,README 的 Versioning 节自己说了 Pre-1.0 API,用 npx 拉最新版即可。

图1 服务器在整个链路里的位置与两种官方用法
安装与客户端配置
官方推荐 npx 直接跑,不用全局装包。命令行客户端一行注册:
# Claude Code claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest # 无头模式 + 固定视口 claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720 # Codex codex mcp add firefox-devtools -- npx @mozilla/firefox-devtools-mcp@latest
配置文件方式(Claude Code 的 mcp_settings.json,Codex 的 ~/.codex/config.toml):
{
"mcpServers": {
"firefox-devtools": {
"command": "npx",
"args": ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
"env": {
"START_URL": "about:blank"
}
}
}
}
想先手动把玩再接客户端,README 给了现成路径——MCP Inspector:
npx @modelcontextprotocol/inspector npx @mozilla/firefox-devtools-mcp@latest --start-url https://example.com --headless
启动参数里值得记住的几个:--start-url 开机页;--profile-path 指定 Firefox profile(服务器会在其下的 firefox_devtools_mcp_profile 子目录里跑,带 .firefox-devtools-mcp 标记文件,指向已标记的 profile 可直接复用);--connect-existing 接管一个已在运行的 Firefox(配 --marionette-port,默认 2828)而不是新开一个;Android 设备调试走 --android-device,值是 ADB 序列号。
安全三件事,官方放在 README 最前面
这个项目的 README 把 Security 节放在 Requirements 之前,位置本身就是态度。三句话概括:
一,用专门的 Firefox profile,绝不用日常 profile 跑——agent 能碰到浏览器能碰到的所有东西,包括 cookies 和已保存的会话。二,谨慎选择让 agent 访问哪些网站,页面内容可能被构造成诱导 agent 的样子(prompt injection),只去你控制的或信任的站点。三,只开需要的工具模块,默认 basic 档已含 evaluate_script,介意的话 --tool-preset slim 会去掉它;更高档位(developer/mozilla)能力更大,风险面也更大。
工具全景:模块、预设与一个实测差异
工具按模块组织,用 --tool-preset 选预设或 --tools 显式列模块(两者同给时 --tools 优先)。预设共五档且逐级包含(官方原话:each is a superset of the previous):slim 只有浏览和交互的最小集;basic 默认档;developer 加上 network、console、profiler、debugging;mozilla 与 all 面向 Mozilla 内部构建,公开 npm 包不含特权模块。
本机实测(0.10.5,默认 basic):握手成功后 tools/list 返回 34 个工具,启动日志列出的模块是 pages、snapshot、input、screenshot、downloads、utilities、management、webextension、screencast、script,共 10 个。这里有个值得注意的出入:官方 docs/tools.md 的预设矩阵把 print 模块也标进 basic(合计应为 35 个工具),但实测 basic 并没有 print_page,需要打印 PDF 得 --tools print 显式开。文档表与实测清单不一致时,以实测为准——这类出入在快速迭代的项目里不罕见。

图2 模块 × 预设矩阵(转绘自官方 docs/tools.md,高亮行=官方表 basic 列,实测差异见图内说明)
高频工具按用途归拢一遍。页面类:list_pages 列标签页、new_page/navigate_page/select_page/close_page 管页面流转、get_page_text 取正文(默认上限 2 万字符)。交互类全走 UID(下一节展开):click_by_uid、fill_by_uid、fill_form_by_uid、press_key、type_text、upload_file_by_uid、hover_by_uid、drag_by_uid_to_uid。观测类:screenshot_page/screenshot_by_uid 截图、list_console_messages 看控制台、list_network_requests/get_network_request 看网络(后三者在 developer 档)。下载类:set_download_behavior 先设行为(allowed + downloadFolder),list_downloads 再查状态。脚本类:evaluate_script 在页面里执行 JS 取返回值——能力大,官方也把它列为安全考量之一。
大输出别硬塞对话上下文。多个工具支持 saveTo 参数把结果落盘(文件路径、目录或 true 放到 ~/.firefox-devtools-mcp/output/),配 preview 回传一小段摘录;落盘文件永远是全量数据,行数上限、截断都不适用。默认落盘位置有白名单限制,想写任意路径得加 --unrestricted-save-paths(官方同时提醒这会放大风险)。
UID 工作流:AI 怎么点中页面元素
这是整个项目最有设计感的部分。传统自动化要么给坐标(窗口一变就偏),要么让 AI 猜 CSS 选择器(页面一改就断)。这里的做法:每次操作前先 take_snapshot 抓 DOM 快照,给每个可交互元素分配稳定 UID,后续 click_by_uid/fill_by_uid 直接引用编号。UID 在元素被移除或页面导航之前一直有效,跨多次快照也有效。
一轮典型回合长这样(示意):
用户:去 example.com 搜一下 "duckdb"
→ navigate_page({url: "https://example.com"})
→ take_snapshot({selector: "#search"})
→ fill_by_uid({uid: "S12", value: "duckdb"})
→ click_by_uid({uid: "B7"})
→ get_page_text({maxLength: 5000})
take_snapshot 默认上限 100 行,复杂页面用 selector 圈范围(Vue/Livewire 这类应用可开 includeAll 关掉相关性过滤),全量树走 saveTo。UID 失效只有两个时刻——元素被移除、页面发生导航,届时任何 UID 工具都会报 stale,重拍快照即可;navigate_history 的文档里官方也直接注明 UIDs become stale。

图3 快照 → 定位 → 操作的完整回合与 UID 失效规则
环境不满足时会发生什么(真实记录)
前面提到本机 Node 20.16.0 + 无 Firefox,把这条链路完整跑了一遍。结果是分层的:
服务器能起。npm 只警告不拦截(EBADENGINE warn 之后照常装),进程启动日志打印 Enabled tool modules: pages, snapshot, input, screenshot, downloads, utilities, management, webextension, screencast, script,接着 Firefox DevTools MCP server running on stdio,Ready to accept tool requests。MCP 握手正常,tools/list 拿到 34 个工具。
工具调用失败。调 list_pages 时服务器尝试经 Selenium 启动 Firefox,返回 isError=true,错误全文如下:
Error: Unable to obtain browser driver. For more information on how to install drivers see https://www.selenium.dev/documentation/webdriver/troubleshooting/errors/driver_location/. Error: Error executing command for .../selenium-webdriver/bin/linux/selenium-manager with --browser,firefox,--language-binding,javascript,--output,json: SyntaxError: Unexpected end of JSON input
结论也简单:引擎版只是警告,真正卡死链路的是没有本机 Firefox。装上 Firefox(或用 --firefox-path 指到已有安装)之后这条报错才会消失。README 的 Troubleshooting 节另有对应条目:首跑慢是 Selenium 在建 BiDi 会话,后续会快;Windows 10 下 MCP 客户端报 Connection closed 的话,用 cmd /c 包一层 npx 或改用 npx 的绝对路径。
和其他浏览器自动化方案怎么选
同一赛道的 Playwright MCP 走自带的 Chromium 生态,开箱即用性好;这套方案的价值在于 Mozilla 官方维护、贴 DevTools 的深度能力(profiler、debugging logpoints 这些 Firefox 153+ 的新接口)以及 Firefox 独有的一些行为。日常表单抓取两者都能干,调试 Firefox 专属问题或扩展开发(install_extension 装扩展、Android 设备调试)时它没有替代品。
本文步骤、工具参数与报错引文依据 mozilla/firefox-devtools-mcp 官方 README 与 docs/tools.md(0.10.5,2026-10 抓取)及本机实测记录整理,版权归原作者所有。工具清单随版本变动较快,以官方文档为准。