Playwright MCP Nedir? Kurulum ve Proxy Ayarları

Claude Code'a ya da Cursor'a "şu sayfayı aç, ilk üç ürünün fiyatını oku" dediğinizde asistan çoğu zaman sayfanın ham HTML'ini getirir. Fiyat JavaScript ile yükleniyorsa elinde boş bir iskelet kalır. Playwright MCP bu boşluğu kapatır: asistanın arkasına gerçek bir tarayıcı koyar, tıklama ve yazma işlerini araç çağrısı olarak sunar. Kurulum tek satırdır. Sorular sonra gelir: tarayıcı hangi IP'den çıkıyor, proxy'nin kullanıcı adı ve parolası nereye yazılıyor, ajan istediği her siteye gidebiliyor mu?

Bu yazıda Playwright MCP'nin ne olduğunu ve nasıl çalıştığını, erişilebilirlik ağacının ekran görüntüsünden farkını, dört yaygın istemcide kurulumu, işe yarayan bayrakları, proxy ayarını (kimlik doğrulamalı proxy dahil), --allowed-origins ile alan kısıtlamayı ve bu kısıtın neden güvenlik sınırı sayılmadığını anlatıyoruz. Bayrakları yazım günü resmî README'den ve --help çıktısından doğruladık. Örnekleri @playwright/mcp 0.0.82 ile, yerel bir test proxy'si üzerinden çalıştırdık.

Playwright MCP nedir?#

Playwright MCP, resmî deposundaki tanımıyla, Playwright'ı kullanarak tarayıcı otomasyonu sunan bir Model Context Protocol sunucusudur. İki parçadan oluşur. Playwright; Chromium, Firefox ve WebKit'i koddan yöneten kütüphanedir ve ayrıntısını Playwright Nedir ve Proxy ile Nasıl Kullanılır? yazımızda anlattık. MCP ise yapay zekâ uygulamalarını dış araçlara standart bir yolla bağlayan protokoldür.

Protokolün kendisini burada yeniden anlatmıyoruz. Bilmeniz gereken şu kadar: asistan uygulaması (host) MCP sunucusunu yerel bir süreç olarak başlatır, sunucu elindeki araçların listesini ve şemalarını bildirir, model de gerektiğinde bu araçları çağırır. Host, client ve server ayrımı, taşıma yöntemleri ve protokol düzeyindeki riskler MCP (Model Context Protocol) Nedir? Detaylı Rehber yazımızda.

Playwright MCP'nin sunduğu araçlar tarayıcı eylemleridir: browser_navigate, browser_click, browser_type, browser_fill_form, browser_snapshot, browser_take_screenshot, browser_tabs ve benzerleri. 0.0.82 sürümünde varsayılan kurulum 25 araç bildirdi. --caps=vision,pdf eklediğimizde koordinatla tıklama ve PDF üretimi de gelerek sayı 32'ye çıktı. Kendi kodunuzla bir tarayıcı betiği yazmaktan farkı, adımlara modelin karar vermesidir: siz hedefi söylersiniz, hangi bağlantıya tıklanacağını model sayfaya bakarak seçer. Ajan döngüsünün genel işleyişi AI Ajanları Nasıl Çalışır? yazımızda.

Playwright MCP nasıl çalışır?#

Bir istek baştan sona şu adımlardan geçer:

