firefox-devtools-mcp

Firefox DevTools MCP

Server Model Context Protocol yang memungkinkan agen AI menggunakan Firefox. Server ini memiliki dua kasus penggunaan utama:

• Penjelajahan agen: agen menggunakan peramban untuk tugas-tugas reguler, seperti membaca halaman, mengisi formulir, dan melalui alur multi-langkah di situs web.
• Pengembangan web berbantuan agen: agen memuat halaman yang sedang Anda kerjakan dan memeriksanya dengan alat pengembang, seperti konsol, permintaan jaringan, debugger, dan profiler.

Server ini mengontrol Firefox melalui WebDriver BiDi (via Selenium WebDriver) dan 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 menjalankannya secara lokal, atau gunakan Docker dengan Dockerfile yang disediakan.

Keamanan

Server MCP peramban membawa risiko yang melekat. 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 tersimpan.
• Berhati-hatilah tentang situs mana 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. Prasetel basic default sudah menyertakan evaluate_script; --tool-preset slim menghapusnya. Prasetel yang lebih tinggi seperti --tool-preset developer (debugging, jaringan, konsol, profiler) dan --tool-preset mozilla (konteks istimewa) memperluas kemampuan agen lebih jauh.

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)

Instalasi dan penggunaan dengan Claude Code atau Codex (npx)

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

Opsi 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

Opsi B — Edit file konfigurasi

Claude Code

Tambahkan ke mcp_settings.json milik Claude Code:

{
  "mcpServers": {
    "firefox-devtools": {
      "command": "npx",
      "args": ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
      "env": {
        "START_URL": "about:blank"
      }
    }
  }
}

Codex

Tambahkan ke ~/.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"

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 (penangkapan selalu aktif), get_network_request
• list_downloads (penangkapan 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 berjalan di subfolder firefox_devtools_mcp_profile dari jalur tersebut, ditandai dengan file .firefox-devtools-mcp; menunjuk --profile-path ke profil yang ditandai akan menggunakannya kembali secara langsung
• --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 sambungkan-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 mana yang akan diaktifkan: slim, basic (default), developer, mozilla, atau all. Lihat Modul alat dan prasetel. (TOOL_PRESET)
• --tools — daftar eksplisit modul alat yang akan diaktifkan, menggantikan --tool-preset sepenuhnya (mis. --tools pages network script). Lihat Modul alat dan prasetel.
• --enable-script — usang, gunakan --tool-preset developer atau --tools ... script debugging. Memilih prasetel alat developer. (ENABLE_SCRIPT=true)
• --enable-privileged-context — usang, gunakan --tool-preset mozilla atau --tools ... privileged prefs. Memilih prasetel 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 (mis. emulator-5554). Jalankan adb devices untuk mencantumkan perangkat yang terhubung. Hapus nilainya atau gunakan auto untuk memilih perangkat terhubung tunggal secara otomatis.
• --android-wipe-app-data — konfirmasi bahwa mode Android menghapus semua data aplikasi target. Diperlukan bersama dengan --android-device. (ANDROID_WIPE_APP_DATA=true)
• --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)
• --unrestricted-save-paths — biarkan parameter saveTo menulis di mana saja di disk alih-alih akar default. Lihat Menyimpan keluaran besar ke disk dan catatan keamanan di SECURITY.md. (UNRESTRICTED_SAVE_PATHS=true)
• --log-file — tulis log server MCP ke file alih-alih stderr. Berguna untuk sesi debugging dengan klien MCP yang menyembunyikan keluaran server. Atur DEBUG=* untuk juga menyertakan log debug verbose. Contoh: --log-file /tmp/firefox-mcp.log

Modul alat dan prasetel

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

Prasetel (masing-masing adalah superset dari yang sebelumnya):

• slim — minimum untuk menjelajah dan berinteraksi dengan halaman
• basic (default) — menambahkan alat untuk penjelajahan reguler
• developer — menambahkan alat untuk pengembang web
• mozilla — menambahkan alat untuk pengembang Firefox
• all — setiap modul

Lihat docs/tools.md untuk daftar modul dan modul di setiap prasetel.

