firefox-devtools-mcp

Firefox DevTools MCP

Máy chủ Giao thức Ngữ cảnh Mô hình (MCP) để tự động hóa Firefox qua WebDriver BiDi (thông qua Selenium WebDriver). Hoạt động với Claude Code, Claude Desktop, Cursor, Cline và các máy khách MCP khác.

Kho lưu trữ: https://github.com/mozilla/firefox-devtools-mcp

Lưu ý: Máy chủ MCP này yêu cầu cài đặt trình duyệt Firefox cục bộ và không thể chạy trên các dịch vụ lưu trữ đám mây như glama.ai. Sử dụng npx @mozilla/firefox-devtools-mcp@latest để chạy cục bộ, hoặc sử dụng Docker với Dockerfile được cung cấp.

Bảo mật

Máy chủ MCP trình duyệt mang theo các rủi ro tiềm ẩn. Một vài thực hành quan trọng:

• Sử dụng hồ sơ Firefox chuyên dụng. Không bao giờ chạy máy chủ với hồ sơ thông thường của bạn — tác nhân có quyền truy cập vào bất cứ thứ gì trình duyệt có thể truy cập, bao gồm cookie và phiên đã lưu.
• Thận trọng về các trang web bạn truy cập. Các trang có thể trả về nội dung được thiết kế để thao túng tác nhân (tiêm prompt). Chỉ truy cập các trang bạn kiểm soát hoặc tin cậy.
• Chỉ bật các mô-đun công cụ bạn cần. Cài đặt trước basic mặc định đã bao gồm evaluate_script; --tool-preset slim loại bỏ nó. Các cài đặt trước cao hơn như --tool-preset developer (gỡ lỗi, mạng, bảng điều khiển, hồ sơ hiệu năng) và --tool-preset mozilla (ngữ cảnh đặc quyền) mở rộng thêm những gì tác nhân có thể làm.

Xem SECURITY.md để biết đầy đủ chi tiết về rủi ro và cách báo cáo lỗ hổng bảo mật.

Yêu cầu

• Node.js ≥ 20.19.0
• Firefox 100+ đã cài đặt (tự động phát hiện, hoặc truyền --firefox-path)

Cài đặt và sử dụng với Claude Code hoặc Codex (npx)

Khuyến nghị: sử dụng npx để bạn chạy phiên bản mới nhất đã phát hành từ npm.

Tùy chọn 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

Tùy chọn B — Chỉnh sửa tệp cấu hình

Claude Code

Thêm vào mcp_settings.json của Claude Code:

{
  "mcpServers": {
    "firefox-devtools": {
      "command": "npx",
      "args": ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "env": {
        "START_URL": "about:blank"
      }
    }
  }
}

Codex

Thêm vào ~/.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"

Tùy chọn C — Tập lệnh trợ giúp (bản dựng phát triển cục bộ)

npm run setup
# Choose Claude Code; the script saves JSON to the right path

Thử với MCP Inspector

npx @modelcontextprotocol/inspector npx @mozilla/firefox-devtools-mcp@latest --start-url https://example.com --headless

Sau đó gọi các công cụ như:

• list_pages, select_page, navigate_page
• take_snapshot sau đó click_by_uid / fill_by_uid
• list_network_requests (ghi hình luôn bật), get_network_request
• list_downloads (ghi hình luôn bật), set_download_behavior
• screenshot_page, list_console_messages

Tùy chọn CLI

Bạn có thể truyền cờ hoặc biến môi trường (tên ở bên phải):