1. Host uygulaması yapılandırmadaki komutu çalıştırır: npx @playwright/mcp@latest. Sunucu stdio üzerinden bağlanır ve araç listesini bildirir.
2. Siz doğal dille bir görev yazarsınız. Model browser_navigate aracını adresle birlikte çağırır.
3. Sunucu ilk araç çağrısında tarayıcıyı başlatır. --browser verilmediğinde testimizde sistemde kurulu Google Chrome açıldı; pencere varsayılan olarak görünürdür, --headless ile gizlenir.
4. Sayfa yüklenince sunucu sayfanın adresini, başlığını ve erişilebilirlik ağacının anlık görüntüsünü (snapshot) üretir. 0.0.82'de browser_navigate yanıtı bu görüntüyü çalışma klasöründeki .playwright-mcp dizinine YAML dosyası olarak kaydedip yolunu verdi, browser_snapshot ise ağacı doğrudan yanıtın içinde döndürdü.
5. Ağaçtaki her öğenin bir referansı vardır: link "Travel" [ref=e21]. Model tıklamak istediği öğeyi bu referansla bildirir: browser_click, target: e21.
6. Sunucu eylemi Playwright ile yürütür ve yanıtta çalıştırdığı kodu da gösterir: await page.getByRole('link', { name: 'Travel' }).click();. Ardından yeni sayfanın görüntüsü döner ve döngü sürer.

Bu kod satırı sayesinde ajanın yaptığı keşfi sonradan sıradan bir Playwright betiğine çevirebilirsiniz. --codegen bayrağı bu çıktının dilini seçer (typescript, python, java, csharp ya da none).

Erişilebilirlik ağacı ekran görüntüsünden neden daha kullanışlı?#

Erişilebilirlik ağacı, tarayıcının ekran okuyucular için ürettiği yapıdır. MDN'in tanımına göre her öğe için dört bilgi taşır: ad, açıklama, rol ve durum. Playwright bu ağacı YAML olarak dışa verir; biçimin ayrıntısı aria snapshot belgesinde. Test sayfamızın (books.toscrape.com) görüntüsü şöyle başladı:

- generic [active] [ref=e1]:
  - banner [ref=e2]:
    - generic [ref=e5]:
      - link "Books to Scrape" [ref=e6] [cursor=pointer]:
        - /url: index.html
      - text: We love being scraped!
  # ... (kısaltıldı)
            - list [ref=e19]:
              - listitem [ref=e20]:
                - link "Travel" [ref=e21] [cursor=pointer]:
                  - /url: catalogue/category/books/travel_2/index.html

Model bu metinde neyin bağlantı, neyin düğme, neyin metin kutusu olduğunu doğrudan okur. Ekran görüntüsünde aynı bilgiyi pikselden çıkarması, sonra da tıklanacak noktanın koordinatını tahmin etmesi gerekir.

Aracın kendi açıklaması da aynı şeyi söyler: ekran görüntüsüne bakarak eylem yapılamaz, eylem için snapshot kullanılır. Yine de metnin bedava olduğunu düşünmeyin. Testimizde kitap listesinin ana sayfası yaklaşık 32 bin karakterlik bir ağaç üretti, 25 aracın şeması da 20 bin karaktere yakındı. Bunlar karakter sayılarıdır; token karşılığı modele göre değişir ve biz ölçmedik. README aynı konuda açık sözlüdür: büyük kod tabanıyla çalışan kodlama ajanları için araç şemalarını ve ağacı bağlama yüklemeyen Playwright CLI yolunu önerir, MCP'yi ise kalıcı tarayıcı durumu ve sayfa üzerinde adım adım akıl yürütme gerektiren işler için konumlar. --snapshot-mode=none yanıtlara otomatik görüntü eklenmesini kapatır, --mobile ise daha hafif mobil sayfaları açtırır.

Playwright MCP kurulumu nasıl yapılır?#

Gereken tek şey Node.js 18 ya da daha yeni bir sürüm ve MCP destekleyen bir istemcidir. Paketi elle kurmazsınız; istemci her açılışta npx ile çalıştırır. README'nin "standart yapılandırma" dediği giriş çoğu istemcide aynıdır:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

İstemciye göre bu girişin yazıldığı yer değişir:

Claude Code'da sunucuya bayrak geçecekseniz araya -- koyun. Claude Code'un MCP belgesine göre çift tireden sonraki her şey sunucu komutuna dokunulmadan aktarılır:

claude mcp add --scope project playwright -- npx @playwright/mcp@latest --headless --isolated

