firefox-devtools-mcp

Firefox DevTools MCP

Máy chủ Giao thức Ngữ cảnh Mô hình (Model Context Protocol) cho phép các tác nhân AI sử dụng Firefox. Nó có hai trường hợp sử dụng chính:

• Duyệt web theo tác nhân: tác nhân sử dụng trình duyệt cho các tác vụ thông thường, chẳng hạn như đọc trang, điền biểu mẫu và thực hiện các luồng nhiều bước trên trang web.
• Phát triển web có hỗ trợ của tác nhân: tác nhân tải trang bạn đang làm việc và kiểm tra nó bằng các công cụ dành cho nhà phát triển, chẳng hạn như bảng điều khiển, yêu cầu mạng, trình gỡ lỗi và trình phân tích hiệu năng.

Nó điều khiển Firefox thông qua WebDriver BiDi (qua Selenium WebDriver) và 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 những rủi ro cố hữu. Một vài 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 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, trình phân tích 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 đủ 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 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 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 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 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 chạy trong thư mục con firefox_devtools_mcp_profile của đường dẫn đó, được đánh dấu bằng tệp .firefox-devtools-mcp; trỏ --profile-path vào một hồ sơ đã đánh dấu sẽ tái sử dụng trực tiếp hồ sơ đó
• --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 một Firefox đang chạy thay vì khởi chạy một 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 các 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ài đặt trước. (TOOL_PRESET)
• --tools — danh sách rõ ràng 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à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 lớn 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 cài đặt trước (mỗi cái là siêu tập hợp của cái trước):

• slim — tối thiểu để duyệt và tương tác với các trang
• basic (mặc định) — thêm các công cụ để duyệt web thông thường
• developer — thêm các công cụ cho nhà phát triển web
• mozilla — thêm các công cụ cho nhà phát triển Firefox
• all — mọi mô-đun

Xem docs/tools.md để biết danh sách các mô-đun và các mô-đun trong mỗi cài đặt trước.

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. Mô-đun launch cũng yêu cầu bản dựng nội bộ của Mozilla: nó khởi động lại Firefox dưới tệp nhị phân, hồ sơ, môi trường và tập hợp tùy chọn do người gọi chọn, đây là thay đổi cấu hình mà người vận hành nên sở hữu. Sử dụng --pref, --firefox-path và các tùy chọn dòng lệnh khác để thay thế. Mô-đun bidi cũng yêu cầu bản dựng nội bộ của Mozilla: nó gửi bất kỳ lệnh WebDriver BiDi nào, vì vậy nó cung cấp quyền truy cập vào những gì các mô-đun khác hiển thị. Gói công khai bỏ qua các mô-đun này 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 để thử nghiệm. Đặ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ý 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 trên 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 của riêng nó và bị xóa sau đó. Vì điều 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 dành riêng cho tự động hóa thay vì tự động hóa trình duyệt bạn 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 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, đă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 dấ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ừ nguồn).

Lưu đầu ra lớn 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. Một số công cụ 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. Xem docs/tools.md để biết danh sách. saveTo có 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/output; các thư mục cha được tạo). Các đường dẫn đến hồ sơ Firefox hoặc các tệp mà máy chủ này đọc lại bị từ chối
• 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 ngắn: 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 ngắn tiêu đề mạng, giới hạn dòng ảnh chụp nhanh) không bao giờ áp dụng cho nó.

Các công cụ tạo văn bản 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 đoạn trích ngắn. Danh sách trong docs/tools.md hiển thị công cụ nào hỗ trợ nó.

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ị hạn chế: đường dẫn tương đối 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 các vị trí này 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ụ với 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ộ, thử nghiệm và CI.

Khắc phục sự cố

• Không tìm thấy Firefox: hãy 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 báo cáo vấn đề, chạy kiểm thử và làm việc trên dự án tại địa phương.

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.