• --firefox-path — đường dẫn tuyệt đối đến tệp thực thi Firefox
• --headless — chạy không có giao diện người dùng (FIREFOX_HEADLESS=true)
• --viewport 1280x720 — kích thước cửa sổ ban đầu
• --profile-path — sử dụng một hồ sơ Firefox cụ thể
• --firefox-arg — đối số Firefox bổ sung (có thể lặp lại)
• --start-url — mở URL này khi khởi động (START_URL)
• --accept-insecure-certs — bỏ qua lỗi TLS (ACCEPT_INSECURE_CERTS=true)
• --connect-existing — đính kèm vào Firefox đang chạy thay vì khởi chạy một phiên mới (CONNECT_EXISTING=true)
• --marionette-port — cổng Marionette cho chế độ kết nối hiện có, mặc định 2828 (MARIONETTE_PORT)
• --pref name=value — đặt tùy chọn Firefox khi khởi động qua moz:firefoxOptions (có thể lặp lại)
• --tool-preset — chọn mô-đun công cụ để bật: slim, basic (mặc định), developer, mozilla, hoặc all. Xem Mô-đun công cụ và cài đặt trước. (TOOL_PRESET)
• --tools — danh sách rõ ràng các mô-đun công cụ để bật, ghi đè hoàn toàn --tool-preset (ví dụ: --tools pages network script). Xem Mô-đun công cụ và cài đặt trước.
• --enable-script — không dùng nữa, sử dụng --tool-preset developer hoặc --tools ... script debugging. Chọn cài đặt trước công cụ developer. (ENABLE_SCRIPT=true)
• --enable-privileged-context — không dùng nữa, sử dụng --tool-preset mozilla hoặc --tools ... privileged prefs. Chọn cài đặt trước công cụ mozilla. Yêu cầu MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device — bật chế độ Firefox cho Android; giá trị là số sê-ri thiết bị ADB (ví dụ: emulator-5554). Chạy adb devices để liệt kê các thiết bị đã kết nối. Bỏ qua giá trị hoặc sử dụng auto để tự động chọn thiết bị đã kết nối duy nhất.
• --android-wipe-app-data — xác nhận rằng chế độ Android xóa toàn bộ dữ liệu của ứng dụng mục tiêu. Bắt buộc cùng với --android-device. (ANDROID_WIPE_APP_DATA=true)
• --android-package — tên gói ứng dụng Android, mặc định org.mozilla.firefox. Các gói khác: org.mozilla.firefox_beta cho Firefox Beta, org.mozilla.fenix cho Firefox Nightly, org.mozilla.fenix.debug cho Firefox Nightly Debug, org.mozilla.geckoview_example cho geckoview (ANDROID_PACKAGE)
• --unrestricted-save-paths — cho phép tham số saveTo ghi ở bất kỳ đâu trên đĩa thay vì các thư mục gốc mặc định. Xem Lưu đầu ra cồng kềnh vào đĩa và ghi chú bảo mật trong SECURITY.md. (UNRESTRICTED_SAVE_PATHS=true)
• --log-file — ghi nhật ký máy chủ MCP vào tệp thay vì stderr. Hữu ích cho các phiên gỡ lỗi với máy khách MCP ẩn đầu ra máy chủ. Đặt DEBUG=* để cũng bao gồm nhật ký gỡ lỗi chi tiết. Ví dụ: --log-file /tmp/firefox-mcp.log

Mô-đun công cụ và cài đặt trước

Các công cụ được nhóm thành các mô-đun. Bạn chọn mô-đun nào để hiển thị bằng cài đặt trước có tên (--tool-preset) hoặc bằng danh sách rõ ràng (--tools). Khi cả hai được cung cấp, --tools thắng và cài đặt trước bị bỏ qua.

Các mô-đun: pages, snapshot, input, network, console, screenshot, downloads, utilities, management, webextension, profiler, screencast, script, debugging, prefs, privileged.

Các cài đặt trước (mỗi cái là tập siêu của cái trước):

• slim — pages, snapshot, input, screenshot
• basic (mặc định) — slim cộng downloads, script, utilities, management, webextension, screencast
• developer — basic cộng debugging, network, console, profiler
• mozilla — developer cộng prefs, privileged
• all — mọi mô-đun

Lưu ý rằng basic, mặc định, bao gồm script và do đó có công cụ evaluate_script. Xem SECURITY.md để biết điều đó có nghĩa gì đối với bề mặt tấn công, và sử dụng --tool-preset slim hoặc danh sách --tools rõ ràng để loại bỏ nó.

# 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

Các mô-đun prefs và privileged yêu cầu MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 và chỉ khả dụng trong bản dựng nội bộ của Mozilla. Gói công khai bỏ qua chúng ngay cả khi được yêu cầu và ghi nhật ký cảnh báo nêu tên các mô-đun đã bị bỏ.

Tùy chọn hữu ích (--pref)