--scope project girişi proje kökündeki .mcp.json dosyasına yazar; dosyayı depoya eklerseniz ekip aynı ayarı kullanır. Komutu denediğimizde dosyada yukarıdaki standart girişin bayraklı hâli oluştu. Bağlantıyı claude mcp list ile ya da oturum içinde /mcp ile kontrol edebilirsiniz. VS Code tarafının ayrıntısı VS Code MCP belgesinde.

@latest etiketi her açılışta güncel sürümü çeker. Paket hızlı değişiyor: bu yazıdaki bayrak adları 0.0.82'ye aittir. Ekipçe aynı davranışı istiyorsanız sürümü sabitleyin (@playwright/mcp@0.0.82) ve yükseltmeden önce npx @playwright/mcp@latest --help çıktısına bakın.

En çok işe yarayan bayraklar hangileri?#

0.0.82'nin yardım çıktısı elli civarında seçenek listeler. Günlük kullanımda karşınıza çıkanlar şunlardır:

Her bayrağın bir ortam değişkeni karşılığı vardır (PLAYWRIGHT_MCP_PROXY_SERVER, PLAYWRIGHT_MCP_ALLOWED_ORIGINS gibi). Proxy değişkenini denedik, bayrakla aynı sonucu verdi.

Playwright MCP'de proxy nasıl ayarlanır?#

Kimlik doğrulama istemeyen, yani çıkış IP'nizin panelde IP whitelist'e eklendiği bir proxy için tek bayrak yeter:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--isolated",
        "--proxy-server=http://pr.proxynet.io:8000",
        "--proxy-bypass=localhost,127.0.0.1"
      ]
    }
  }
}

Bu yapılandırmayı yerel test proxy'mizle çalıştırdık: ajanın açtığı her sayfa proxy kaydına CONNECT satırı olarak düştü. --proxy-bypass listesine eklediğimiz alan adı ise kayıtta hiç görünmedi, yani doğrudan bağlandı. Yerel geliştirme sunucunuzu test ediyorsanız localhost girişini unutmayın; aksi hâlde ajan kendi makinenizdeki sayfaya proxy üzerinden ulaşmaya çalışır.

SOCKS5 de çalışır: --proxy-server=socks5://pr.proxynet.io:1080. Denememizde sayfa açıldı ve SOCKS5 sunucusuna alan adı gitti, yani DNS çözümlemesi proxy tarafında kaldı. SOCKS5'te kullanıcı adı ve parola desteklenmez; nedeni Chromium'dur ve ayrıntısı yukarıda andığımız Playwright proxy yazısındadır. Ürün tarafı SOCKS5 Proxy sayfasında.

Proxy'nin gerçekten devrede olduğunu ajana sorarak doğrulayabilirsiniz: "https://httpbin.org/ip adresini aç ve gördüğün IP'yi yaz." Dönen adres kendi IP'niz değilse trafik proxy'den geçiyordur.

Kullanıcı adı ve parolalı proxy nasıl tanımlanır?#

İlk akla gelen yol, kimlik bilgisini adrese gömmektir: --proxy-server=http://user:pass@pr.proxynet.io:8000. Çalışmaz. Denediğimizde sunucu başladı, ama ilk gezinme şu hatayla döndü:

Error: browserBackend.callTool: net::ERR_INVALID_AUTH_CREDENTIALS at https://httpbin.org/ip

Proxy kaydında isteğin kimlik bilgisi olmadan geldiğini ve 407 aldığını gördük. Kimlik bilgisini hiç yazmadığımızda da hata aynıydı. Yani bayrak yalnızca şemayı, sunucuyu ve portu taşır.

Çözüm yapılandırma dosyasıdır. --config ile verilen JSON'daki browser.launchOptions alanı Playwright'ın kendi başlatma seçeneklerine aktarılır; proxy nesnesi de oradadır:

