firefox-devtools-mcp

Firefox DevTools MCP

Server Model Context Protocol untuk mengotomatiskan Firefox melalui WebDriver BiDi (melalui Selenium WebDriver). Bekerja dengan Claude Code, Claude Desktop, Cursor, Cline, dan klien MCP lainnya.

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

Catatan: Server MCP ini memerlukan instalasi peramban Firefox lokal dan tidak dapat berjalan di layanan hosting cloud seperti glama.ai. Gunakan npx @mozilla/firefox-devtools-mcp@latest untuk menjalankan secara lokal, atau gunakan Docker dengan Dockerfile yang disediakan.

Keamanan

Server MCP peramban membawa risiko bawaan. Beberapa praktik utama:

• Gunakan profil Firefox khusus. Jangan pernah menjalankan server terhadap profil reguler Anda — agen memiliki akses ke apa pun yang dapat dijangkau peramban, termasuk cookie dan sesi yang tersimpan.
• Berhati-hatilah dengan situs yang Anda kunjungi. Halaman dapat mengembalikan konten yang dirancang untuk memanipulasi agen (injeksi prompt). Tetap gunakan situs yang Anda kendalikan atau percayai.
• Hindari mengaktifkan flag tambahan kecuali diperlukan. --enable-script dan --enable-privileged-context secara signifikan memperluas apa yang dapat dilakukan agen.

Lihat SECURITY.md untuk rincian lengkap risiko dan cara melaporkan kerentanan.

Persyaratan

• Node.js ≥ 20.19.0
• Firefox 100+ terinstal (terdeteksi otomatis, atau berikan --firefox-path)

Instal dan gunakan dengan Claude Code (npx)

Direkomendasikan: gunakan npx agar Anda selalu menjalankan versi terbaru yang dipublikasikan dari npm.

Opsi A — Claude Code CLI

claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest

Berikan opsi baik sebagai argumen atau variabel lingkungan. Contoh:

# 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

Opsi B — Edit JSON pengaturan Claude Code

Tambahkan ke file konfigurasi Claude Code Anda:

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

Opsi C — Skrip pembantu (build pengembangan lokal)

npm run setup
# Choose Claude Code; the script saves JSON to the right path

Coba dengan MCP Inspector

npx @modelcontextprotocol/inspector npx @mozilla/firefox-devtools-mcp@latest --start-url https://example.com --headless

Kemudian panggil alat seperti:

• list_pages, select_page, navigate_page
• take_snapshot lalu click_by_uid / fill_by_uid
• list_network_requests (tangkapan selalu aktif), get_network_request
• screenshot_page, list_console_messages

Opsi CLI

Anda dapat memberikan flag atau variabel lingkungan (nama di sebelah kanan):

• --firefox-path — path absolut ke biner Firefox
• --headless — jalankan tanpa UI (FIREFOX_HEADLESS=true)
• --viewport 1280x720 — ukuran jendela awal
• --profile-path — gunakan profil Firefox tertentu
• --firefox-arg — argumen Firefox tambahan (dapat diulang)
• --start-url — buka URL ini saat mulai (START_URL)
• --accept-insecure-certs — abaikan kesalahan TLS (ACCEPT_INSECURE_CERTS=true)
• --connect-existing — lampirkan ke Firefox yang sudah berjalan alih-alih meluncurkan yang baru (CONNECT_EXISTING=true)
• --marionette-port — port Marionette untuk mode connect-existing, default 2828 (MARIONETTE_PORT)
• --pref name=value — atur preferensi Firefox saat startup melalui moz:firefoxOptions (dapat diulang)
• --enable-script — aktifkan alat evaluate_script (mengeksekusi JavaScript arbitrer dalam konteks halaman) dan alat debugging (daftar skrip, periksa sumber, atur logpoint). Alat debugging memerlukan Firefox 153+. (ENABLE_SCRIPT=true)
• --enable-privileged-context — aktifkan alat konteks istimewa: daftar/pilih konteks istimewa, evaluasi skrip istimewa, dapatkan/atur preferensi Firefox, dan daftar ekstensi. Memerlukan MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device — aktifkan mode Firefox untuk Android; nilainya adalah serial perangkat ADB (mis. emulator-5554). Jalankan adb devices untuk mendaftar perangkat yang terhubung. Abaikan nilainya atau gunakan auto untuk memilih perangkat tunggal yang terhubung secara otomatis.
• --android-package — nama paket aplikasi Android, default org.mozilla.firefox. Paket lain: org.mozilla.firefox_beta untuk Firefox Beta, org.mozilla.fenix untuk Firefox Nightly, org.mozilla.fenix.debug untuk Firefox Nightly Debug, org.mozilla.geckoview_example untuk geckoview (ANDROID_PACKAGE)
• --log-file — tulis log server MCP ke file alih-alih stderr. Berguna untuk sesi debugging dengan klien MCP yang menyembunyikan output server. Atur DEBUG=* untuk juga menyertakan log debug verbose. Contoh: --log-file /tmp/firefox-mcp.log

Preferensi berguna (--pref)

