Playwright MCP - Claude Code가 직접 브라우저를 다루게 만들기

Claude Code 플러그인 큐레이션 시리즈 · 6편 Playwright

이 글에서 다루는 내용

Microsoft 공식 Playwright MCP 서버를 Claude Code에 연결하면, 자연어로 페이지 이동·폼 입력·스크린샷·E2E 테스트까지 지시할 수 있게 됩니다. 비전 모델이 화면을 "보는" 방식이 아니라 접근성 스냅샷(accessibility snapshot)을 받아 구조 기반으로 동작하기 때문에 정확하고 빠른 게 특징입니다. 이 글은 한 줄 설치 명령, 핵심 도구 카테고리, 활용 시나리오, 비공식 executeautomation 변종과의 차이까지 정리합니다. 기준 시점은 2026년 4월입니다.

---

1. Playwright MCP의 자리

Playwright는 Microsoft가 만든 크로스 브라우저 자동화 라이브러리입니다. 그 자체로도 E2E 테스트의 사실상 표준 중 하나로 자리잡았는데, MCP(Model Context Protocol) 서버 형태로 감싸 놓은 것이 Playwright MCP입니다. Claude Code, Cursor, Claude Desktop, Windsurf 등 MCP 클라이언트 어디에서든 동일하게 동작합니다.

다른 브라우저 자동화 도구와 갈리는 결정적 차이는 비전 없이 접근성 트리로 동작한다는 점입니다. Claude가 페이지를 "본다"는 건 사실 화면 캡처를 받는 게 아니라 DOM의 의미 구조를 받아서 추론한다는 뜻입니다. 그래서 더 빠르고, 토큰을 적게 쓰고, 결과가 일관됩니다.

---

2. 설치 - 한 줄

2-1. claude mcp add 명령 한 줄

Claude Code 세션 시작 전에 터미널에서 다음 명령을 한 번 실행합니다.

> claude mcp add playwright npx @playwright/mcp@latest

이 명령은 Playwright MCP 서버 등록을 ~/.claude.json에 영구 저장합니다. 이후 Claude Code 세션을 열면 자동으로 활성화됩니다.

2-2. 등록 확인

세션 안에서 /mcp를 입력하면 등록된 MCP 서버 목록에 playwright가 보여야 합니다. 그 자리에서 간단한 자연어 명령을 던져 동작을 확인합니다.

> example.com 으로 이동해서 페이지 제목을 알려줘.

ℹ️ 처음 실행 시 Playwright가 헤드리스 브라우저(Chromium 기본)를 자동으로 다운로드합니다. 한 번만 받아 두면 이후엔 즉시 동작합니다.

---

3. 제공 도구 카테고리

Playwright MCP가 노출하는 도구는 자연어로 자동 호출되므로 외울 필요는 없습니다. 다만 어떤 동작이 가능한지 알아 두면 프롬프트 설계가 쉬워집니다.

카테고리	대표 동작
탐색	URL 이동, 뒤로/앞으로, 새로고침
상호작용	클릭, 텍스트 입력, 폼 채우기, 드롭다운 선택
관찰	페이지 스냅샷, 특정 요소 스크린샷, 텍스트 추출
키보드·마우스	키 입력, 호버, 드래그·드롭
대기	요소 등장 대기, 네트워크 idle 대기, 시간 지연

---

4. 활용 시나리오 네 가지

4-1. E2E 테스트 자연어로 작성하고 바로 실행

> localhost:3000 의 회원가입 흐름을 검증하는 E2E 테스트를 만들어줘. 이메일·비밀번호 입력 → 가입 버튼 → 환영 페이지 노출까지 검증하고 실제로 한 번 돌려서 통과하는지도 확인해줘.

Claude가 Playwright 테스트 코드를 작성한 뒤, 같은 MCP를 통해 실제 브라우저로 한 번 돌려 결과를 보고합니다. 사람이 코드 작성 → 저장 → 실행을 따로 할 필요가 없습니다.

4-2. 회귀 테스트 - 시각 변경 점검

> 메인 페이지·상품 상세·결제 화면을 라이트/다크 모드별로 캡처해줘. 어제 캡처한 baseline과 다른 점만 표로 정리.

스크린샷 비교는 Playwright의 강한 분야입니다. 실제 디자인 시스템 변경 PR을 머지하기 전에 한 번 돌려 두면 회귀를 빠르게 잡을 수 있습니다.

