firefox-devtools-mcp

Firefox DevTools MCP

Model Context Protocol sunucusu; yapay zeka ajanlarının Firefox kullanmasını sağlar. İki ana kullanım senaryosu vardır:

• Ajan tabanlı gezinme: ajan, tarayıcıyı normal görevler için kullanır; sayfaları okuma, formları doldurma ve web sitelerinde çok adımlı akışları tamamlama gibi.
• Ajan destekli web geliştirme: ajan, üzerinde çalıştığınız sayfayı yükler ve konsol, ağ istekleri, hata ayıklayıcı ve profil oluşturucu gibi geliştirici araçlarıyla inceler.

Firefox'u WebDriver BiDi (Selenium WebDriver aracılığıyla) ile kontrol eder ve 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 — ajan, tarayıcının erişebildiği her şeye, çerezler ve kayıtlı oturumlar dahil, erişebilir.
• Ziyaret ettiğiniz sitelere dikkat edin. Sayfalar, ajanı manipüle etmek için tasarlanmış içerik döndürebilir (istemci enjeksiyonu). 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 bunu 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, ajanı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üzenleme

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, bu yolun firefox_devtools_mcp_profile alt klasöründe çalışır ve .firefox-devtools-mcp dosyasıyla işaretlenir; --profile-path işaretli bir profile işaret etmek onu doğrudan yeniden kullanır
• --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 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 tek bağlı cihazı otomatik 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 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üllerin açığa çıkarılacağını 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.

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

• slim — sayfalarda gezinmek ve etkileşim kurmak için minimum
• basic (varsayılan) — normal gezinme için araçlar ekler
• developer — web geliştiricileri için araçlar ekler
• mozilla — Firefox geliştiricileri için araçlar ekler
• all — her modül

Modüllerin listesi ve her ön ayardaki modüller için docs/tools.md dosyasına bakın.

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 için SECURITY.md dosyasına bakın ve 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 iç derlemesinde kullanılabilir. launch modülü de Mozilla iç derlemesini gerektirir: Firefox'u çağıranın seçtiği bir ikili dosya, profil, ortam ve tercihler kümesi altında yeniden başlatır; bu, operatörün sahip olması gereken bir yapılandırma değişikliğidir. Bunun yerine --pref, --firefox-path ve diğer komut satırı seçeneklerini kullanın. bidi modülü de Mozilla iç derlemesini gerektirir: herhangi bir WebDriver BiDi komutu gönderir, böylece diğer modüllerin açığa çıkardıklarına erişim sağlar. Genel paket, istendiğinde bile bu modülleri 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, eşleşen günlük düzeyini otomatik olarak geckodriver'a iletir, böylece her iki taraf da aynı ayrıntı düzeyinde günlük tutar.
• 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ı 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, hedef uygulamanın tüm verilerini her oturumdan önce siler. Sekmeler, geçmiş, yer imleri, parolalar, çerezler ve ayarların tümü kaybolur. geckodriver, oturum oluştururken adb shell pm clear <package> çalıştırır ve atlama seçeneği 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ğlanma

Çerezler, oturum açma bilgileri ve açık sekmeler bozulmadan gerçek gezinme 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

Her iki bayrak da gereklidir çünkü MCP hem WebDriver Classic (--marionette) hem de WebDriver BiDi (--remote-debugging-port) kullanır. 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 (kaynaktan üretilmiştir) docs/tools.md dosyasına bakın.

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

Büyük araç çıktısı, Claude Code gibi CLI istemcilerinde önemli bağlam tüketebilir. Bazı araçlar, sonucu satır içi döndürmek yerine bir dosyaya yazan isteğe bağlı bir saveTo parametresini kabul eder. Liste için docs/tools.md dosyasına bakın. saveTo üç biçimden birini alır:

• bir dosya yolu (geçerli çalışma dizinine göreli veya ~/.firefox-devtools-mcp/output içinde mutlak; üst dizinler oluşturulur). Firefox profiline ulaşan yollar veya bu sunucunun geri okuduğu dosyalar reddedilir
• 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ı) asla ona uygulanmaz.

Metin üreten araçlar ayrıca, kaydedilen çıktının kısa bir alıntı olarak satır içi geri yansıtılacak karakter sayısı olan preview kabul eder. docs/tools.md içindeki liste hangi araçların bunu desteklediğini gösterir.

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 konumlardan kaçan yollar reddedilir. Bu dizinin dışındaki mutlak yollar dahil keyfi konumlara yazmak için sunucuyu --unrestricted-save-paths ile başlatın.

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 belirtin.
• İ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ı kapandı

  • Çö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ümleme

• 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

MIT veya Apache 2.0 lisanslarından birini seçerek lisanslanmıştır.