{
  "browser": {
    "isolated": true,
    "launchOptions": {
      "headless": true,
      "proxy": {
        "server": "http://pr.proxynet.io:8000",
        "username": "user",
        "password": "pass"
      }
    }
  },
  "network": {
    "allowedOrigins": ["https://books.toscrape.com", "https://httpbin.org"]
  }
}

İstemci tarafındaki giriş yalnızca dosyayı gösterir:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--config=playwright-mcp.json"]
    }
  }
}

Bu ikiliyi kullanıcı adı ve parola isteyen yerel proxy'mizle denedik: tarayıcı önce 407 aldı, kimlik bilgisini gönderdi ve sayfa açıldı. Dosya yolunu mutlak yazmak daha güvenlidir, çünkü istemcinin sunucuyu hangi dizinde başlattığı uygulamaya göre değişir.

Parola düz metin olarak bir dosyada duracağı için iki önlem alın: dosyayı depoya eklemeyin ve mümkünse bu iş için ayrı bir proxy kullanıcısı açın. Parolayı hiç yazmak istemiyorsanız IP whitelist ile ilk bölümdeki tek bayraklı kuruluma dönersiniz. İki yöntemin karşılaştırması Proxy Kimlik Doğrulama: User:Pass ve IP Whitelist yazımızda.

Ajanın gezebileceği alanlar nasıl kısıtlanır?#

Modele tarayıcı vermek, okuduğu her sayfanın ona talimat fısıldayabilmesi demektir. Dolaylı prompt injection'ın işleyişini ve izin listesinin neden yasak listesinden daha sağlam olduğunu LLM'e Güvenli Web Erişimi: Hız Sınırı ve İzinler yazımızda anlattık. Playwright MCP o fikrin hazır bir uygulamasını sunar:

"args": [
  "@playwright/mcp@latest",
  "--allowed-origins=https://books.toscrape.com;https://httpbin.org"
]

Origin şema, alan adı ve porttan oluşur; liste noktalı virgülle ayrılır. Yapılandırma dosyasındaki karşılığı network.allowedOrigins dizisidir ve http://localhost:* biçiminde port joker karakteri kabul eder. --blocked-origins tersini yapar ve önce değerlendirilir; izin listesi olmadan kullanıldığında listede olmayan her adres açık kalır.

Testimizde liste dışındaki bir adrese gitmeye çalışan ajan şu yanıtı aldı: net::ERR_BLOCKED_BY_CLIENT. İzinli sayfanın içine koyduğumuz liste dışı bir görsel de yüklenmedi, yani kural yalnızca gezinmeyi değil alt kaynakları da kapsıyor.

Bu uyarının pratikte ne anlama geldiğini üç gözlemle gösterebiliriz:

• Yönlendirmeler listeyi aşar. İzin listesindeki yerel bir adres 302 ile liste dışı bir siteye yönlendirdiğinde sayfa açıldı ve ajan içeriğini okudu.
• Engellenen adrese bağlantı yine de açılabiliyor. Engellenen alan adı için proxy kaydında CONNECT satırı gördük. Sayfa yüklenmedi, ama tarayıcı o sunucuyla bağlantı kurdu.
• Tarayıcının kendi arka plan trafiği kurala tabi değil. Chrome'un güncelleme ve hesap servislerine giden istekleri listeden bağımsız olarak proxy'den geçti. Trafiği GB ile ödüyorsanız bu istekler de sayaca yazılır.

Varsayılan araçlar arasında browser_evaluate ve browser_run_code_unsafe da vardır. İkincisinin açıklaması açıktır: sunucu sürecinde keyfi JavaScript çalıştırır ve uzaktan kod çalıştırmaya eşdeğerdir. Dosya sistemi erişimi varsayılan olarak çalışma klasörüyle sınırlıdır ve file:// adresleri engellidir; --allow-unrestricted-file-access bu sınırı kaldırır, gerekmedikçe kullanmayın.

