firefox-devtools-mcp

Firefox DevTools MCP

เซิร์ฟเวอร์ Model Context Protocol สำหรับการควบคุม Firefox ผ่าน WebDriver BiDi (ผ่าน Selenium WebDriver) ทำงานร่วมกับ Claude Code, Claude Desktop, Cursor, Cline และไคลเอนต์ MCP อื่นๆ

Repository: https://github.com/mozilla/firefox-devtools-mcp

หมายเหตุ: เซิร์ฟเวอร์ MCP นี้ต้องมีการติดตั้งเบราว์เซอร์ Firefox ในเครื่อง และไม่สามารถรันบนบริการคลาวด์โฮสติ้งเช่น glama.ai ได้ ใช้ npx @mozilla/firefox-devtools-mcp@latest เพื่อรันในเครื่อง หรือใช้ Docker กับ Dockerfile ที่ให้มา

ความปลอดภัย

เซิร์ฟเวอร์ MCP สำหรับเบราว์เซอร์มีความเสี่ยงโดยธรรมชาติ แนวปฏิบัติสำคัญบางประการ:

• ใช้โปรไฟล์ Firefox เฉพาะ ห้ามรันเซิร์ฟเวอร์กับโปรไฟล์ปกติของคุณ — เอเจนต์สามารถเข้าถึงทุกสิ่งที่เบราว์เซอร์เข้าถึงได้ รวมถึงคุกกี้และเซสชันที่บันทึกไว้
• ระมัดระวังเกี่ยวกับเว็บไซต์ที่คุณเยี่ยมชม เพจสามารถส่งคืนเนื้อหาที่ออกแบบมาเพื่อจัดการเอเจนต์ (prompt injection) ยึดติดกับเว็บไซต์ที่คุณควบคุมหรือเชื่อถือ
• เปิดใช้เฉพาะโมดูลเครื่องมือที่คุณต้องการ ค่าตั้งต้น 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

เพิ่มใน mcp_settings.json ของ Claude Code:

{
  "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 — รันโดยไม่มี UI (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 — ตั้งค่าค่ากำหนด Firefox เมื่อเริ่มต้นผ่าน moz:firefoxOptions (ทำซ้ำได้)
• --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 สำหรับ 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 รันในโหมดอัตโนมัติ มันจะใช้ RecommendedPreferences ที่ปรับเปลี่ยนพฤติกรรมเบราว์เซอร์สำหรับการทดสอบ ตั้งค่า remote.prefs.recommended เป็น false เพื่อข้ามสิ่งเหล่านั้นและมีการกำหนดค่าที่ใกล้เคียงกับอินสแตนซ์ Firefox ปกติ
• remote.log.level=Trace เปิดใช้บันทึกโปรโตคอล WebDriver แบบละเอียดใน Firefox เซิร์ฟเวอร์ MCP จะส่งระดับบันทึกที่ตรงกันให้ geckodriver โดยอัตโนมัติเพื่อให้ทั้งสองฝั่งบันทึกที่ระดับความละเอียดเดียวกัน
• app.update.disabledForTesting=false อนุญาตให้ Firefox ดาวน์โหลดและใช้การอัปเดตโดยอัตโนมัติ โปรดทราบว่าการอัปเดตอาจขัดจังหวะเซสชันของคุณ ต้องตั้งค่า remote.prefs.recommended=false ด้วย

Firefox สำหรับ Android

ใช้ --android-device เพื่อควบคุม Firefox ที่รันบนอุปกรณ์ Android ต้องใช้ adb ใน PATH ของคุณและ geckodriver ซึ่งจัดการโดยอัตโนมัติ

คำเตือน: โหมด Android ล้างข้อมูลทั้งหมดของแอปเป้าหมายก่อนทุกเซสชัน แท็บ, ประวัติ, ที่คั่นหน้า, รหัสผ่าน, คุกกี้และการตั้งค่าทั้งหมดจะสูญหาย 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 เพื่อควบคุมเซสชันการท่องเว็บจริงของคุณ โดยมีคุกกี้ การเข้าสู่ระบบ และแท็บที่เปิดอยู่ครบถ้วน:

# 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 ฯลฯ เปิดใช้ Marionette เฉพาะเมื่อคุณต้องการการควบคุม MCP จากนั้นรีสตาร์ท 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‑first, ตัวกรอง, การจับภาพแบบเปิดตลอด; ทั้งสองรองรับ 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 dialog, history back/forward, set viewport

การบันทึกเอาต์พุตขนาดใหญ่ลงดิสก์

เอาต์พุตเครื่องมือขนาดใหญ่สามารถใช้บริบทจำนวนมากในไคลเอนต์ 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 เพื่อ เขียนไปยังตำแหน่งใดก็ได้ รวมถึงเส้นทางสัมบูรณ์ภายนอกไดเรกทอรีนั้น

ไฟล์ที่บันทึกแล้วสามารถดูได้ เช่น ด้วยเครื่องมือ Read ของ Claude Code โดยไม่กระทบต่อขนาดของบริบท

การพัฒนาท้องถิ่น

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

ดู CONTRIBUTING.md สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับการพัฒนาท้องถิ่น การทดสอบ และ CI

การแก้ไขปัญหา

• ไม่พบ Firefox: ส่ง --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) หรือเส้นทางที่ถูกต้องบนระบบปฏิบัติการของคุณ
• การรันครั้งแรกช้า: Selenium จะตั้งค่าเซสชัน BiDi; การรันครั้งต่อๆ ไปจะเร็วขึ้น
• UID ที่เก่า: UID จะยังคงใช้ได้จนกว่าองค์ประกอบนั้นจะถูกลบออกหรือมีการนำทางหน้าเว็บ; ถ่ายภาพรวมใหม่ (take_snapshot) เมื่อเครื่องมือ UID รายงานว่าไม่มีองค์ประกอบนั้นแล้ว
• 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"]
      }
    }
    

การกำหนดเวอร์ชัน

• API ก่อน 1.0: เวอร์ชันเริ่มต้นที่ 0.x ใช้ @latest กับ npx สำหรับรุ่นล่าสุด

การมีส่วนร่วม

ดู CONTRIBUTING.md สำหรับวิธีการแจ้งปัญหา รันการทดสอบ และทำงานในโปรเจกต์ในเครื่อง

ผู้เขียน

ดูแลโดย Mozilla

สัญญาอนุญาต

ได้รับอนุญาตภายใต้ MIT หรือ Apache 2.0 ตามที่คุณเลือก