4-3. 데이터 수집 / 폼 자동 입력

로그인이 필요한 어드민 페이지에서 같은 작업을 반복해야 한다면 자연어로 위임할 수 있습니다.

> 어드민에 로그인하고, "주문" 메뉴에서 어제 등록된 모든 주문의 주문번호·상태·금액을 표로 뽑아줘. 자격증명은 .env 의 ADMIN_USER/ADMIN_PASS.

4-4. 디자이너·기획자도 직접 쓸 수 있는 영역

"내가 만든 디자인이 실제 화면에서 어떻게 보이는지" 확인을 자연어로 시킬 수 있는 게 큰 가치입니다. 모바일 폭으로 페이지를 열어 보고, 특정 컴포넌트가 깨지는 시점을 잡아 달라고 부탁하는 식의 활용이 자연스럽습니다.

---

5. 비공식 변종 - executeautomation과의 차이

커뮤니티에 @executeautomation/playwright-mcp-server라는 비공식 Playwright MCP가 별도로 존재합니다. 같은 영역의 도구지만 차이가 있습니다.

관점	@playwright/mcp (Microsoft 공식)	@executeautomation/playwright-mcp-server (커뮤니티)
메인 동작 방식	접근성 스냅샷 기반	스크린샷·셀렉터 기반
유지·관리	Microsoft 공식	커뮤니티 메인테이너
권장 사용처	대부분의 일반 케이스	공식이 안 되는 특정 워크플로우

특별한 이유가 없다면 Microsoft 공식 패키지를 추천합니다. 이름이 비슷해서 헷갈리기 쉬운 부분이라 설치 명령을 그대로 복사할 때 패키지명을 한 번 더 확인하는 편이 좋습니다.

---

트러블슈팅

문제 1: 첫 실행에서 멈춘다

Playwright가 브라우저 바이너리를 자동 다운로드하는 단계에서 시간이 걸립니다. 네트워크가 느린 환경이라면 1~2분 정도 걸릴 수 있고, 한 번 받으면 이후엔 즉시 시작됩니다. 기업 프록시 환경이라면 사전에 npx playwright install chromium으로 미리 받아 두는 편이 안전합니다.

문제 2: 로그인이 필요한 페이지에서 동작이 끊긴다

매 호출마다 새 컨텍스트로 시작하므로 세션 쿠키가 유지되지 않을 수 있습니다. 로그인 흐름을 자연어로 위임하거나, Playwright의 storageState 기능으로 인증 상태를 파일에 저장해 두고 재사용하면 안정적입니다.

문제 3: 셀렉터를 못 찾는다

요소가 동적으로 렌더링되는 경우입니다. "요소가 보일 때까지 대기"를 자연어로 명시하면 Playwright가 적절한 wait 함수를 자동으로 추가합니다. data-testid 같은 안정 속성을 두면 더 견고해집니다.

문제 4: 다른 MCP 서버와 충돌하는 듯하다

여러 MCP를 동시에 등록한 경우 같은 포트나 같은 도구명을 두고 충돌할 수 있습니다. /mcp로 등록 목록을 확인하고, ~/.claude.json의 MCP 정의를 직접 점검합니다.

---

마무리

Playwright MCP의 진짜 가치는 Claude Code의 능력을 화면 너머로 확장한다는 점입니다. 코드를 작성하는 것에서 그치지 않고 그 코드가 만든 화면을 직접 확인하고, 결과를 다시 코드 수정에 반영하는 사이클이 한 자리에서 돕니다. E2E 테스트가 필요한 환경이라면 도입 우선순위가 가장 높은 도구 중 하나이고, QA·기획자 역할까지 닿는 영역이라 팀 도입 시 영향이 큰 도구이기도 합니다.

이번 6편으로 시리즈가 한 바퀴 마무리됩니다. 카테고리별로 한 가지씩 추렸지만 본인 환경에 가장 잘 맞는 두세 개만 골라 쓰는 게 핵심입니다. 자세한 조합 가이드는 시리즈 인덱스의 4번 항목을 참고하시면 됩니다.

 

• Playwright MCP 공식 GitHub: github.com/microsoft/playwright-mcp
• Playwright 공식 문서: playwright.dev/docs/getting-started-mcp
• Anthropic 공식 플러그인 페이지: claude.com/plugins/playwright
• 이전 편: 5편 Claude-Mem
• 시리즈 인덱스로: Claude Code 플러그인 큐레이션 시리즈