firefox-devtools-mcp

官方

用於 Firefox DevTools 的 Model Context Protocol 伺服器，可讓 AI 助手透過遠端除錯協定檢查並控制 Firefox 瀏覽器。

GitHub

307

你可以用 Firefox DevTools MCP 做什麼？

導航和管理瀏覽器分頁 — 使用 navigate_page、select_page 和 list_pages 開啟、關閉、切換和導航頁面。
檢查並與頁面內容互動 — 使用 take_snapshot 擷取文字快照，然後透過唯一 ID 使用 click_by_uid 和 fill_by_uid 點擊或填寫表單欄位。
監控網路活動 — 使用 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 — 無 UI 執行 (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 — 用於 connect-existing 模式的 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 的功能（主控台事件、網路事件）在 connect-existing 模式下無法使用；所有其他功能則正常運作。

警告： 在一般瀏覽期間不要保持啟用 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

請參閱 CONTRIBUTING.md 以取得更多關於本機開發、測試和 CI 的詳細資訊。

疑難排解

找不到 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 授權。