firefox-devtools-mcp

Firefox DevTools MCP

เซิร์ฟเวอร์ Model Context Protocol ที่ช่วยให้เอเจนต์ AI ใช้ Firefox ได้ โดยมีกรณีการใช้งานหลักสองกรณี:

• การท่องเว็บแบบเอเจนต์: เอเจนต์ใช้เบราว์เซอร์สำหรับงานทั่วไป เช่น การอ่านหน้าเว็บ การกรอกฟอร์ม และการดำเนินการตามขั้นตอนหลายขั้นตอนบนเว็บไซต์
• การพัฒนาเว็บโดยใช้เอเจนต์ช่วย: เอเจนต์โหลดหน้าที่คุณกำลังทำงานอยู่และตรวจสอบด้วยเครื่องมือสำหรับนักพัฒนา เช่น คอนโซล คำขอเครือข่าย ดีบักเกอร์ และโปรไฟเลอร์

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

ที่เก็บ: 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 รันในโฟลเดอร์ย่อย firefox_devtools_mcp_profile ของเส้นทางนั้น โดยทำเครื่องหมายด้วยไฟล์ .firefox-devtools-mcp; การชี้ --profile-path ไปที่โปรไฟล์ที่ทำเครื่องหมายไว้จะนำกลับมาใช้โดยตรง
• --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 จะชนะและ พรีเซ็ตจะถูกละเว้น

พรีเซ็ต (แต่ละอันเป็นซูเปอร์เซ็ตของอันก่อนหน้า):

• slim — ขั้นต่ำสำหรับการท่องเว็บและโต้ตอบกับหน้า
• basic (ค่าเริ่มต้น) — เพิ่มเครื่องมือสำหรับการท่องเว็บทั่วไป
• developer — เพิ่มเครื่องมือสำหรับนักพัฒนาเว็บ
• mozilla — เพิ่มเครื่องมือสำหรับนักพัฒนา Firefox
• all — ทุกโมดูล

ดู docs/tools.md สำหรับรายการโมดูลและโมดูล ในแต่ละพรีเซ็ต

โปรดทราบว่า 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 เท่านั้น โมดูล launch ต้องใช้บิลด์ภายในของ Mozilla เช่นกัน: มันรีสตาร์ท Firefox ด้วยไบนารี โปรไฟล์ สภาพแวดล้อม และชุดการตั้งค่าที่ผู้เรียกเลือก ซึ่งเป็นการเปลี่ยนแปลงคอนฟิกที่ผู้ปฏิบัติงานควรเป็นเจ้าของ ใช้ --pref, --firefox-path และตัวเลือกบรรทัดคำสั่งอื่นๆ แทน โมดูล bidi ต้องใช้ บิลด์ภายในของ Mozilla เช่นกัน: มันส่งคำสั่ง WebDriver BiDi ใดๆ ดังนั้นจึงให้การเข้าถึงสิ่งที่ โมดูลอื่นๆ เปิดเผย แพ็กเกจสาธารณะข้ามโมดูลเหล่านี้แม้จะถูกร้องขอและบันทึก คำเตือนที่ระบุชื่อโมดูลที่ถูกตัดออก

การตั้งค่าที่มีประโยชน์ (--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 สำหรับรายการเครื่องมือทั้งหมดตามโมดูล พร้อม คำอธิบายและพารามิเตอร์ (สร้างจากซอร์ส)

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

เอาต์พุตเครื่องมือขนาดใหญ่สามารถใช้บริบทจำนวนมากในไคลเอนต์ CLI เช่น Claude Code เครื่องมือ หลายตัวยอมรับพารามิเตอร์ saveTo ที่เป็นทางเลือกซึ่งเขียนผลลัพธ์ลงไฟล์แทนที่จะ ส่งคืนแบบอินไลน์ ดู docs/tools.md สำหรับรายการ saveTo รับหนึ่งในสามรูปแบบ:

• เส้นทางไฟล์ (สัมพันธ์กับไดเรกทอรีทำงานปัจจุบัน หรือสัมบูรณ์ภายใน ~/.firefox-devtools-mcp/output; ไดเรกทอรีหลักจะถูกสร้าง) เส้นทางที่เข้าถึงโปรไฟล์ Firefox หรือไฟล์ที่เซิร์ฟเวอร์นี้อ่านกลับจะถูกปฏิเสธ
• ไดเรกทอรีที่มีอยู่ (ไฟล์ที่มีการประทับเวลาจะถูกสร้างภายในนั้น)
• true (ไฟล์ที่มีการประทับเวลาจะถูกสร้างภายใต้ ~/.firefox-devtools-mcp/output/)

การตอบสนองส่งคืนเส้นทางและขนาดไบต์ ไฟล์ที่บันทึกมีข้อมูลเต็มที่ไม่ถูกตัดทอนเสมอ: การป้องกันขนาดอินไลน์ (ขีดจำกัดข้อความคอนโซล การตัดทอนส่วนหัวเครือข่าย ขีดจำกัดบรรทัดสแนปช็อต) ไม่มีผลกับมัน

เครื่องมือที่สร้างข้อความยังยอมรับ preview ซึ่งเป็นจำนวนอักขระของเอาต์พุตที่บันทึกเพื่อ ส่งกลับแบบอินไลน์เป็นข้อความสั้นๆ รายการใน docs/tools.md แสดงว่าเครื่องมือใดรองรับมัน

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 ตามที่คุณเลือก