Puppeteer MCP

Headless (veya headed) bir Chrome tarayıcıyı AI'ın kontrolüne veren MCP sunucusu. Sayfaya git, element seç, tıkla, yaz, JavaScript eval et, screenshot çek, içerik çıkar. Scraping, form otomasyonu, E2E test senaryolarının AI ile yürütülmesi, bug reproduction için.

Ne işe yarar?

• Web scraping: JS ile render olan SPA'lardan veri çıkarma (sadece HTML fetch yetmediği yerde)
• Form otomasyonu: Tekrarlanan form doldurma işleri (test datası girme vb.)
• Visual regression: Aynı sayfanın iki sürümünün screenshot'ını alıp karşılaştırma
• Bug reproduction: "X sayfasında Y butonuna basınca ne oluyor?" — AI kendisi denesin
• Accessibility audit: AI klavyeyle gezinsin, eksik label'ları rapor etsin
• E2E test adımları: Test senaryosunu AI'a anlat, kendisi tıklayıp valide etsin
• Yönetim paneli otomasyonu: API'si olmayan eski admin UI'da tekrar eden işler

Yetenekler

Tool	Açıklama
puppeteer_navigate	URL'ye git
puppeteer_screenshot	Viewport / element screenshot
puppeteer_click	CSS selector ile tıkla
puppeteer_fill	Input doldur
puppeteer_select	Dropdown seç
puppeteer_hover	Element üzerine gel
puppeteer_evaluate	Sayfada rastgele JavaScript çalıştır

Ayrıca console log'lar bir resource olarak okunabilir — AI sayfanın JS hatalarını görebilir.

Kurulum

Claude Code

claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

İlk çalıştırmada Chromium binary indirilir (~170MB). Bunu atlamak için sistem Chrome'unu kullan:

claude mcp add puppeteer \
  --env PUPPETEER_EXECUTABLE_PATH=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --env PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
  -- npx -y @modelcontextprotocol/server-puppeteer

Claude Desktop / Cursor

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "env": {
        "PUPPETEER_LAUNCH_OPTIONS": "{\"headless\": true, \"defaultViewport\": {\"width\": 1280, \"height\": 800}}",
        "ALLOW_DANGEROUS": "false"
      }
    }
  }
}

headless: false yaparsan tarayıcı görünür — debugging için yararlı.

Docker

{
  "command": "docker",
  "args": [
    "run", "-i", "--rm", "--init",
    "--cap-add=SYS_ADMIN",
    "mcp/puppeteer"
  ]
}

Güvenlik

• AI bütün interneti gezebilir. PII içeren, authenticate olduğun sayfalara girerse AI cookie/session üzerinden işlem yapabilir.
• Login bilgilerin tarayıcıda kalmasın: Fresh profile kullan, cached credential yok.
• puppeteer_evaluate = arbitrary JS. AI'a hangi sayfada ne eval ettiğini net ver. Sensitif DOM verisi çıkarılabilir.
• ALLOW_DANGEROUS env: true yaparsan --no-sandbox gibi flag'ler açılır — CTF / test dışında kapalı tut.
• Download'lar: scripted download noktasını temiz tut, her şeyi indirmesin.
• Kurumsal VPN: AI oradan çıkış yaparak lokal-only kaynakları da görebilir — bilinçli ol.

Örnek kullanımlar

SPA scraping

"https://example.com/listings sayfasını aç, tüm kart'ları scroll ederek yükle (lazy load), sonra her kartın başlık + fiyat + link'ini JSON olarak döner."

AI:

1. navigate → URL
2. evaluate → window.scrollTo(0, document.body.scrollHeight) döngüsü
3. evaluate → Array.from(document.querySelectorAll(...)).map(...)
4. JSON döner

Bug reproduction

"Staging'de /settings sayfasında Save'e bastığımda 500 alıyorum. Aynısını reproduce et, network tab'de hatayı yakala."

Accessibility kontrolü

"/signup form'unu klavyeyle doldurmaya çalış. Hangi alanlar Tab ile erişilemedi?"

Screenshot karşılaştırma

"Feature branch'in deploy URL'i ve main'in URL'i için aynı sayfanın screenshot'ını al, farkları söyle."

Sınırlar

• CAPTCHA: çözmez. Recaptcha, hCaptcha, vb. engel olur. Legal engel de teşkil eder.
• Login duvarları: OAuth / 2FA varsa manuel login, sonra cookie state'i aktar
• Video stream'leri: izleyemez, ses analiz etmez
• Desktop app'ler: sadece web — Electron harici yerel uygulama yok
• Multi-tab orchestration kısıtlı — her session tek tab'le çalışır tipik
• Mobile emulation viewport seviyesinde, native app simülasyonu değil

Sorun giderme

Belirti	Sebep	Çözüm
Browser launch failed	Chromium yok	npm install puppeteer ya da sistem Chrome path'i ver
Element bulunamıyor	Selector yanlış veya zamanlama	waitForSelector kullan, ya da evaluate ile kontrol et
Timeout	Sayfa ağır	navigationTimeout'u artır
Target closed	Sayfa kapandı	Yeni navigate
PDF çıktısında font hatası	System font eksik	Docker'da alpine yerine mcp/puppeteer kullan

Doğrulama

/mcp

puppeteer yeşil ise AI'a sor:

"example.com'un screenshot'ını al, title'ı ne?"

Screenshot + title dönmeli.

Puppeteer mı, Playwright mı?

• Puppeteer MCP: Anthropic'in resmi server'ı, Chrome odaklı, sadelik
• Playwright MCP (topluluk): multi-browser (Chrome + Firefox + WebKit), daha fazla tool. Test-ağırlıklı iş yapıyorsan tercih edebilirsin — repo: microsoft/playwright-mcp.

---

Resmi repo: github.com/modelcontextprotocol/servers · Anthropic maintained