Playwright MCP: 실전 심층 가이드 (2026)

중급

Microsoft의 playwright-mcp은 GitHub 스타 약 35k에 이르며 — 커뮤니티가 관리하는 MCP 레지스트리 기준으로 — 현재 지구상에서 가장 많이 설치된 MCP 서버로, 공식 GitHub MCP와 Figma MCP 서버보다도 앞서 있습니다. Claude Code, Cursor, Codex, Windsurf, Claude Desktop 중 어느 하나라도 사용하며 에이전트에게 "사이트 확인해봐" 또는 "저 대시보드에서 데이터 가져와"라고 시켜본 적이 있다면, 실제로 그 일을 하는 도구가 바로 이것입니다.

이에 관한 거의 모든 가이드는 두 줄짜리 설치 방법에서 멈춥니다. 이 페이지는 그 이후에 중요한 부분입니다: 이 도구가 내부에서 실제로 하고 있는 일, 사람들이 존재하는 줄 모르는 모드들, 그리고 2주차쯤 나타나는 날카로운 모서리들 — 토큰 비용, 보안, 브라우저 프로파일 잠금.

What you'll learn

접근성 스냅샷 모드(기본값)가 비전보다 빠를 뿐만 아니라, LLM이 결정론적으로 다루는 다른 자동화 패러다임인 이유 이해하기
세 가지 프로파일 모드 — 영구, 격리, 브라우저 확장 — 를 알고 각각이 올바른 선택인 시점 파악하기
--caps로 옵트인 기능 팩(network, storage, devtools, vision, pdf, testing)을 켜고 왜 기본적으로 꺼져 있는지 이해하기
Claude Code 세션에서 Playwright MCP의 실제 토큰 비용을 확인하고 Playwright-as-a-Skill이 이기는 시점 알기
Playwright MCP를 독립 HTTP/SSE 서버로, Docker에서, 그리고 자율 실행을 위해 안전하게 배포하기 (시크릿 마스킹은 편의 기능이지 경계가 아니다)

이 서버가 생태계를 삼킨 이유

Playwright MCP는 "LLM에 브라우저를 주자"의 참조 구현체이며, 옳다고 판명된 두 가지 설계 결정을 했습니다:

구조화된 접근성 스냅샷을 주요 인터페이스로 사용 — 스크린샷이 아닙니다. 모델은 요소들(역할, 이름, 참조)의 간결하고 결정론적인 트리를 얻습니다. 비전 모델이 필요 없고, 좌표 환각도 없으며, 토큰은 픽셀 대신 구조에 사용됩니다.
Playwright의 실제 자동화 엔진을 아래에 배치 — 동일한 대기, 동일한 자동 실행 가능성 확인, 여러 해에 걸쳐 프로덕션 QA로 다져진 동일한 로케이터 시스템. 새로 만든 것이 아무것도 없습니다.

결과: 새로 설치하면 탐색, 폼 입력, 탭, 스냅샷, 스크린샷, 콘솔 접근, 네트워크 검사, 그리고 몇 가지 옵트인 카테고리에 걸쳐 대략 50개 이상의 도구를 얻습니다. 상당한 표면적입니다 — 이는 바로 사람들을 놀라게 하는 첫 번째 지점으로 이어집니다.

실제로 실행 중인 모드

기본적으로 MCP 서버는 접근성 스냅샷 모드로 실행됩니다. 에이전트가 browser_snapshot을 호출하면, 스크린샷이 아니라 YAML과 같은 트리를 얻습니다:

- Page URL: https://example.com/login
- role: main
  - role: form
    - role: textbox, name: "Email", ref: e12
    - role: textbox, name: "Password", ref: e13
    - role: button, name: "Sign in", ref: e14

에이전트는 그런 다음 browser_click({ ref: "e14" })를 호출합니다 — 지어낸 CSS 셀렉터도, 추측한 좌표도 없습니다. ref는 서버가 내부 Playwright 로케이터에서 발행한 핸들이므로, 클릭은 손으로 작성한 page.getByRole('button', { name: 'Sign in' }).click()만큼 신뢰할 수 있습니다.

이것이 LLM이 작성한 Selenium/Puppeteer 스크립트를 접한 사람들이 "AI의 브라우저 사용은 망가졌다"고 생각하는 이유입니다 — 그들은 모델에 원시 HTML이나 스크린샷을 먹이고 있었습니다. 스냅샷 모드에는 그러한 실패 모드가 없습니다. 모델이 잘못 볼 수 있는 셀렉터를 절대 보지 않기 때문입니다.

Pro tip