• remote.prefs.recommended=false. Saat Firefox berjalan dalam otomatisasi, ia menerapkan RecommendedPreferences yang memodifikasi perilaku peramban untuk pengujian. Atur remote.prefs.recommended ke false untuk melewatinya dan memiliki konfigurasi yang lebih dekat dengan instance Firefox biasa.
• remote.log.level=Trace. Aktifkan log protokol WebDriver verbose di Firefox. Server MCP akan secara otomatis meneruskan level log yang cocok ke geckodriver sehingga kedua sisi mencatat pada verbositas yang sama.
• app.update.disabledForTesting=false. Izinkan Firefox untuk mengunduh dan menerapkan pembaruan secara otomatis. Perhatikan bahwa pembaruan dapat mengganggu sesi Anda. Memerlukan juga pengaturan remote.prefs.recommended=false.

Firefox untuk Android

Gunakan --android-device untuk mengotomatiskan Firefox yang berjalan di perangkat Android. Memerlukan adb di PATH Anda dan geckodriver, yang dikelola secara otomatis.

# 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

Penerusan port antara host dan perangkat ditangani secara otomatis oleh geckodriver.

Hubungkan ke Firefox yang sudah ada

Gunakan --connect-existing untuk mengotomatiskan sesi penjelajahan nyata Anda — dengan cookie, login, dan tab terbuka tetap utuh:

# Start Firefox with Marionette enabled
firefox --marionette

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

Atau atur marionette.enabled ke true di about:config (atau user.js) untuk mengaktifkan Marionette pada setiap peluncuran.

Fitur yang bergantung pada BiDi (peristiwa konsol, peristiwa jaringan) tidak tersedia dalam mode connect-existing; semua fitur lainnya berfungsi normal.

Peringatan: Jangan biarkan Marionette aktif selama penjelajahan normal. Ini mengatur navigator.webdriver = true dan mengubah sinyal sidik jari peramban lainnya, yang dapat memicu deteksi bot di situs yang dilindungi oleh Cloudflare, Akamai, dll. Hanya aktifkan Marionette saat Anda memerlukan otomatisasi MCP, lalu mulai ulang Firefox secara normal setelahnya.

Ikhtisar alat

• Halaman: daftar/baru/navigasi/pilih/tutup
• Snapshot/UID: ambil/resolusi/hapus
• Input: klik/arahkan/isi/seret/unggah/isi formulir
• Jaringan: daftar/dapatkan (ID-pertama, filter, tangkapan selalu aktif)
• Konsol: daftar/hapus
• Tangkapan layar: halaman/berdasarkan uid (dengan saveTo opsional untuk lingkungan CLI)
• Skrip: evaluate_script
• Konteks Istimewa: daftar/pilih konteks istimewa ("chrome"), evaluate_privileged_script (memerlukan MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• WebExtension: install_extension, uninstall_extension, list_extensions (daftar memerlukan MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Manajemen Firefox: get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs
• Profiler: profiler_is_active, profiler_start (preset atau konfigurasi eksplisit), profiler_stop (menyimpan profil ke direktori unduhan)
• Utilitas: terima/tolak dialog, riwayat mundur/maju, atur viewport

Optimasi tangkapan layar untuk Claude Code

Saat menggunakan tangkapan layar di Claude Code CLI, data gambar base64 dapat menghabiskan konteks yang signifikan. Gunakan parameter saveTo untuk menyimpan tangkapan layar ke disk sebagai gantinya:

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

File kemudian dapat dilihat dengan alat Read Claude Code tanpa memengaruhi ukuran konteks.

Pengembangan lokal

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

Lihat CONTRIBUTING.md untuk detail lebih lanjut tentang pengembangan lokal, pengujian, dan CI.

Pemecahan masalah

• Firefox tidak ditemukan: berikan --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) atau path yang benar di OS Anda.
• Jalan pertama lambat: Selenium menyiapkan sesi BiDi; jalan berikutnya lebih cepat.
• UID basi setelah navigasi: ambil snapshot baru (take_snapshot) sebelum menggunakan alat UID.
• Windows 10: Kesalahan selama penemuan untuk server MCP 'firefox-devtools': MCP error -32000: Connection closed

  • Solusi 1 Bungkus dengan cmd /c (detail):

    "mcpServers": {
      "firefox-devtools": {
        "command": "cmd",
        "args": ["/c", "npx", "-y", "@mozilla/firefox-devtools-mcp@latest"]
      }
    }
    

  • Solusi 2 Gunakan path absolut ke npx (sesuaikan ekstensi — .cmd, .bat, .exe, atau .ps1 — agar cocok dengan pengaturan Anda):

    "mcpServers": {
      "firefox-devtools": {
        "command": "C:\\nvm4w\\nodejs\\npx.ps1",
        "args": ["-y", "@mozilla/firefox-devtools-mcp@latest"]
      }
    }
    

Pembuatan versi

• API Pra‑1.0: versi dimulai dari 0.x. Gunakan @latest dengan npx untuk rilis terbaru.

Berkontribusi

Lihat CONTRIBUTING.md untuk cara mengajukan isu, menjalankan pengujian, dan mengerjakan proyek secara lokal.

Penulis

Dikelola oleh Mozilla.

Lisensi

Dilisensikan di bawah salah satu dari MIT atau Apache 2.0 sesuai pilihan Anda.