firefox-devtools-mcp

Firefox DevTools MCP

Server Model Context Protocol untuk mengotomatisasi 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 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 disediakan.

Keamanan

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

• Gunakan profil Firefox khusus. Jangan pernah menjalankan server dengan profil reguler Anda — agen memiliki akses ke apa pun yang dapat dijangkau browser, termasuk cookie dan sesi tersimpan.
• Berhati-hatilah tentang 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. 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 sisi 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 terhubung-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 nilai 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 — izinkan parameter saveTo menulis di mana saja di disk alih-alih root default. Lihat Menyimpan output 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 output 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.

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

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

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

Perhatikan bahwa basic, default, menyertakan script dan oleh karena itu alat evaluate_script. Lihat SECURITY.md untuk artinya 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. Paket publik melewatkannya 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 browser untuk pengujian. Atur remote.prefs.recommended ke false untuk melewatinya dan memiliki konfigurasi yang lebih mirip 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 mengotomatisasi 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 itu, --android-device memerlukan --android-wipe-app-data, dan Anda harus menginstal build yang didedikasikan untuk otomatisasi daripada mengotomatisasi browser 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.

Terhubung ke Firefox yang ada

Gunakan --connect-existing untuk mengotomatisasi 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 untuk me-restart Firefox dengan kedua flag.

Peringatan: Jangan biarkan Marionette aktif selama penjelajahan normal. Ini mengatur 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 restart Firefox secara normal setelahnya.

Ringkasan alat

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

• 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, penangkapan selalu aktif; keduanya mendukung saveTo opsional)
• Unduhan: list_downloads/clear_downloads (penangkapan 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 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
• Preferensi Firefox: get_firefox_prefs, set_firefox_prefs (memerlukan MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1)
• Profiler: profiler_is_active, profiler_start (prasetel 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 mengonsumsi 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 menyimpan 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 di dalam ~/.firefox-devtools-mcp. Jalur yang keluar dari lokasi tersebut akan ditolak. Mulai server dengan --unrestricted-save-paths untuk menulis ke lokasi arbitrer, termasuk jalur absolut di luar direktori tersebut.

File yang disimpan kemudian dapat dilihat, misalnya, dengan alat Read dari 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 OS Anda.
• Eksekusi pertama lambat: Selenium menyiapkan sesi BiDi; eksekusi berikutnya lebih cepat.
• UID basi: UID tetap valid hingga elemennya dihapus atau halaman berpindah; ambil snapshot baru (take_snapshot) saat alat UID melaporkan bahwa UID 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.