firefox-devtools-mcp

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 指定）

使用 Claude Code 或 Codex 安裝與使用（npx）

建議：使用 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-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 在自動化模式下執行時，會套用建議偏好設定來修改瀏覽器行為以利測試。將 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 任一授權下使用。