firefox-devtools-mcp

Firefox DevTools MCP

Firefox'u WebDriver BiDi (Selenium WebDriver aracılığıyla) üzerinden otomatikleştirmek için Model Context Protocol sunucusu. 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ışamaz. 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ç temel uygulama:

• Özel bir Firefox profili kullanın. Sunucuyu asla normal profilinize karşı çalıştırmayın — aracı, çerezler ve kayıtlı oturumlar dahil tarayıcının erişebildiği her şeye erişebilir.
• Hangi siteleri ziyaret ettiğinize dikkat edin. Sayfalar, aracıyı 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.
• Gerekmedikçe ekstra bayrakları etkinleştirmekten kaçının. --enable-script ve --enable-privileged-context, aracının yapabileceklerini önemli ölçüde 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 belirtilir)

Claude Code ile kurulum ve kullanım (npx)

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

Seçenek A — Claude Code CLI

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

Seçenekleri argüman veya ortam değişkeni olarak iletin. Örnekler:

# 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

Seçenek B — Claude Code ayarları JSON'ını düzenleyin

Claude Code yapılandırma dosyanıza ekleyin:

• 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"
      }
    }
  }
}

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 (sürekli yakalama), get_network_request
• screenshot_page, list_console_messages

CLI seçenekleri

Bayraklar veya ortam değişkenleri (sağdaki adlar) iletebilirsiniz:

• --firefox-path — Firefox ikili dosyasının mutlak yolu
• --headless — Kullanıcı arayüzü olmadan çalıştır (FIREFOX_HEADLESS=true)
• --viewport 1280x720 — Başlangıç pencere boyutu
• --profile-path — Belirli bir Firefox profili kullan
• --firefox-arg — Ekstra Firefox argümanları (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 — Yeni bir tane başlatmak yerine zaten çalışan bir Firefox'a bağlan (CONNECT_EXISTING=true)
• --marionette-port — Mevcut bağlantı modu için Marionette portu, varsayılan 2828 (MARIONETTE_PORT)
• --pref name=value — Başlangıçta moz:firefoxOptions aracılığıyla Firefox tercihi ayarla (tekrarlanabilir)
• --enable-script — evaluate_script aracını (sayfa bağlamında rastgele JavaScript yürütür) ve hata ayıklama araçlarını (betikleri listele, kaynağı incele, günlük noktaları ayarla) etkinleştir. Hata ayıklama araçları Firefox 153+ gerektirir. (ENABLE_SCRIPT=true)
• --enable-privileged-context — Ayrıcalıklı bağlam araçlarını etkinleştir: ayrıcalıklı bağlamları listele/seç, ayrıcalıklı betikleri değerlendir, Firefox tercihlerini al/ayarla ve eklentileri listele. MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 gerektirir (ENABLE_PRIVILEGED_CONTEXT=true)
• --android-device — Android için Firefox 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. Tek bağlı cihazı otomatik olarak seçmek için değeri atlayın veya auto kullanın.
• --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)
• --log-file — MCP sunucu günlüklerini stderr yerine bir dosyaya yaz. Sunucu çıktısını gizleyen MCP istemcileriyle oturum hata ayıklaması 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

Yararlı tercihler (--pref)

• remote.prefs.recommended=false. Firefox otomasyonda çalıştığında, 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ştir. MCP sunucusu, her iki tarafın da aynı ayrıntı düzeyinde günlük tutması için eşleşen günlük seviyesini otomatik olarak geckodriver'a iletecektir.
• app.update.disabledForTesting=false. Firefox'un güncellemeleri otomatik olarak indirip uygulamasına izin ver. Güncellemelerin oturumunuzu kesebileceğini unutmayın. Ayrıca remote.prefs.recommended=false ayarını gerektirir.

Android için Firefox

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

# 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

Ana bilgisayar ile cihaz arasındaki bağlantı noktası yönlendirme, geckodriver tarafından otomatik olarak yapılır.

Mevcut Firefox'a bağlan

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

# Start Firefox with Marionette enabled
firefox --marionette

# Run the MCP server
npx @mozilla/firefox-devtools-mcp --connect-existing --marionette-port 2828

Veya her başlatmada Marionette'i etkinleştirmek için about:config (veya user.js) içinde marionette.enabled değerini true olarak ayarlayın.

BiDi'ye bağlı özellikler (konsol olayları, ağ olayları) mevcut bağlantı modunda kullanılamaz; diğer tüm özellikler normal şekilde çalışır.

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

Araç genel bakış

• Sayfalar: listele/yeni/gezin/seç/kapat
• Anlık Görüntü/UID: al/çözümle/temizle
• Girdi: tıkla/üzerine gel/doldur/sürükle/yükle/form doldur
• Ağ: listele/al (önce kimlik, filtreler, sürekli yakalama)
• Konsol: listele/temizle
• Ekran Görüntüsü: sayfa/uid ile (CLI ortamları için isteğe bağlı saveTo ile)
• Betik: evaluate_script
• Ayrıcalıklı Bağlam: ayrıcalıklı ("chrome") bağlamları listele/seç, evaluate_privileged_script (MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 gerektirir)
• WebExtension: install_extension, uninstall_extension, list_extensions (listeleme MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 gerektirir)
• Firefox Yönetimi: get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs
• Profil Oluşturucu: profiler_is_active, profiler_start (ön ayar veya açık yapılandırma), profiler_stop (profili indirilenler dizinine kaydeder)
• Yardımcı Programlar: iletişim kutusunu kabul et/reddet, geçmiş ileri/geri, görünüm alanını ayarla

Claude Code için ekran görüntüsü optimizasyonu

Claude Code CLI'de ekran görüntüleri kullanırken, base64 görüntü verileri önemli miktarda bağlam tüketebilir. Ekran görüntülerini diske kaydetmek için saveTo parametresini kullanın:

screenshot_page({ saveTo: "/tmp/page.png" })
screenshot_by_uid({ uid: "abc123", saveTo: "/tmp/element.png" })

Dosya daha sonra bağlam boyutunu etkilemeden Claude Code'un Read aracıyla 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ş: Selenium BiDi oturumunu kurar; sonraki çalıştırmalar daha hızlıdır.
• Gezinme sonrası eski UID'ler: UID araçlarını kullanmadan önce 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 sarın (detaylar):

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

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

    "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, testleri ç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.