firefox-devtools-mcp

Firefox DevTools MCP

Máy chủ Model Context Protocol để tự động hóa Firefox thông qua WebDriver BiDi (qua Selenium WebDriver). Hoạt động với Claude Code, Claude Desktop, Cursor, Cline và các ứng dụng 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 rủi ro cố hữu. Một số thực hành chính:

• 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ể tiếp cận, bao gồm cookie và phiên đã lưu.
• Thận trọng với 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 tưởng.
• Tránh bật thêm cờ trừ khi cần thiết. --enable-script và --enable-privileged-context mở rộng đáng kể những gì tác nhân có thể làm.

Xem SECURITY.md để biết phân tích đầy đủ 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 xuất bản 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 — 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

Dùng 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 (chụp luôn bật), get_network_request
• 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 người dùng (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 — gắn vào Firefox đang chạy thay vì khởi chạy 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)
• --enable-script — bật công cụ evaluate_script (thực thi JavaScript tùy ý trong ngữ cảnh trang) và các công cụ gỡ lỗi (liệt kê tập lệnh, kiểm tra nguồn, đặt điểm ghi nhật ký). Công cụ gỡ lỗi yêu cầu Firefox 153+. (ENABLE_SCRIPT=true)
• --enable-privileged-context — bật công cụ ngữ cảnh đặc quyền: liệt kê/chọn ngữ cảnh đặc quyền, đánh giá tập lệnh đặc quyền, lấy/đặt tùy chọn Firefox và liệt kê tiện ích mở rộng. 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-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 cho việc gỡ lỗi phiên với các ứng dụng 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

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 mục đích kiểm thử. Đặt remote.prefs.recommended thành false để bỏ qua những điều đó 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ý phù hợ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ập nhật. Lưu ý rằng cập nhật có thể làm gián đoạn phiên của bạn. Yêu cầu cũng đặ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 trên 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 geckodriver xử lý tự động.

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òn nguyên vẹn:

# Start Firefox with Marionette enabled
firefox --marionette

# Run the MCP server
npx @mozilla/firefox-devtools-mcp --connect-existing --marionette-port 2828

Hoặc đặt marionette.enabled thành true trong about:config (hoặc user.js) để bật Marionette mỗi lần khởi chạy.

Các tính năng phụ thuộc BiDi (sự kiện console, sự kiện mạng) không khả dụng trong chế độ kết nối hiện có; tất cả các tính năng khác hoạt động bình thường.

Cảnh báo: Không để Marionette được bật trong khi duyệt web bình 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 web đượ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: liệt kê/mới/điều hướng/chọn/đóng
• Ảnh chụp nhanh/UID: chụp/giải quyết/xóa
• Đầu vào: nhấp/di chuột/điền/kéo/tải lên/điền biểu mẫu
• Mạng: liệt kê/lấy (ưu tiên ID, bộ lọc, chụp luôn bật)
• Console: liệt kê/xóa
• Ảnh chụp màn hình: trang/theo uid (với saveTo tùy chọn cho môi trường CLI)
• Tập lệnh: evaluate_script
• Ngữ cảnh đặc quyền: liệt kê/chọn 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 (danh sách 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 cấu hình rõ ràng), profiler_stop (lưu hồ sơ vào thư mục tải xuống)
• Tiện ích: chấp nhận/hủy hộp thoại, lịch sử quay lại/tiến, đặt khung nhìn

Tối ưu hóa ảnh chụp màn hình cho Claude Code

Khi sử dụng ảnh chụp màn hình trong Claude Code CLI, dữ liệu ảnh base64 có thể tiêu tốn ngữ cảnh đáng kể. Sử dụng tham số saveTo để lưu ảnh chụp màn hình vào đĩa thay thế:

screenshot_page({ saveTo: "/tmp/page.png" })
screenshot_by_uid({ uid: "abc123", saveTo: "/tmp/element.png" })

Sau đó, tệp có thể được xem 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.

Khắc phục 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ũ sau khi điều hướng: chụp ảnh chụp nhanh mới (take_snapshot) trước khi sử dụng các công cụ UID.
• Windows 10: Lỗi trong quá trình khám phá máy chủ MCP 'firefox-devtools': MCP error -32000: Connection closed

  • Giải pháp 1 Bao 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 — để 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 tiền 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 gửi 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 chọn của bạn.