• remote.prefs.recommended=false. Khi Firefox chạy trong tự động hóa, nó áp dụng RecommendedPreferences để sửa đổi hành vi trình duyệt cho việc kiểm thử. Đặt remote.prefs.recommended thành false để bỏ qua những tùy chọn đó và có cấu hình gần với phiên bản Firefox thông thường hơn.
• remote.log.level=Trace. Bật nhật ký giao thức WebDriver chi tiết trong Firefox. Máy chủ MCP sẽ tự động truyền mức nhật ký khớp đến geckodriver để cả hai bên ghi nhật ký ở cùng mức chi tiết.
• app.update.disabledForTesting=false. Cho phép Firefox tự động tải xuống và áp dụng các bản cập nhật. Lưu ý rằng các bản cập nhật có thể làm gián đoạn phiên của bạn. Cũng yêu cầu đặt remote.prefs.recommended=false.

Firefox cho Android

Sử dụng --android-device để tự động hóa Firefox chạy trên thiết bị Android. Yêu cầu adb trong PATH của bạn và geckodriver, được quản lý tự động.

Cảnh báo: Chế độ Android xóa toàn bộ dữ liệu của ứng dụng mục tiêu trước mỗi phiên. Các tab, lịch sử, dấu trang, mật khẩu, cookie và cài đặt đều bị mất. geckodriver chạy adb shell pm clear <package> khi tạo phiên và không có cách nào để bỏ qua, sau đó chạy phiên trên hồ sơ tạm thời riêng của nó và bị xóa sau đó. Vì lý do này, --android-device yêu cầu --android-wipe-app-data, và bạn nên cài đặt một bản dựng chuyên dụng cho tự động hóa thay vì tự động hóa trình duyệt bạn đang sử dụng. Bug 2064088 theo dõi việc thêm một tùy chọn vào geckodriver để giữ dữ liệu ứng dụng hiện có.

# 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

Chuyển tiếp cổng giữa máy chủ và thiết bị được xử lý tự động bởi geckodriver.

Kết nối đến Firefox hiện có

Sử dụng --connect-existing để tự động hóa phiên duyệt web thực của bạn, với cookie, đăng nhập và các tab đang mở còn nguyên vẹn:

# 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

Cả hai cờ đều bắt buộc vì MCP sử dụng cả WebDriver Classic (--marionette) và WebDriver BiDi (--remote-debugging-port). Nếu Firefox chỉ được khởi động với --marionette, máy chủ MCP không kết nối được và yêu cầu bạn khởi động lại Firefox với cả hai cờ.

Cảnh báo: Không để Marionette được bật trong quá trình duyệt web thông thường. Nó đặt navigator.webdriver = true và thay đổi các tín hiệu vân tay trình duyệt khác, có thể kích hoạt phát hiện bot trên các trang được bảo vệ bởi Cloudflare, Akamai, v.v. Chỉ bật Marionette khi bạn cần tự động hóa MCP, sau đó khởi động lại Firefox bình thường sau đó.

Tổng quan về công cụ

Xem docs/tools.md để biết danh sách đầy đủ các công cụ theo mô-đun, với mô tả và tham số (được tạo từ mã nguồn).