Gerçek sınırı dışarıda kurarsınız: ajanı ayrı bir kullanıcı hesabında ya da konteynerde çalıştırın, --isolated ile kişisel oturumlarınızdan ayırın, araç çağrılarındaki onay adımını kapatmayın ve mümkünse çıkış proxy'sinde ikinci bir alan adı denetimi yapın. Bayraklar bu katmanların yerine geçmez, onlara eklenir.

Profil ve oturum: kalıcı mı, yalıtılmış mı?#

Varsayılan kip kalıcı profildir: çerezler ve giriş bilgileri diskte saklanır, bir sonraki oturumda ajan kaldığı yerden devam eder. Profil dizini istemcinin çalışma klasörüne göre türetilir, yani farklı projeler ayrı profil alır. README'nin bir uyarısı var: kalıcı profili aynı anda tek tarayıcı kullanabilir. Aynı projede iki istemci açacaksanız ikincisine --isolated ya da ayrı bir --user-data-dir verin.

--isolated her oturumu temiz başlatır ve tarayıcı kapanınca her şeyi siler. Veri okuma işlerinde doğru varsayılan budur. Kendi uygulamanızı giriş yapılmış hâlde test etmeniz gerekiyorsa çerezleri bir kez dışa aktarıp --storage-state ile yüklersiniz; biçimi Playwright'ın kimlik doğrulama belgesinde. Bu dosya oturum anahtarlarınızı taşır, parola gibi koruyun. Üçüncü kip, --extension ile açık olan Chrome'unuza bağlanmaktır. Ajan o zaman sizin giriş yapılmış bütün sekmelerinize erişebileceği için bu yolu yalnızca ne yaptığınızı bilerek seçin.

Kullanım alanları#

• Yerelleştirme kontrolü: sitenizin belirli bir ülkeden nasıl göründüğünü ajana gezdirmek. Proxy'yi o ülkenin çıkış noktasına ayarlar, ajandan dil, para birimi ve çerez bildirimi gibi öğeleri raporlamasını istersiniz. Ayrıntı yerelleştirme çözümü sayfasında; gerçek ev bağlantısı görünümü gereken kontrollerde Residential Proxy kullanılır.
• Keşif amaçlı test: kendi uygulamanızda bir akışı ajana yürütüp ürettiği Playwright kodunu kalıcı teste çevirmek. Farklı ülkelerden test kurgusu uygulama testi sayfasında.
• Dinamik sayfadan tek seferlik veri okuma: JavaScript ile yüklenen herkese açık bir sayfadan birkaç değeri almak. Düzenli ve büyük hacimli iş için ajan pahalıdır; kalıcı kurgu veri kazıma çözümü sayfasında, tarayıcının gerekip gerekmediği Statik ve Dinamik Sayfalar: Headless Tarayıcı Gerekir mi? yazısında.
• Hata ayıklama: browser_console_messages ve browser_network_requests araçlarıyla ajan, sayfanın konsol hatalarını ve ağ isteklerini okuyup size özetler.

Ajan da olsa gezen şey bir tarayıcıdır ve aynı kurallar geçerlidir: robots.txt dosyasına ve sitenin kullanım şartlarına uyun, resmî API varsa onu tercih edin, istek hızını düşük tutun. Tespit atlatma eklentileri önermiyoruz. Sitelerin otomatik ziyaretçiyi neden ayırt etmeye çalıştığını AI Alışveriş Ajanları Neden Sitelerde Engelleniyor? yazımızda anlattık.

Sık yapılan hatalar#

Tabloya girmeyen alışkanlık hataları da var:

• İzin listesini güvenlik önlemi saymak. Yönlendirme listeyi aşar; yalıtımı süreç ve ağ düzeyinde kurun.
• Kişisel Chrome profilini ajana açmak. E-posta ve banka oturumlarınızın durduğu profil, dış içerik okuyan bir modelin elinde olmamalıdır.
• Her iş için ekran görüntüsü istemek. Eylem zaten snapshot üzerinden yürür; görsel yalnızca görsel doğrulama içindir.
• @latest ile ekip çalışması. Bayrak adları sürümden sürüme değişebilir; sürümü sabitleyin.
• Düzenli taramayı ajana bırakmak. Her adımda model çağrısı yapılır. Ajanla keşfedin, üretilen kodu betiğe çevirip onu çalıştırın.

Karar rehberi#

Sıkça sorulan sorular#

Playwright MCP ücretsiz mi?#

Evet. Paket Apache 2.0 lisansıyla yayımlanır ve npx ile ücretsiz çalışır. Maliyet iki yerden gelir: modelin işlediği araç şemaları ile sayfa görüntüleri ve kullandığınız proxy trafiği.

Playwright MCP ile Playwright kütüphanesi arasındaki fark nedir?#

Kütüphanede adımları siz kodlarsınız, betik her çalıştığında aynı yolu izler. MCP sunucusunda adımlara model karar verir; siz yalnızca hedefi söylersiniz. İlki tekrarlanan işler için ucuz ve öngörülebilirdir, ikincisi keşif ve tek seferlik işler için hızlıdır. Kütüphane tarafındaki proxy ayrıntıları (context başına proxy, rotasyon, hata tablosu) Playwright proxy yazımızda.

Hangi tarayıcıyı kullanır, Chrome kurulu olmalı mı?#

--browser verilmediğinde testimizde sistemdeki Google Chrome açıldı. --browser firefox, webkit ya da msedge ile değiştirebilir, --executable-path ile belirli bir tarayıcı dosyasını gösterebilirsiniz.

Browser Use ile aynı şey mi?#

Amaç aynıdır: modele tarayıcı kullandırmak. Browser Use bağımsız bir Python ajan kütüphanesidir ve döngüyü kendi içinde yürütür. Playwright MCP ise yalnızca araçları sunar; döngüyü zaten kullandığınız asistan (Claude Code, Cursor, VS Code) yürütür.

Rotating proxy ile kullanılabilir mi?#

Kullanılabilir, ama tarayıcı bir sayfa için birçok bağlantı açar ve her bağlantıda IP değiştiren bir ağ geçidinde bu bağlantılar farklı adreslerden çıkabilir. Bağımsız sayfaları okurken sorun olmaz. Çok adımlı bir akışta oturumun ortasında IP değişmesini istemiyorsanız Sticky Proxy seçin. Rotasyonun işleyişi IP Rotasyonu Nedir ve Nasıl Çalışır? yazımızda.

Proxy kullanmak doğrulama ekranlarını ortadan kaldırır mı?#

Hayır. Proxy yalnızca isteğin hangi IP'den çıktığını değiştirir. Otomasyonla yönetilen bir tarayıcının bıraktığı sinyaller ve istek hızı aynı kalır. Kalıcı yol makul hız, izin verilen sayfalar ve varsa resmî API'dir.

Özetle#

Playwright MCP, asistanınıza gerçek bir tarayıcı verir ve sayfayı ona erişilebilirlik ağacı olarak okutur. Kurulum tek satırdır: npx @playwright/mcp@latest. Proxy için --proxy-server yeter; kullanıcı adı ve parola gerekiyorsa adrese gömmek ERR_INVALID_AUTH_CREDENTIALS ile biter, doğru yer yapılandırma dosyasındaki launchOptions.proxy nesnesidir. --allowed-origins ajanın alanını daraltır, ama yönlendirmeleri kapsamaz ve belgelerin kendi ifadesiyle güvenlik sınırı değildir; yalıtımı süreç ve ağ düzeyinde kurun. Sürümü sabitleyin, keşfi ajanla yapıp tekrarlanan işi betiğe devredin. Ajanınızın çıkış noktası için uygun proxy türlerini proxy hizmetlerimizde bulabilirsiniz.