firefox-devtools-mcp

Firefox DevTools MCP

Model Context Protocol sunucusu; Firefox'u WebDriver BiDi (Selenium WebDriver aracılığıyla) kullanarak otomatikleştirir. Claude Code, Claude Desktop, Cursor, Cline ve diğer MCP istemcileriyle çalışır.

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

Not: Bu MCP sunucusu yerel bir Firefox tarayıcı kurulumu gerektirir ve glama.ai gibi bulut barındırma hizmetlerinde çalıştırılamaz. Yerel olarak çalıştırmak için npx @mozilla/firefox-devtools-mcp@latest kullanın veya sağlanan Dockerfile ile Docker kullanın.

Güvenlik

Tarayıcı MCP sunucuları doğal riskler taşır. Birkaç önemli uygulama:

• Özel bir Firefox profili kullanın. Sunucuyu asla normal profilinize karşı çalıştırmayın — aracı, tarayıcının erişebildiği her şeye, çerezler ve kayıtlı oturumlar dahil, erişebilir.
• Hangi siteleri ziyaret ettiğinize dikkat edin. Sayfalar, aracıyı manipüle etmek için tasarlanmış içerik döndürebilir (istem dışı enjeksiyon). Kontrol ettiğiniz veya güvendiğiniz sitelere bağlı kalın.
• Yalnızca ihtiyacınız olan araç modüllerini etkinleştirin. Varsayılan basic ön ayarı zaten evaluate_script içerir; --tool-preset slim onu kaldırır. --tool-preset developer (hata ayıklama, ağ, konsol, profil oluşturucu) ve --tool-preset mozilla (ayrıcalıklı bağlam) gibi daha yüksek ön ayarlar, aracının yapabileceklerini daha da genişletir.

Risklerin tam dökümü ve güvenlik açıklarının nasıl bildirileceği için SECURITY.md dosyasına bakın.

Gereksinimler

• Node.js ≥ 20.19.0
• Firefox 100+ kurulu (otomatik algılanır veya --firefox-path ile geçilir)

Claude Code veya Codex ile kurulum ve kullanım (npx)

Önerilen: npm'den en son yayınlanan sürümü çalıştırmak için npx kullanın.

Seçenek 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

Seçenek B — Yapılandırma dosyasını düzenleyin

Claude Code

Claude Code'un mcp_settings.json dosyasına ekleyin:

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

Codex

~/.codex/config.toml dosyasına ekleyin:

[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"

Seçenek C — Yardımcı betik (yerel geliştirme derlemesi)

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

MCP Inspector ile deneyin

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

Ardından şu araçları çağırın:

• list_pages, select_page, navigate_page
• take_snapshot ardından click_by_uid / fill_by_uid
• list_network_requests (her zaman açık yakalama), get_network_request
• list_downloads (her zaman açık yakalama), set_download_behavior
• screenshot_page, list_console_messages

CLI seçenekleri

Bayraklar veya ortam değişkenleri geçebilirsiniz (sağdaki adlar):

• --firefox-path — Firefox ikili dosyasının mutlak yolu
• --headless — arayüz olmadan çalıştır (FIREFOX_HEADLESS=true)
• --viewport 1280x720 — başlangıç pencere boyutu
• --profile-path — belirli bir Firefox profili kullan
• --firefox-arg — ek Firefox bağımsız değişkenleri (tekrarlanabilir)
• --start-url — başlangıçta bu URL'yi aç (START_URL)
• --accept-insecure-certs — TLS hatalarını yoksay (ACCEPT_INSECURE_CERTS=true)
• --connect-existing — yenisini başlatmak yerine zaten çalışan bir Firefox'a bağlan (CONNECT_EXISTING=true)
• --marionette-port — mevcut bağlantı modu için Marionette bağlantı noktası, varsayılan 2828 (MARIONETTE_PORT)
• --pref name=value — başlangıçta moz:firefoxOptions aracılığıyla Firefox tercihi ayarla (tekrarlanabilir)
• --tool-preset — hangi araç modüllerinin etkinleştirileceğini seç: slim, basic (varsayılan), developer, mozilla veya all. Araç modülleri ve ön ayarlar bölümüne bakın. (TOOL_PRESET)
• --tools — --tool-preset değerini tamamen geçersiz kılan açık araç modülleri listesi (örn. --tools pages network script). Araç modülleri ve ön ayarlar bölümüne bakın.
• --enable-script — kullanımdan kaldırıldı, --tool-preset developer veya --tools ... script debugging kullanın. developer araç ön ayarını seçer. (ENABLE_SCRIPT=true)
• --enable-privileged-context — kullanımdan kaldırıldı, --tool-preset mozilla veya --tools ... privileged prefs kullanın. mozilla araç ön ayarını seçer. MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 gerektirir (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device — Firefox for Android modunu etkinleştir; değer ADB cihaz seri numarasıdır (örn. emulator-5554). Bağlı cihazları listelemek için adb devices çalıştırın. Değeri atlayın veya bağlı tek cihazı otomatik olarak seçmek için auto kullanın.
• --android-wipe-app-data — Android modunun hedef uygulamanın tüm verilerini sildiğini onaylayın. --android-device ile birlikte gereklidir. (ANDROID_WIPE_APP_DATA=true)
• --android-package — Android uygulama paket adı, varsayılan org.mozilla.firefox. Diğer paketler: Firefox Beta için org.mozilla.firefox_beta, Firefox Nightly için org.mozilla.fenix, Firefox Nightly Debug için org.mozilla.fenix.debug, geckoview için org.mozilla.geckoview_example (ANDROID_PACKAGE)
• --unrestricted-save-paths — saveTo parametresinin varsayılan kökler yerine disk üzerinde herhangi bir yere yazmasına izin ver. Büyük çıktıyı diske kaydetme ve SECURITY.md içindeki güvenlik notuna bakın. (UNRESTRICTED_SAVE_PATHS=true)
• --log-file — MCP sunucu günlüklerini stderr yerine bir dosyaya yazın. Sunucu çıktısını gizleyen MCP istemcileriyle hata ayıklama oturumları için kullanışlıdır. Ayrıntılı hata ayıklama günlüklerini de dahil etmek için DEBUG=* ayarlayın. Örnek: --log-file /tmp/firefox-mcp.log

Araç modülleri ve ön ayarlar

Araçlar modüller halinde gruplandırılmıştır. Hangi modülleri açığa çıkaracağınızı adlandırılmış bir ön ayarla (--tool-preset) veya açık bir listeyle (--tools) seçersiniz. Her ikisi de verildiğinde, --tools kazanır ve ön ayar yok sayılır.

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

Ön ayarlar (her biri bir öncekinin üst kümesidir):

• slim — pages, snapshot, input, screenshot
• basic (varsayılan) — slim artı downloads, script, utilities, management, webextension, screencast
• developer — basic artı debugging, network, console, profiler
• mozilla — developer artı prefs, privileged
• all — her modül

basic varsayılanının script içerdiğini ve dolayısıyla evaluate_script aracını içerdiğini unutmayın. Bunun saldırı yüzeyi için ne anlama geldiğini görmek üzere SECURITY.md dosyasına bakın ve onu kaldırmak için --tool-preset slim veya açık bir --tools listesi kullanın.

# 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

prefs ve privileged modülleri MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 gerektirir ve yalnızca Mozilla dahili derlemesinde kullanılabilir. Genel paket, istendiğinde bile bunları atlar ve bıraktığı modülleri adlandıran bir uyarı günlüğe kaydeder.

Yararlı tercihler (--pref)

• remote.prefs.recommended=false. Firefox otomasyonda çalışırken, test için tarayıcı davranışını değiştiren RecommendedPreferences uygular. Bunları atlamak ve normal bir Firefox örneğine daha yakın bir yapılandırmaya sahip olmak için remote.prefs.recommended değerini false olarak ayarlayın.
• remote.log.level=Trace. Firefox'ta ayrıntılı WebDriver protokol günlüklerini etkinleştirin. MCP sunucusu, her iki tarafın da aynı ayrıntı düzeyinde günlük kaydetmesi için eşleşen günlük düzeyini otomatik olarak geckodriver'a iletir.
• app.update.disabledForTesting=false. Firefox'un güncellemeleri otomatik olarak indirmesine ve uygulamasına izin verin. Güncellemelerin oturumunuzu kesebileceğini unutmayın. Ayrıca remote.prefs.recommended=false ayarının da yapılmasını gerektirir.

Firefox for Android

Android cihazda çalışan Firefox'u otomatikleştirmek için --android-device kullanın. PATH'inizde adb ve otomatik olarak yönetilen geckodriver gerektirir.

Uyarı: Android modu, her oturumdan önce hedef uygulamanın tüm verilerini siler. Sekmeler, geçmiş, yer imleri, parolalar, çerezler ve ayarların tümü kaybolur. geckodriver, oturumu oluştururken adb shell pm clear <package> çalıştırır ve bunu atlamanın bir yolunu sunmaz, ardından oturumu daha sonra silinen kendi geçici profili üzerinde çalıştırır. Bu nedenle, --android-device --android-wipe-app-data gerektirir ve kullandığınız tarayıcıyı otomatikleştirmek yerine otomasyona ayrılmış bir derleme kurmalısınız. Bug 2064088, geckodriver'a mevcut uygulama verilerini koruma seçeneği eklemeyi izler.

# 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

Ana bilgisayar ile cihaz arasındaki bağlantı noktası yönlendirmesi geckodriver tarafından otomatik olarak yönetilir.

Mevcut Firefox'a bağlanın

Çerezler, oturum açma bilgileri ve açık sekmeler bozulmadan gerçek tarama oturumunuzu otomatikleştirmek için --connect-existing kullanın:

# 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

MCP hem WebDriver Classic (--marionette) hem de WebDriver BiDi (--remote-debugging-port) kullandığından her iki bayrak da gereklidir. Firefox yalnızca --marionette ile başlatılırsa, MCP sunucusu bağlanamaz ve Firefox'u her iki bayrakla yeniden başlatmanızı ister.

Uyarı: Normal gezinme sırasında Marionette'i etkin bırakmayın. navigator.webdriver = true ayarlar ve Cloudflare, Akamai vb. tarafından korunan sitelerde bot algılamayı tetikleyebilecek diğer tarayıcı parmak izi sinyallerini değiştirir. Marionette'i yalnızca MCP otomasyonuna ihtiyacınız olduğunda etkinleştirin, ardından Firefox'u normal şekilde yeniden başlatın.

Araç genel bakışı

Modüllere göre araçların tam listesi, açıklamalar ve parametrelerle birlikte docs/tools.md dosyasına bakın (kaynaktan üretilmiştir).

• Sayfalar: list/new/navigate/select/close/get_page_text (get_page_text isteğe bağlı saveTo destekler)
• Anlık görüntü/UID: take/resolve/clear (take isteğe bağlı saveTo destekler)
• Girdi: click/hover/fill/drag/upload/form fill
• Ağ: list/get (ID-öncelikli, filtreler, her zaman açık yakalama; her ikisi de isteğe bağlı saveTo destekler)
• İndirmeler: list_downloads/clear_downloads (her zaman açık yakalama), set_download_behavior (allow/deny/default)
• Konsol: list/clear (list isteğe bağlı saveTo destekler)
• Ekran görüntüsü: sayfa/uid ile (CLI ortamları için isteğe bağlı saveTo ile)
• Betik: evaluate_script (izole bir alan için isteğe bağlı sandbox; büyük sonuçlar için isteğe bağlı saveTo)
• Ayrıcalıklı Bağlam: ayrıcalıklı ("chrome") bağlamları list/select, evaluate_privileged_script (MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 gerektirir)
• WebExtension: install_extension, uninstall_extension, list_extensions (list MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 gerektirir)
• Firefox Yönetimi: get_firefox_info, get_firefox_output, restart_firefox
• Firefox Tercihleri: get_firefox_prefs, set_firefox_prefs (MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 gerektirir)
• Profil Oluşturucu: profiler_is_active, profiler_start (ön ayar veya açık yapılandırma), profiler_stop (profili indirme dizinine kaydeder)
• Ekran Kaydı: screencast_start (sayfa görünüm alanını indirme dizinindeki bir video dosyasına kaydeder), screencast_stop (Firefox 154+ gerektirir)
• Yardımcı Programlar: accept/dismiss dialog, history back/forward, set viewport

Büyük çıktıyı diske kaydetme

Büyük araç çıktısı, Claude Code gibi CLI istemcilerinde önemli miktarda bağlam tüketebilir. screenshot_page, screenshot_by_uid, take_snapshot, list_console_messages, list_network_requests, get_network_request, get_page_text, evaluate_script ve evaluate_privileged_script araçları, sonucu satır içi döndürmek yerine bir dosyaya yazan isteğe bağlı bir saveTo parametresi kabul eder. saveTo üç biçimden birini alır:

• bir dosya yolu (geçerli çalışma dizinine göreli veya ~/.firefox-devtools-mcp içinde mutlak; üst dizinler oluşturulur)
• mevcut bir dizin (içinde zaman damgalı bir dosya oluşturulur)
• true (~/.firefox-devtools-mcp/output/ altında zaman damgalı bir dosya oluşturulur)

Yanıt, yolu ve bayt boyutunu döndürür. Kaydedilen dosya her zaman tam, kesilmemiş veriyi tutar: satır içi boyut korumaları (konsol mesajı sınırları, ağ başlığı kesme, anlık görüntü satır sınırları) ona asla uygulanmaz.

Metin üreten araçlar (ekran görüntüleri hariç her şey) ayrıca preview kabul eder; bu, kaydedilen çıktının satır içi kısa bir alıntı olarak yansıtılacak karakter sayısıdır. Ekran görüntülerinin önizlemesi yoktur.

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

Varsayılan olarak, kaydetme yolları kısıtlıdır: göreli yollar geçerli çalışma dizinine göre çözümlenir ve mutlak yollara yalnızca ~/.firefox-devtools-mcp içinde izin verilir. Bu konumların dışına çıkan yollar reddedilir. Sunucuyu --unrestricted-save-paths ile başlatarak, o dizinin dışındaki mutlak yollar da dahil olmak üzere isteğe bağlı konumlara yazma izni verin.

Kaydedilen dosyalar daha sonra örneğin Claude Code'un Read aracıyla, bağlam boyutunu etkilemeden görüntülenebilir.

Yerel geliştirme

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

Yerel geliştirme, test ve CI hakkında daha fazla ayrıntı için CONTRIBUTING.md dosyasına bakın.

Sorun giderme

• Firefox bulunamadı: --firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox" (macOS) veya işletim sisteminizdeki doğru yolu iletin.
• İlk çalıştırma yavaştır: Selenium BiDi oturumunu kurar; sonraki çalıştırmalar daha hızlıdır.
• Eski UID'ler: Bir UID, öğesi kaldırılana veya sayfa gezinene kadar geçerli kalır; bir UID aracı kaybolduğunu bildirdiğinde yeni bir anlık görüntü alın (take_snapshot).
• Windows 10: 'firefox-devtools' MCP sunucusu için keşif sırasında hata: MCP hatası -32000: Bağlantı kapalı

  • Çözüm 1 cmd /c ile sarmalayın (ayrıntılar):

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

  • Çözüm 2 npx için mutlak yolu kullanın (uzantıyı ayarlayın — .cmd, .bat, .exe veya .ps1 — kurulumunuza uyacak şekilde):

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

Sürüm oluşturma

• 1.0 öncesi API: sürümler 0.x ile başlar. En yeni sürüm için npx ile @latest kullanın.

Katkıda bulunma

Sorun bildirme, test çalıştırma ve proje üzerinde yerel olarak çalışma hakkında bilgi için CONTRIBUTING.md dosyasına bakın.

Yazar

Mozilla tarafından sürdürülmektedir.

Lisans

Seçiminize bağlı olarak MIT veya Apache 2.0 altında lisanslanmıştır.