Playwright MCP — 사용 사례, 설치 & 라이브 데모

Name: Playwright MCP Server
Author: microsoft

왜 쓰나요

핵심 기능

퍼스트파티 — Microsoft Playwright 팀에서 발행 및 유지보수
접근성 트리 기반 — 픽셀 기반 브라우저 에이전트보다 훨씬 안정적
Chromium, Firefox, WebKit 지원, headed 또는 headless 모드
멀티탭, 파일 업로드/다운로드, 네트워크 가로채기, 비디오 녹화

라이브 데모

실제 사용 모습

playwright.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

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

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

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

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

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

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

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

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "playwright": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@playwright/mcp@latest"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add playwright -- npx -y @playwright/mcp@latest

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Playwright

프로덕션 배포를 60초 안에 스모크 테스트하기

👤 DevOps 엔지니어, 릴리스 관리자 ⏱ ~5 min intermediate

언제 쓸까: 배포를 완료했으며 성공을 선언하기 전에 중요한 사용자 흐름이 여전히 작동하는지 빠르게 확인하고 싶을 때입니다.

사전 조건

테스트 계정 자격증명(실제 사용자가 아닌 전용 QA 계정 사용) — 환경 변수에 저장하거나 프롬프트에 직접 입력

흐름

홈페이지를 열고 로드되는지 확인

https://app.example.com을 엽니다. 페이지가 200을 반환하는지, H1이 'Welcome'을 표시하는지, 로그인 버튼이 보이는지 확인합니다.✓ 복사됨

→ 통과/실패, 실패 시 스크린샷 포함
로그인 → 핵심 작업 → 로그아웃 흐름 실행

[email protected] / [password]로 로그인합니다. 그 다음 'smoke-test-<timestamp>' 이름의 새 프로젝트를 만듭니다. 그 다음 삭제합니다. 그 다음 로그아웃합니다.✓ 복사됨

→ 각 단계 성공; 실패 시 스크린샷 + DOM 덤프
실패 진단

단계가 실패했다면 페이지 스냅샷을 캡처하고 작동하는 기준선과 어떤 점이 다른지 알려줍니다.✓ 복사됨

→ 손상된 특정 요소 또는 네트워크 요청

결과: 전체 E2E 스위트 없이 1분 이내에 배포에 대한 확신(또는 빠른 대응)을 얻습니다.

함정

하드코딩된 테스트 데이터가 축적되어 프로덕션을 오염시킴 — 항상 테스트 데이터에 고유한 타임스탬프를 사용하고 흐름 끝에서 정리합니다
브라우저 세션이 실행 간에 유지되어 깨끗한 상태가 필요한 버그를 숨김 — --browser-context: incognito로 실행하거나 실행 간에 쿠키를 지웁니다

함께 쓰기: sentry

5개 뷰포트 너비에서 사이트 감사하고 손상 보고

👤 프론트엔드 엔지니어, 디자이너 ⏱ ~15 min intermediate

언제 쓸까: 마케팅 사이트나 제품 페이지를 배포하기 전에 일반적인 너비에서 손상되지 않는지 확인하고 싶을 때입니다.

흐름

5개 뷰포트 너비(320, 375, 768, 1024, 1440)에서 페이지 열기

https://example.com을 뷰포트 320×568, 375×812, 768×1024, 1024×768, 1440×900에서 엽니다. 각각의 전체 페이지 스크린샷을 캡처합니다.✓ 복사됨

→ 5개 스크린샷 저장됨
각 너비에서 수평 오버플로우 감지

각 뷰포트에서 scrollWidth > viewportWidth인 요소를 나열합니다. 이들은 수평 스크롤을 유발하고 손상된 것처럼 보입니다.✓ 복사됨

→ 뷰포트별 문제 CSS 선택자 목록
수정 제안

각 오버플로우 요소에 대해 계산된 CSS를 가져오고 가장 작은 수정을 제안합니다(아마도 max-width, overflow-wrap 또는 breakpoint 조정).✓ 복사됨

→ 요소당 실행 가능한 diff

결과: 특정 선택자가 있는 우선순위가 지정된 수정 목록으로, 단일 PR로 제출하기에 적합합니다.

함정

실제 사용자는 스크롤바(Windows에서 15px)를 가지고 있으며, 헤드리스 브라우저는 기본적으로 이를 시뮬레이션하지 않습니다 — --browser=chromium과 --browser=webkit 모두로 테스트합니다. 너비는 생각보다 중요합니다