에이전트가 CSS 셀렉터를 추측하고 있다면, 거의 확실히 다른 브라우저 MCP를 사용 중이거나 스냅샷을 비활성화한 것입니다.
스냅샷은 페이지 범위입니다. iframe의 경우, iframe 내부에서 browser_snapshot을 명시적으로 호출하세요; 도구는 iframe 탐색을 노출합니다.
Ref는 일시적입니다. 다음 페이지 변경 전까지만 유효합니다 — React fiber ID처럼 다루세요.

옵트인 기능 팩 (--caps)

지루하고 안전한 도구만 활성화된 채로 배포됩니다. 강력한 것들은 --caps 플래그 뒤에 살고 있으며 서버별로 켭니다:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--caps=network,storage,pdf"]
    }
  }
}

캡	활성화되는 기능	기본적으로 꺼져 있는 이유
`network`	요청 모킹, 오프라인 설정, 라우트 가로채기	트래픽을 조용히 다시 쓸 수 있음; 의도 필요
`storage`	쿠키, localStorage, sessionStorage 읽기/쓰기	켜지면 같은 출처 데이터 절도가 사소해짐
`devtools`	트레이싱, 비디오 녹화, 요소 강조	매우 큰 아티팩트, 디스크 비용
`vision`	픽셀 좌표 마우스 동작	결정론적 모델을 우회 — 아래 참조
`pdf`	현재 페이지를 PDF로 저장	문제없음, 대부분의 세션에서는 잡음일 뿐
`testing`	요소/텍스트/값 검증, 로케이터 생성	테스트 작성 틈새, 약 10여 개 도구 추가
`config`	확인된 서버 구성 되읽기	디버그 전용

자명하지 않은 것은 vision입니다. 이것을 켜면 모델에 browser_mouse_move_at_coordinates와 그 친구들을 제공합니다. 또한 전체 세션의 실패 프로파일을 조용히 바꿉니다. 스냅샷이 불편할 때 에이전트가 좌표 클릭으로 되돌아가기 때문입니다 — 이제 언어 모델이 픽셀 계산을 하며 구동하는 브라우저를 갖게 됩니다. canvas 요소나 접근성이 깨진 위젯이 강제할 때만 활성화하세요.

세 가지 프로파일 모드

여기가 흥미로운 설계가 살고 있는 곳입니다.

Guided walkthrough1 of 3

서버는 워크스페이스별 사용자 데이터 디렉토리(작업 폴더 해시에서 파생된 경로)에 대해 Chromium을 실행합니다. 쿠키, localStorage, 저장된 비밀번호, 이력이 세션 간에 유지됩니다. 인증된 대시보드에 훌륭합니다. 날카로운 모서리: 한 번에 하나의 인스턴스만 프로파일을 보유할 수 있습니다 — 같은 폴더에 대한 두 번째 Claude Code 창은 오류가 발생합니다. --user-data-dir을 공유 위치로 지정하면 프로젝트 간에 상태를 공유할 수 있습니다.

설치: 실제로 원하는 네 가지 구성

표준 로컬 (Claude Desktop / Claude Code / Cursor)

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

격리 + 사전 로드된 인증 (CI 스러운, 재현 가능)

{
"mcpServers": {
  "playwright": {
    "command": "npx",
    "args": [
      "@playwright/mcp@latest",
      "--isolated",
      "--storage-state", "/Users/me/.auth/github.json",
      "--caps=network"
    ]
  }
}
}

내 실제 Chrome 탭에 연결 (브라우저 확장)

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

독립 HTTP 서버 (많은 에이전트 간에 하나의 브라우저 공유)

# One-time on your workstation:
npx @playwright/mcp@latest --port 8931

# Then every client points at it:
{
"mcpServers": {
  "playwright": { "url": "http://localhost:8931/mcp" }
}
}

HTTP 모드는 사람들이 놓치는 것입니다. 동일한 머신에서 네 개의 코딩 에이전트를 실행하면, Playwright MCP의 네 개의 개별 npx 설치가 각각 자체 Chromium을 실행합니다. 하나의 공유 HTTP 서버는 단일 브라우저 풀을 유지하며, 이는 더 저렴하고 관찰하기 쉽습니다.

Docker: 유일하게 지원되는 "헤드리스 서버" 레시피

# One-shot (stdio):
docker run -i --rm --init --pull=always mcr.microsoft.com/playwright/mcp

# Long-lived HTTP server on port 8931:
docker run -d -i --rm --init --pull=always \
  --entrypoint node \
  -p 8931:8931 \
  mcr.microsoft.com/playwright/mcp \
  /app/cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0

