firefox-devtools-mcp

Firefox DevTools MCP

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

ดู SECURITY.md สำหรับรายละเอียดความเสี่ยงทั้งหมดและวิธีการรายงานช่องโหว่

ข้อกำหนด

• Node.js ≥ 20.19.0
• ติดตั้ง Firefox 100+ (ตรวจหาอัตโนมัติ หรือส่ง --firefox-path)

ติดตั้งและใช้กับ Claude Code (npx)

แนะนำ: ใช้ npx เพื่อให้คุณรันเวอร์ชันล่าสุดที่เผยแพร่จาก npm เสมอ

ตัวเลือก A — Claude Code CLI

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

ตัวเลือก B — แก้ไข JSON การตั้งค่า Claude Code

เพิ่มลงในไฟล์การกำหนดค่า Claude Code ของคุณ:

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

ตัวเลือก 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
• 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 (ทำซ้ำได้)
• --enable-script — เปิดใช้งานเครื่องมือ evaluate_script (เรียกใช้ JavaScript ตามอำเภอใจในบริบทของหน้า) และเครื่องมือดีบัก (แสดงรายการสคริปต์ ตรวจสอบซอร์ส ตั้งค่าจุดบันทึก) เครื่องมือดีบักต้องการ Firefox 153+ (ENABLE_SCRIPT=true)
• --enable-privileged-context — เปิดใช้งานเครื่องมือบริบทสิทธิพิเศษ: แสดงรายการ/เลือกบริบทสิทธิพิเศษ ประเมินสคริปต์สิทธิพิเศษ รับ/ตั้งค่ากำหนด Firefox และแสดงรายการส่วนขยาย ต้องการ MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device — เปิดใช้งานโหมด Firefox สำหรับ Android; ค่าคือซีเรียลอุปกรณ์ ADB (เช่น emulator-5554) รัน adb devices เพื่อแสดงรายการอุปกรณ์ที่เชื่อมต่อ ละเว้นค่าหรือใช้ auto เพื่อเลือกอุปกรณ์ที่เชื่อมต่อเพียงเครื่องเดียวโดยอัตโนมัติ
• --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)
• --log-file — เขียนบันทึกเซิร์ฟเวอร์ MCP ลงไฟล์แทน stderr มีประโยชน์สำหรับการดีบักเซสชันกับไคลเอนต์ MCP ที่ซ่อนเอาต์พุตเซิร์ฟเวอร์ ตั้งค่า DEBUG=* เพื่อรวมบันทึกดีบักแบบละเอียดด้วย ตัวอย่าง: --log-file /tmp/firefox-mcp.log

การตั้งค่าที่มีประโยชน์ (--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 ซึ่งจัดการโดยอัตโนมัติ

# 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

การส่งต่อพอร์ตระหว่างโฮสต์และอุปกรณ์จัดการโดยอัตโนมัติโดย geckodriver

เชื่อมต่อกับ Firefox ที่มีอยู่

ใช้ --connect-existing เพื่อทำงานอัตโนมัติกับเซสชันการท่องเว็บจริงของคุณ — พร้อมคุกกี้ การเข้าสู่ระบบ และแท็บที่เปิดอยู่ครบถ้วน:

# Start Firefox with Marionette enabled
firefox --marionette

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

หรือตั้งค่า marionette.enabled เป็น true ใน about:config (หรือ user.js) เพื่อเปิดใช้งาน Marionette ทุกครั้งที่เปิด

คุณสมบัติที่ขึ้นกับ BiDi (เหตุการณ์คอนโซล เหตุการณ์เครือข่าย) ไม่พร้อมใช้งานในโหมดเชื่อมต่อที่มีอยู่; คุณสมบัติอื่นๆ ทั้งหมดทำงานตามปกติ

คำเตือน: อย่าเปิด Marionette ทิ้งไว้ระหว่างการท่องเว็บปกติ มันตั้งค่า navigator.webdriver = true และเปลี่ยนสัญญาณลายนิ้วมือเบราว์เซอร์อื่นๆ ซึ่งสามารถกระตุ้นการตรวจจับบอทบนไซต์ที่ป้องกันโดย Cloudflare, Akamai ฯลฯ เปิดใช้งาน Marionette เฉพาะเมื่อคุณต้องการการทำงานอัตโนมัติของ MCP จากนั้นรีสตาร์ท Firefox ตามปกติหลังจากนั้น

ภาพรวมเครื่องมือ

• หน้า: แสดงรายการ/ใหม่/นำทาง/เลือก/ปิด
• สแนปช็อต/UID: ถ่าย/แก้ไข/ล้าง
• อินพุต: คลิก/โฮเวอร์/กรอก/ลาก/อัปโหลด/กรอกฟอร์ม
• เครือข่าย: แสดงรายการ/รับ (ID ก่อน, ตัวกรอง, การจับภาพตลอดเวลา)
• คอนโซล: แสดงรายการ/ล้าง
• ภาพหน้าจอ: หน้า/ตาม uid (พร้อม saveTo เสริมสำหรับสภาพแวดล้อม CLI)
• สคริปต์: evaluate_script
• บริบทสิทธิพิเศษ: แสดงรายการ/เลือกบริบทสิทธิพิเศษ ("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, set_firefox_prefs, get_firefox_prefs
• โปรไฟเลอร์: profiler_is_active, profiler_start (ค่าที่ตั้งไว้ล่วงหน้าหรือการกำหนดค่าที่ชัดเจน), profiler_stop (บันทึกโปรไฟล์ไปยังไดเรกทอรีดาวน์โหลด)
• ยูทิลิตี้: ยอมรับ/ปฏิเสธไดอะล็อก, ประวัติย้อนกลับ/ไปข้างหน้า, ตั้งค่าวิวพอร์ต

การเพิ่มประสิทธิภาพภาพหน้าจอสำหรับ Claude Code

เมื่อใช้ภาพหน้าจอใน Claude Code CLI ข้อมูลภาพ base64 สามารถใช้บริบทจำนวนมาก ใช้พารามิเตอร์ saveTo เพื่อบันทึกภาพหน้าจอลงดิสก์แทน:

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

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