함께 쓰기: chrome-devtools · filesystem

사이트를 크롤링하고 손상된 모든 내부 링크 찾기

👤 문서 관리자, SEO 관리자 ⏱ ~30 min intermediate

언제 쓸까: 마케팅 푸시 전이나 분기별로 한 번 — 내부 링크의 조용한 404는 SEO와 사용자 신뢰를 해칩니다.

흐름

사이트를 크롤링하여 모든 내부 링크 수집

https://docs.example.com부터 시작하여 같은 도메인의 모든 페이지를 크롤링합니다(최대 깊이 3). 발견한 모든 href를 수집합니다.✓ 복사됨

→ 완전한 링크 인벤토리
각 링크 테스트

각 고유 URL에 대해 HEAD 요청을 보내고 상태 코드를 캡처합니다. 400 이상인 모든 것을 표시합니다.✓ 복사됨

→ 상태 코드와 함께 손상된 링크 목록
손상된 링크를 참조자별로 그룹화

각 손상된 링크에 대해 이를 링크하는 페이지를 나열하므로 어디를 수정해야 하는지 알 수 있습니다.✓ 복사됨

→ 참조자별 손상된 링크 목록, 참조자 수로 정렬

결과: 문서 팀에 전달할 수 있는 마크다운 보고서로, 모든 손상된 링크를 수정해야 할 페이지별로 그룹화합니다.

함정

일부 사이트는 공격적인 크롤러를 속도 제한합니다 — 요청 간에 지연을 추가합니다. 프로덕션에서 실행하는 경우 비피크 시간에 수행합니다

함께 쓰기: filesystem · github

인증이 필요한 데이터 스크래핑

👤 데이터 분석가, 연구원 ⏱ ~20 min advanced

언제 쓸까: 필요한 데이터가 로그인 뒤에 있고(자신의 관리자 대시보드, 내부 보고서 등) 기본 스크래퍼로 접근할 수 없을 때입니다.

사전 조건

대상에 대한 유효한 자격증명 — 서비스 계정을 사용하고 개인 계정을 사용하지 않습니다

흐름

로그인

https://target.example.com/login을 엽니다. 이메일 필드를 [email]으로 채우고 비밀번호를 [password]로 채웁니다. 제출합니다.✓ 복사됨

→ 확인된 세션 — 대시보드 URL에 도착
데이터 페이지로 네비게이션

Reports 섹션을 클릭합니다. 데이터 테이블이 렌더링될 때까지 기다립니다.✓ 복사됨

→ DOM에서 테이블 표시됨
데이터 추출

보고서 테이블의 모든 행을 읽습니다. 각 열을 키로 하는 JSON으로 반환합니다.✓ 복사됨

→ 완전한 데이터 세트를 JSON으로

결과: 간단한 HTTP 스크래퍼로는 얻을 수 없었던 구조화된 데이터로, 스프레드시트나 DB에 드롭할 준비가 되어 있습니다.

함정

MFA가 활성화되어 흐름이 손상됨 — 서비스가 지원하는 경우 앱별 비밀번호를 설정하거나 대신 오래 유지되는 API 토큰을 사용합니다
여러 로그인 후 Captcha가 나타남 — 지속적인 브라우저 컨텍스트(--user-data-dir)를 사용하여 쿠키를 재사용하고 captcha 게이트를 트리거하지 않습니다

함께 쓰기: postgres · filesystem

조합

다른 MCP와 조합해 10배 효율

playwright + filesystem

사이트를 스크래핑하고 각 페이지의 콘텐츠를 디스크에 저장하여 오프라인 RAG를 수행

docs.stripe.com을 /api부터 크롤링하기 시작하고 각 페이지를 ./knowledge/stripe/{path}.md 아래 Markdown 파일로 저장합니다.✓ 복사됨

playwright + chrome-devtools

한 흐름에서 성능 + 기능 테스트 — 페이지가 올바르게 로드되고 빠르게 로드되는지 확인

내 랜딩 페이지를 엽니다. H1을 확인한 다음 Lighthouse 추적을 캡처하고 LCP가 2초 미만인지 알려줍니다.✓ 복사됨

playwright + sentry

사용자 breadcrumb를 재생하여 Sentry에서 보고된 프로덕션 오류 재현