문서에서 묻어두는 두 가지: Docker 이미지는 헤드리스 Chromium 전용입니다(Firefox 없음, WebKit 없음, headed 모드 없음), 그리고 컨테이너 내부에서 --no-sandbox가 필수입니다. Firefox나 실제 GPU가 필요하다면 호스트에서 서버를 실행하세요.

토큰 비용 싸움: MCP vs Skill vs 원시 CLI

아무도 경고하지 않는 또 다른 것: Playwright MCP는 Claude Code에 붙일 수 있는 가장 무거운 단일 서버로, 세션당 도구 스키마 오버헤드가 약 3,500 토큰입니다 — 단 한 번의 호출도 하기 전에. 그 숫자는 전체 대화 동안 컨텍스트 창에 살아 있습니다.

커뮤니티의 보고된 측정치(아래 링크)는 일반적인 "이 사이트 테스트하기" 작업을 다음과 같이 집계합니다:

접근 방식	작업에 대한 토큰	Sonnet 비용 (대략)
Playwright MCP (기본 캡)	~114k	~$0.34
Playwright CLI + Skill 파일	~27k	~$0.08

Skill 접근 방식은 Playwright의 CLI를 문서화하고 에이전트가 bash로 셸 아웃하게 하는 작은 SKILL.md를 제공합니다. 도구 스키마는 필요할 때까지 모델의 컨텍스트에서 빠져 있고, 스킬 파일 자체는 한 번만 읽힙니다. 최근 Playwright MCP 버전은 모든 호출마다 전체 페이지 상태를 스트리밍하지 않도록 하여 이 격차를 좁혔지만, 스키마 오버헤드는 여전히 스키마 오버헤드입니다.

경험 법칙: 모델이 DOM과 대화형으로 주고받아야 하는 대화형/탐색적 작업에는 MCP. 반복 가능한 작업 — URL 목록 스크린샷, 테스트 스위트 실행, 크론에 넣을 만한 것들 — 에는 Skill/CLI.

자신의 세션에서 이를 측정하는 방법은 Claude Code 페이지 MCP 토큰 비용을 참조하세요.

시크릿 마스킹은 편의 기능이지 경계가 아니다

Playwright MCP는 구성에서 secrets 맵을 지원합니다:

{
  "secrets": {
    "OPENAI_API_KEY": "sk-real-key-here",
    "GITHUB_TOKEN": "ghp_real"
  }
}

서버가 도구 응답 내에서 그 정확한 문자열을 볼 때, 결과를 모델에 전달하기 전에 키 이름을 다시 치환합니다. 이것은 정말로 유용합니다 — API 키를 그대로 반향하는 페이지 콘텐츠는 더 이상 LLM 트랜스크립트에 그것을 유출하지 않습니다.

그러나 프로젝트 README는 명시적이며 여러 번 반복합니다: "Playwright MCP는 보안 경계가 아니다." 구체적으로:

페이지는 시크릿을 title 속성 또는 base64로 렌더링할 수 있으며 마스커는 이를 잡지 못할 것입니다.
모델이 브라우저에게 요청하는 모든 것 — 폼 필드 트릭을 통한 document.cookie 읽기 포함 — 은 여전히 실제 프로파일의 권한으로 실행됩니다.
확장 모드는 일상적인 Chrome에 연결됩니다. 로그인된 모든 탭이 원칙적으로 도달 가능해집니다.

Playwright MCP + 영구 프로파일을 가진 에이전트는 관리자 쿠키를 가진 새로운 직원과 동일하게 취급하세요: 좁고 감독된 작업에는 좋지만, --dangerously-skip-permissions에서는 재앙적입니다. 더 넓은 위협 모델은 에이전트 브라우저와 같은 출처 신뢰와 에이전트가 업로드하는 것을 참조하세요.

최근 변경 사항

최근 릴리스(v0.0.79 라인)는 기본값을 변경하므로 알아둘 가치가 있습니다:

--timeout-settle — 이제 서버는 각 동작 후 트리거된 작업이 안정될 때까지 반환 전에 구성 가능한 ms 수(기본 500)를 기다립니다. 느린 SPA의 경우 올리고, perf 테스트의 경우 낮추세요.
WebP 스크린샷 — browser_take_screenshot은 type: "png" | "jpeg" | "webp"를 받아들이고 파일명에서 추론합니다. WebP는 같은 품질에서 PNG보다 약 30–50% 작으며, 스크린샷을 많이 찍는다면 변경할 가치가 있습니다.
Python / Java / C#용 Codegen 출력 — testing 캡은 이제 TypeScript 이상으로 테스트 스켈레톤을 방출할 수 있습니다.
다운로드 이벤트 감지 — 이전 오류 기반 추론을 대체합니다; 다운로드는 이제 실제 이벤트를 트리거하므로 에이전트가 그것들을 기다릴 수 있습니다.
브라우저 확장 CDP 릴레이 — WebSocket 업그레이드에서 헤더 검증으로 강화됨.