Perhatikan bahwa basic, default, menyertakan script dan karena itu alat evaluate_script. Lihat SECURITY.md untuk apa artinya itu bagi permukaan serangan, dan gunakan --tool-preset slim atau daftar --tools eksplisit untuk menghapusnya.

# 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

Modul prefs dan privileged memerlukan MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 dan hanya tersedia di build internal Mozilla. Modul launch juga memerlukan build internal Mozilla: modul ini memulai ulang Firefox di bawah biner, profil, lingkungan, dan kumpulan preferensi yang dipilih pemanggil, yang merupakan perubahan konfigurasi yang harus dimiliki operator. Gunakan --pref, --firefox-path dan opsi baris perintah lainnya sebagai gantinya. Modul bidi juga memerlukan build internal Mozilla: modul ini mengirim perintah WebDriver BiDi apa pun, sehingga memberikan akses ke apa yang diekspos modul lain. Paket publik melewati modul ini bahkan jika diminta dan mencatat peringatan yang menyebutkan modul yang dihapusnya.

Preferensi yang berguna (--pref)

• remote.prefs.recommended=false. Ketika 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 reguler.
• remote.log.level=Trace. Aktifkan log protokol WebDriver verbose di Firefox. Server MCP akan secara otomatis meneruskan tingkat log yang cocok ke geckodriver sehingga kedua sisi mencatat pada verbositas yang sama.
• app.update.disabledForTesting=false. Izinkan Firefox mengunduh dan menerapkan pembaruan secara otomatis. Perhatikan bahwa pembaruan dapat mengganggu sesi Anda. Juga memerlukan 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.

Peringatan: Mode Android menghapus semua data aplikasi target sebelum setiap sesi. Tab, riwayat, bookmark, kata sandi, cookie, dan pengaturan semuanya hilang. geckodriver menjalankan adb shell pm clear <package> saat membuat sesi dan tidak menawarkan cara untuk melewatinya, lalu menjalankan sesi pada profil sementara sendiri yang dihapus setelahnya. Karena ini, --android-device memerlukan --android-wipe-app-data, dan Anda harus menginstal build yang didedikasikan untuk otomatisasi daripada mengotomatiskan peramban yang Anda gunakan. Bug 2064088 melacak penambahan opsi ke geckodriver untuk mempertahankan data aplikasi yang ada.

# 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

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

Sambungkan ke Firefox yang ada

Gunakan --connect-existing untuk mengotomatiskan sesi penjelajahan nyata Anda, dengan cookie, login, dan tab terbuka yang 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 memulai ulang Firefox dengan kedua flag.

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.

Ringkasan alat

Lihat docs/tools.md untuk daftar lengkap alat per modul, dengan deskripsi dan parameter (dihasilkan dari sumber).

Menyimpan keluaran besar ke disk

Keluaran alat yang besar dapat mengonsumsi konteks yang signifikan di klien CLI seperti Claude Code. Beberapa alat menerima parameter opsional saveTo yang menulis hasil ke file alih-alih mengembalikannya secara inline. Lihat docs/tools.md untuk daftarnya. saveTo mengambil salah satu dari tiga bentuk:

• jalur file (relatif terhadap direktori kerja saat ini, atau absolut dalam ~/.firefox-devtools-mcp/output; direktori induk dibuat). Jalur yang mencapai profil Firefox, atau file yang dibaca kembali oleh server ini, ditolak
• 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, tidak terpotong: pengaman ukuran inline (batas pesan konsol, pemotongan header jaringan, batas baris snapshot) tidak pernah berlaku untuknya.

Alat yang menghasilkan teks juga menerima preview, sejumlah karakter dari keluaran yang disimpan untuk digemakan kembali secara inline sebagai kutipan singkat. Daftar di docs/tools.md menunjukkan alat mana yang mendukungnya.

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 milik 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 pada sistem operasi Anda.
• Run pertama lambat: Selenium menyiapkan sesi BiDi; run berikutnya lebih cepat.
• UID basi: sebuah UID tetap valid hingga elemennya dihapus atau halaman berpindah; ambil snapshot baru (take_snapshot) ketika alat UID melaporkan bahwa UID tersebut 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"]
      }
    }
    

Versioning

• 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 tes, dan mengerjakan proyek secara lokal.

Penulis

Dikelola oleh Mozilla.

Lisensi

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