firefox-devtools-mcp

Firefox DevTools MCP

Máy chủ Model Context Protocol để 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 dùng Docker với Dockerfile được cung cấp.

Bảo mật

Máy chủ MCP trình duyệt tiềm ẩn nhiều rủi ro. 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 mọi thứ trình duyệt có thể truy cập, bao gồm cookie và phiên đã lưu.
• Thận trọng với các trang web bạn truy cập. 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ác cấu hình cao hơn như --tool-preset developer (script, gỡ lỗi) và --tool-preset mozilla (ngữ cảnh đặc quyền) mở rộng đáng kể 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.

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 (npx)

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

Tùy chọn A — Claude Code CLI

claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest

Truyền tùy chọn dưới dạng đối số hoặc biến môi trường. Ví dụ:

# 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

Tùy chọn B — Chỉnh sửa JSON cài đặt Claude Code

Thêm vào tệp cấu hình Claude Code của bạn:

• 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"
      }
    }
  }
}

Tùy chọn C — Script trợ giúp (bản build 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 rồi click_by_uid / fill_by_uid
• list_network_requests (ghi liên tục), get_network_request
• list_downloads (ghi liên tục), 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 nhị phân Firefox
• --headless — chạy không có giao diện (FIREFOX_HEADLESS=true)
• --viewport 1280x720 — kích thước cửa sổ ban đầu
• --profile-path — sử dụng 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 phiên bả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ụ cần bật: slim, basic (mặc định), developer, mozilla, hoặc all. Xem Mô-đun công cụ và cấu hình. (TOOL_PRESET)
• --tools — danh sách tường minh các mô-đun công cụ cần bật, ghi đè hoàn toàn --tool-preset (ví dụ --tools pages network script). Xem Mô-đun công cụ và cấu hình.
• --enable-script — không dùng nữa, sử dụng --tool-preset developer hoặc --tools ... script debugging. Chọn cấu hình 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ấu hình 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 dùng auto để tự động chọn thiết bị duy nhất đã kết nối.
• --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)
• --log-file — ghi nhật ký máy chủ MCP vào tệp thay vì stderr. Hữu ích khi gỡ lỗi phiên với các máy khách MCP ẩn đầu ra của 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ấu hình

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

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

Các cấu hình (mỗi cấu hình là tập siêu của cấu hình trước):

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

# Use the developer preset (adds script and debugging 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 build nội bộ của Mozilla; gói công khai âm thầm bỏ qua chúng ngay cả khi được yêu cầu.

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

• remote.prefs.recommended=false. Khi Firefox chạy trong chế độ tự động hóa, nó áp dụng RecommendedPreferences để sửa đổi hành vi trình duyệt cho mục đích kiểm thử. Đặt remote.prefs.recommended thành false để bỏ qua các 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ý tương ứng cho 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 bản cập nhật. Lưu ý rằng bản cập nhật có thể làm gián đoạn phiên của bạn. Cũng cần đặ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.

# 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

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 với 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, thông tin đăng nhập và các tab đang mở được giữ nguyê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 công cụ

• 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)
• Nhập liệu: click/hover/fill/drag/upload/form fill
• Mạng: list/get (ưu tiên ID, bộ lọc, ghi liên tục; cả hai hỗ trợ saveTo tùy chọn)
• Tải xuống: list_downloads/clear_downloads (ghi liên tục), 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/theo uid (với saveTo tùy chọn cho môi trường CLI)
• Script: evaluate_script (sandbox tùy chọn cho ngữ cảnh biệt lập; saveTo tùy chọn cho kết quả lớn)
• 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, set_firefox_prefs, get_firefox_prefs
• Profiler: profiler_is_active, profiler_start (cấu hình sẵn hoặc tường minh), profiler_stop (lưu hồ sơ vào thư mục tải xuống)
• Screencast: 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 kết quả lớn ra đĩa

Đầu ra công cụ lớn có thể tiêu tốn nhiều ngữ cảnh 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 nhận một trong ba dạng:

• đườ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 tự động)
• 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 trong ~/.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 ngắn: các giới hạn an toàn nội tuyến (giới hạn thông báo bảng điều khiển, cắt ngắn tiêu đề mạng, giới hạn dòng snapshot) không bao giờ áp dụng cho tệp đó.

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 nội tuyến dưới dạng trích đoạn 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, đườ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 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 bên 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 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; chụp snapshot mới (take_snapshot) khi một công cụ UID báo cá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': MCP error -32000: Connection closed

  • 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 — cho phù hợ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 báo cáo 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 MIT hoặc Apache 2.0 tùy theo lựa chọn của bạn.