• Trang: list/new/navigate/select/close/get_page_text (get_page_text hỗ trợ saveTo tùy chọn)
• Snapshot/UID: take/resolve/clear (take hỗ trợ saveTo tùy chọn)
• Đầu vào: click/hover/fill/drag/upload/form fill
• Mạng: list/get (ưu tiên ID, bộ lọc, ghi hình luôn bật; cả hai hỗ trợ saveTo tùy chọn)
• Tải xuống: list_downloads/clear_downloads (ghi hình luôn bật), set_download_behavior (allow/deny/default)
• Bảng điều khiển: list/clear (list hỗ trợ saveTo tùy chọn)
• Ảnh chụp màn hình: page/by uid (với saveTo tùy chọn cho môi trường CLI)
• Tập lệnh: evaluate_script (sandbox tùy chọn cho một vùng cách ly; saveTo tùy chọn cho kết quả cồng kềnh)
• Ngữ cảnh đặc quyền: list/select ngữ cảnh đặc quyền ("chrome"), evaluate_privileged_script (yêu cầu MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• WebExtension: install_extension, uninstall_extension, list_extensions (list yêu cầu MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Quản lý Firefox: get_firefox_info, get_firefox_output, restart_firefox
• Tùy chọn Firefox: get_firefox_prefs, set_firefox_prefs (yêu cầu MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Hồ sơ hiệu năng: profiler_is_active, profiler_start (cài đặt trước hoặc cấu hình rõ ràng), profiler_stop (lưu hồ sơ vào thư mục tải xuống)
• Ghi hình màn hình: screencast_start (ghi viewport trang vào tệp video trong thư mục tải xuống), screencast_stop (yêu cầu Firefox 154+)
• Tiện ích: accept/dismiss dialog, history back/forward, set viewport

Lưu đầu ra cồng kềnh vào đĩa

Đầu ra công cụ lớn có thể tiêu tốn ngữ cảnh đáng kể trong các máy khách CLI như Claude Code. Các công cụ screenshot_page, screenshot_by_uid, take_snapshot, list_console_messages, list_network_requests, get_network_request, get_page_text, evaluate_script, và evaluate_privileged_script chấp nhận tham số saveTo tùy chọn để ghi kết quả vào tệp thay vì trả về nội tuyến. saveTo có một trong ba dạng:

• một đường dẫn tệp (tương đối với thư mục làm việc hiện tại, hoặc tuyệt đối trong ~/.firefox-devtools-mcp; các thư mục cha được tạo)
• một thư mục hiện có (một tệp có dấu thời gian được tạo bên trong nó)
• true (một tệp có dấu thời gian được tạo dưới ~/.firefox-devtools-mcp/output/)

Phản hồi trả về đường dẫn và kích thước byte. Tệp đã lưu luôn chứa dữ liệu đầy đủ, không bị cắt: các biện pháp bảo vệ kích thước nội tuyến (giới hạn tin nhắn bảng điều khiển, cắt tiêu đề mạng, giới hạn dòng snapshot) không bao giờ áp dụng cho nó.

Các công cụ tạo văn bản (mọi thứ trừ ảnh chụp màn hình) cũng chấp nhận preview, một số ký tự của đầu ra đã lưu để phản hồi lại nội tuyến như một đoạn trích ngắn. Ảnh chụp màn hình không có bản xem trước.

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 })

Theo mặc định, các đường dẫn lưu bị giới hạn: đường dẫn tương đối được phân giải theo thư mục làm việc hiện tại, và đường dẫn tuyệt đối chỉ được phép nằm trong ~/.firefox-devtools-mcp. Các đường dẫn thoát khỏi những vị trí này sẽ bị từ chối. Khởi động máy chủ với --unrestricted-save-paths để ghi vào các vị trí tùy ý, bao gồm cả đường dẫn tuyệt đối nằm ngoài thư mục đó.

Các tệp đã lưu sau đó có thể được xem, ví dụ, bằng công cụ Read của Claude Code mà không ảnh hưởng đến kích thước ngữ cảnh.

Phát triển cục bộ

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

Xem CONTRIBUTING.md để biết thêm chi tiết về phát triển cục bộ, kiểm thử và CI.

Xử lý sự cố

• Không tìm thấy Firefox: truyền --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) hoặc đường dẫn chính xác trên hệ điều hành của bạn.
• Lần chạy đầu tiên chậm: Selenium thiết lập phiên BiDi; các lần chạy sau sẽ nhanh hơn.
• UID cũ: một UID vẫn hợp lệ cho đến khi phần tử của nó bị xóa hoặc trang điều hướng; hãy chụp ảnh nhanh mới (take_snapshot) khi một công cụ UID báo rằng nó đã biến mất.
• Windows 10: Lỗi trong quá trình phát hiện máy chủ MCP 'firefox-devtools': Lỗi MCP -32000: Kết nối đã đóng

  • Giải pháp 1 Bọc bằng cmd /c (chi tiết):

    "mcpServers": {
      "firefox-devtools": {
        "command": "cmd",
        "args": ["/c", "npx", "-y", "@mozilla/firefox-devtools-mcp@latest"]
      }
    }
    

  • Giải pháp 2 Sử dụng đường dẫn tuyệt đối đến npx (điều chỉnh phần mở rộng — .cmd, .bat, .exe, hoặc .ps1 — để khớp với thiết lập của bạn):

    "mcpServers": {
      "firefox-devtools": {
        "command": "C:\\nvm4w\\nodejs\\npx.ps1",
        "args": ["-y", "@mozilla/firefox-devtools-mcp@latest"]
      }
    }
    

Phiên bản

• API trước 1.0: các phiên bản bắt đầu từ 0.x. Sử dụng @latest với npx cho bản phát hành mới nhất.

Đóng góp

Xem CONTRIBUTING.md để biết cách nộp vấn đề, chạy kiểm thử và làm việc trên dự án cục bộ.

Tác giả

Được duy trì bởi Mozilla.

Giấy phép

Được cấp phép theo một trong hai MIT hoặc Apache 2.0 tùy theo lựa chọn của bạn.