firefox-devtools-mcp

Firefox DevTools MCP

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

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

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

Keamanan

Server MCP browser membawa risiko yang melekat. Beberapa praktik penting:

• Gunakan profil Firefox khusus. Jangan pernah menjalankan server terhadap profil reguler Anda — agen memiliki akses ke apa pun yang dapat dijangkau browser, termasuk cookie dan sesi tersimpan.
• Berhati-hatilah terhadap situs yang Anda kunjungi. Halaman dapat mengembalikan konten yang dirancang untuk memanipulasi agen (injeksi prompt). Tetap gunakan situs yang Anda kendalikan atau percayai.
• Aktifkan hanya modul alat yang Anda butuhkan. Preset yang lebih tinggi seperti --tool-preset developer (skrip, debugging) dan --tool-preset mozilla (konteks istimewa) secara signifikan memperluas apa yang dapat dilakukan agen.

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

Persyaratan

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

Instalasi dan penggunaan dengan Claude Code (npx)

Disarankan: gunakan npx sehingga Anda selalu menjalankan versi terbaru yang dipublikasikan dari npm.

Opsi A — CLI Claude Code

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

Berikan opsi 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 bantuan (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 (pengambilan selalu aktif), get_network_request
• list_downloads (pengambilan selalu aktif), set_download_behavior
• screenshot_page, list_console_messages

Opsi CLI

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

• --firefox-path — jalur 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 koneksi-ke-yang-ada, default 2828 (MARIONETTE_PORT)
• --pref name=value — atur preferensi Firefox saat startup melalui moz:firefoxOptions (dapat diulang)
• --tool-preset — pilih modul alat yang akan diaktifkan: slim, basic (default), developer, mozilla, atau all. Lihat Modul alat dan preset. (TOOL_PRESET)
• --tools — daftar eksplisit modul alat yang akan diaktifkan, sepenuhnya menggantikan --tool-preset (misalnya --tools pages network script). Lihat Modul alat dan preset.
• --enable-script — tidak digunakan lagi, gunakan --tool-preset developer atau --tools ... script debugging. Memilih preset alat developer. (ENABLE_SCRIPT=true)
• --enable-privileged-context — tidak digunakan lagi, gunakan --tool-preset mozilla atau --tools ... privileged prefs. Memilih preset alat mozilla. Memerlukan MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device — aktifkan mode Firefox untuk Android; nilainya adalah serial perangkat ADB (misalnya emulator-5554). Jalankan adb devices untuk mencantumkan perangkat yang terhubung. Hilangkan nilainya atau gunakan auto untuk memilih satu-satunya perangkat yang terhubung secara otomatis.
• --android-package — nama paket aplikasi Android, default org.mozilla.firefox. Paket lainnya: 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. Setel DEBUG=* untuk juga menyertakan log debug verbose. Contoh: --log-file /tmp/firefox-mcp.log

Modul alat dan preset

Alat dikelompokkan ke dalam modul. Anda memilih modul mana yang akan diekspos baik dengan preset bernama (--tool-preset) atau dengan daftar eksplisit (--tools). Jika keduanya diberikan, --tools yang menang dan preset diabaikan.

Modul: pages, snapshot, input, network, console, screenshot, utilities, management, webextension, profiler, screencast, script, debugging, prefs, privileged.

Preset (masing-masing merupakan superset dari yang sebelumnya):

• slim — pages, snapshot, input, network, console
• basic (default) — slim ditambah screenshot, utilities, management, webextension, profiler, screencast
• developer — basic ditambah script, debugging
• mozilla — developer ditambah prefs, privileged
• all — setiap modul

# Use the developer preset (adds script and debugging tools)
npx @mozilla/firefox-devtools-mcp --tool-preset developer

# Enable only the modules you need
npx @mozilla/firefox-devtools-mcp --tools pages network console

Modul prefs dan privileged memerlukan MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 dan hanya tersedia di build internal Mozilla; paket publik secara diam-diam melewatkannya meskipun diminta.

Preferensi yang berguna (--pref)

• remote.prefs.recommended=false. Saat Firefox berjalan dalam otomatisasi, ia menerapkan RecommendedPreferences yang memodifikasi perilaku browser untuk pengujian. Setel remote.prefs.recommended ke false untuk melewati itu dan memiliki konfigurasi yang lebih mirip dengan instance Firefox reguler.
• remote.log.level=Trace. Aktifkan log protokol WebDriver yang 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. Juga perlu menyetel remote.prefs.recommended=false.

Firefox untuk Android

Gunakan --android-device untuk mengotomatisasi 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 mengotomatisasi sesi penjelajahan nyata Anda, dengan cookie, login, dan tab terbuka yang tetap utuh:

# 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

Kedua flag diperlukan karena MCP menggunakan WebDriver Classic (--marionette) dan WebDriver BiDi (--remote-debugging-port). Jika Firefox hanya dimulai dengan --marionette, server MCP gagal terhubung dan meminta Anda untuk memulai ulang Firefox dengan kedua flag.

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

Ringkasan alat

• Halaman: list/new/navigate/select/close/get_page_text (get_page_text mendukung saveTo opsional)
• Snapshot/UID: take/resolve/clear (take mendukung saveTo opsional)
• Input: click/hover/fill/drag/upload/form fill
• Jaringan: list/get (ID-pertama, filter, pengambilan selalu aktif; keduanya mendukung saveTo opsional)
• Unduhan: list_downloads/clear_downloads (pengambilan selalu aktif), set_download_behavior (allow/deny/default)
• Konsol: list/clear (list mendukung saveTo opsional)
• Tangkapan layar: page/by uid (dengan saveTo opsional untuk lingkungan CLI)
• Skrip: evaluate_script (sandbox opsional untuk realm terisolasi; saveTo opsional untuk hasil yang besar)
• Konteks Istimewa: list/select konteks istimewa ("chrome"), evaluate_privileged_script (memerlukan MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• WebExtension: install_extension, uninstall_extension, list_extensions (list 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)
• Screencast: screencast_start (merekam viewport halaman ke file video di direktori unduhan), screencast_stop (memerlukan Firefox 154+)
• Utilitas: accept/dismiss dialog, history back/forward, set viewport

Menyimpan output besar ke disk

Output alat yang besar dapat menghabiskan konteks yang signifikan di klien CLI seperti Claude Code. Alat screenshot_page, screenshot_by_uid, take_snapshot, list_console_messages, list_network_requests, get_network_request, get_page_text, evaluate_script, dan evaluate_privileged_script menerima parameter saveTo opsional yang menulis hasil ke file alih-alih mengembalikannya secara inline. saveTo mengambil salah satu dari tiga bentuk:

• jalur file (relatif terhadap direktori kerja saat ini, atau absolut dalam ~/.firefox-devtools-mcp; direktori induk dibuat)
• direktori yang ada (file berstempel waktu dibuat di dalamnya)
• true (file berstempel waktu dibuat di bawah ~/.firefox-devtools-mcp/output/)

Respons mengembalikan jalur dan ukuran byte. File yang disimpan selalu berisi data lengkap, tanpa pemotongan: pengaman ukuran inline (batas pesan konsol, pemotongan header jaringan, batas baris snapshot) tidak pernah berlaku untuknya.

Alat yang menghasilkan teks (semuanya kecuali tangkapan layar) juga menerima preview, sejumlah karakter dari output yang disimpan untuk digaungkan kembali secara inline sebagai kutipan singkat. Tangkapan layar tidak memiliki pratinjau.

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 })

Secara default, jalur penyimpanan dibatasi: jalur relatif diselesaikan terhadap direktori kerja saat ini, dan jalur absolut hanya diizinkan dalam ~/.firefox-devtools-mcp. Jalur yang keluar dari lokasi ini ditolak. Mulai server dengan --unrestricted-save-paths untuk menulis ke lokasi arbitrer, termasuk jalur absolut di luar direktori itu.

File yang disimpan kemudian dapat dilihat misalnya 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 jalur yang benar di OS Anda.
• Jalankan pertama lambat: Selenium menyiapkan sesi BiDi; jalankan berikutnya lebih cepat.
• UID basi: UID tetap valid hingga elemennya dihapus atau halaman berpindah; ambil snapshot baru (take_snapshot) saat alat UID melaporkan bahwa snapshot sudah tidak ada.
• Windows 10: Error during discovery for MCP server '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 jalur absolut ke npx (sesuaikan ekstensi — .cmd, .bat, .exe, atau .ps1 — agar sesuai dengan pengaturan Anda):

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

Versi

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

Kontribusi

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

Penulis

Dikelola oleh Mozilla.

Lisensi

Dilisensikan di bawah MIT atau Apache 2.0 sesuai pilihan Anda.