디버깅 플레이북

Guided walkthrough1 of 5

스냅샷이 오래되었습니다. 모든 탐색 또는 폼 제출 후 에이전트가 browser_snapshot을 다시 호출하게 하세요 — 이전 스냅샷의 ref는 죽었습니다. 여전히 요소를 찾을 수 없다면, 버튼이 iframe 또는 Shadow DOM 내부에 있을 수 있습니다; 스냅샷 범위를 확장하세요.

명확히 구분해야 할 관련 개념

아직 카드가 없습니다 — 추가해서 학습을 시작하세요. 🃏

빠른 확인

Check yourself

0/5

기본적으로, 에이전트가 browser_click을 호출할 때 무엇이 대상 요소를 식별합니까?
같은 저장소에 대해 두 개의 Claude Code 창을 원하고, 둘 다 로그인된 프로파일로 Playwright MCP를 사용합니다. 올바른 조치는?
어떤 --caps 값이 세션의 안전 프로파일을 가장 많이 변경합니까?
반복 가능한 배치 작업(밤마다 200개 URL 스크린샷)의 경우, 일반적으로 어떤 도구가 올바릅니까?
GITHUB_TOKEN=ghp_xxx로 시크릿 맵을 구성합니다. 페이지에 base64로 인코딩된 토큰이 숨겨진 필드에 포함되어 있습니다. 무슨 일이 일어납니까?

Playwright MCP가 잘못된 도구일 때

진행 중인 사람 브라우징 세션과 공유된 로그인이 필요합니다. 로그인을 상속하는 브라우저 에이전트에서 다룬 것과 같은 공유 로그인 에이전트 브라우저를 고려하세요 — Playwright MCP의 확장 모드는 가깝게 접근하지만, 승인과 Spaces 주변의 UX가 다릅니다.
프로덕션 코드 경로를 테스트하고 실제 Playwright 테스트 러너를 원합니다. @playwright/test를 직접 사용하세요; MCP는 에이전트 탐색용으로 최적화되어 있지, CI 테스트 작성용이 아닙니다.
워크로드가 100% 정적 HTML의 헤드리스 스크래핑입니다. 단순한 fetch + 파서가 수 배 저렴합니다. 브라우저는 실제로 JavaScript 실행이 필요한 페이지를 위해 남겨두세요.
어떤 브라우저 상태 유출도 감수할 수 없습니다. 실행마다 새로운 --storage-state 스냅샷으로 --isolated를 사용하세요. 일상 Chrome에 대해 확장 모드를 사용하지 마세요.

출처 및 추가 자료

microsoft/playwright-mcp — 표준 저장소, README, 위에 인용된 버전 번호에 대한 릴리스 노트.
microsoft/playwright-mcp/releases — WebP 스크린샷 지원, --timeout-settle, 확장 CDP 강화.
Claude Code에서의 MCP 서버 토큰 비용 — ~3,500 토큰 오버헤드 수치와 도구별 숫자의 출처.
Playwright CLI vs Playwright MCP — 4× Skill 대 MCP 비용 차이 뒤의 커뮤니티 벤치마크.
관련 AILmanac 페이지: Claude Code MCP 토큰 비용 · MCP: 무상태 모드 · 에이전트 스킬 검증 · 에이전트 브라우저와 같은 출처 신뢰.

이 서버가 생태계를 삼킨 이유​

실제로 실행 중인 모드​

옵트인 기능 팩 (--caps)​

세 가지 프로파일 모드​

설치: 실제로 원하는 네 가지 구성​

표준 로컬 (Claude Desktop / Claude Code / Cursor)

격리 + 사전 로드된 인증 (CI 스러운, 재현 가능)

내 실제 Chrome 탭에 연결 (브라우저 확장)

독립 HTTP 서버 (많은 에이전트 간에 하나의 브라우저 공유)

Docker: 유일하게 지원되는 "헤드리스 서버" 레시피​

토큰 비용 싸움: MCP vs Skill vs 원시 CLI​

시크릿 마스킹은 편의 기능이지 경계가 아니다​

최근 변경 사항​

디버깅 플레이북​

명확히 구분해야 할 관련 개념​

빠른 확인​