Sentry 문제 WEB-3a91에서는 사용자가 X를 클릭한 후 Y를 클릭한 후 충돌했다고 합니다. Playwright에서 그 정확한 순서를 재현하고 확인합니다.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
browser_navigate	url: str	URL로 네비게이션 — 모든 흐름의 첫 번째 작업	페이지 로드 1회
browser_snapshot		모든 상호작용 요소(링크, 버튼, 입력)의 구조화된 보기 가져오기	무료
browser_click	ref: str (from snapshot) \| selector: str	스냅샷 참조 또는 CSS 선택자로 식별된 요소 클릭	무료
browser_type	ref, text, submit?: bool	입력 필드를 채웁니다. submit:true일 때 Enter 키도 누릅니다	무료
browser_screenshot	fullPage?: bool, path?: str	시각적 증거 캡처 — 디버깅 또는 감사	디스크 공간
browser_evaluate	script: str	페이지 컨텍스트에서 임의의 JS를 실행합니다 — 드물게 사용하고 특정 도구를 선호합니다	무료
browser_network_requests		페이지가 로딩하는 항목을 검사합니다. 숨겨진 API 엔드포인트를 찾는 데 유용합니다	무료

비용 및 제한

운영 비용

API 쿼터: 무료 — 로컬에서 실행되며 머신 리소스만 사용
호출당 토큰: 스냅샷은 페이지 복잡도에 따라 500-3000 토큰
금액: 무료입니다. 브라우저 바이너리는 한 번만 다운로드됩니다(~300MB Chromium).
팁: browser_snapshot을 스크린샷 대신 사용하십시오 — 토큰의 100배 저렴하고 Claude가 작용하기에 더 안정적입니다.

보안

권한, 시크릿, 파급범위

자격 증명 저장: 환경 변수를 통해 전달합니다. 실제 프로덕션 자격증명을 프롬프트에 절대 입력하지 마십시오

데이터 외부 송신: 브라우저는 네비게이션하는 모든 URL에 연결됩니다. Microsoft로의 원격 측정 없음

브라우저 세션이 유지됩니다 — 인증을 테스트하는 경우 실행 간에 쿠키를 지웁니다.
Headed 모드는 머신에서 실제 창을 엽니다. CI의 경우 headless를 사용합니다.

문제 해결

자주 발생하는 오류와 해결

요소를 찾을 수 없음 / TimeoutError

페이지가 렌더링을 완료하지 못했습니다. 작업 전에 명시적 대기를 추가합니다: browser_wait_for(selector) 또는 browser_wait_for(text='...')

확인: 먼저 스냅샷을 캡처하여 실제로 페이지에 있는 내용을 확인합니다

Linux에서 브라우저를 시작하지 못함

OS 종속성을 설치합니다: npx playwright install-deps. Docker에서 흔함 — 공식 Playwright 이미지를 기본으로 사용합니다.

확인: playwright --version

모든 네비게이션이 net::ERR_*로 실패

네트워크 샌드박싱 문제입니다. Docker에 있는 경우 --no-sandbox로 실행하거나 방화벽/프록시를 확인합니다.

사이트가 자동화를 감지하고 captcha 표시

--browser-type=firefox를 사용하십시오(headless Chromium보다 덜 감지됨) 또는 필요한 경우 headed로 실행합니다. 일부 사이트는 의도적으로 봇 방지입니다 — 이를 존중합니다.

대안

Playwright 다른 것과 비교

대안	언제 쓰나	단점/장점
puppeteer MCP	Chromium만 필요하고 약간 더 간단한 API를 원할 때	Chromium만 지원; Firefox/WebKit 없음; 이제 커뮤니티가 더 작음
Firecrawl MCP	콘텐츠만 추출하면 되고 페이지와 상호작용할 필요가 없을 때	호스팅됨(크레딧 비용) 하지만 인프라 없음; 흐름을 클릭할 수 없음
Browserbase MCP	서버리스 컨텍스트에서 브라우저 자동화를 실행해야 할 때(로컬 브라우저 없음)	분당 가격이 있는 호스팅 서비스; 프로덕션 에이전트에 좋음

Playwright

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: Playwright

사전 조건

흐름

함정

흐름

함정

흐름

함정

사전 조건

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

Playwright 다른 것과 비교

더 보기

리소스