playwright

무엇을 하는 도구인가

Playwright MCP는 Playwright로 브라우저를 조작하는 MCP 서버입니다. README는 픽셀 기반 입력이 아니라 접근성 트리를 쓴다고 설명합니다. 기본 방식에서는 browser_snapshot으로 페이지를 구조화된 텍스트로 읽고, 그 안의 요소 참조로 클릭하거나 입력합니다. 그래서 비전 모델이 없어도 동작합니다.

스크린샷(browser_take_screenshot)도 있지만 README는 스크린샷을 보고 동작할 수는 없다고 밝힙니다. 동작은 스냅샷 기준입니다.

설치

공식 마켓플레이스에 playwright 플러그인이 있고, 이 플러그인은 .mcp.json에서 npx로 @playwright/mcp@latest를 실행하게 구성돼 있습니다. 플러그인 없이 MCP 서버만 직접 등록할 수도 있습니다. Node.js 18 이상이 필요합니다.

# 플러그인으로
/plugin install playwright@claude-plugins-official

# MCP 서버로 직접
claude mcp add playwright npx @playwright/mcp@latest

쓰는 방법

• "localhost:3000을 열어서 로그인 화면이 정상인지 확인해줘"처럼 대상과 확인할 것을 말합니다.
• 폭이 다른 화면을 보려면 창 크기를 지정해서 열라고 요청합니다. 도구 목록에 browser_resize가 있습니다.
• 콘솔 오류와 네트워크 요청도 읽을 수 있습니다(browser_console_messages, browser_network_requests).
• 브라우저는 기본이 창이 보이는 모드입니다. 창 없이 돌리려면 서버 옵션에 --headless를 줍니다.
• --browser로 chrome, firefox, webkit, msedge를 고르고, --isolated를 쓰면 프로필을 메모리에만 두어 닫을 때 상태가 사라집니다.

쓰지 말아야 할 때와 안전

• README는 처리량이 높은 코딩 에이전트에는 Playwright CLI와 스킬 조합을 권합니다. MCP는 도구 정의와 접근성 트리 때문에 컨텍스트를 더 씁니다.
• MCP 방식은 탐색적 자동화, 자가 복구 테스트, 브라우저 상태가 유지되어야 하는 긴 작업에 맞습니다.
• README는 이 서버가 보안 경계가 아니라고 명시합니다. 로그인된 프로필로 돌리면 그 계정으로 행동합니다. 신뢰할 수 없는 사이트를 열 때는 --isolated나 --allowed-hosts, --blocked-origins를 고려하세요.
• 영구 프로필은 브라우저 인스턴스 하나만 쓸 수 있어, 병렬 사용 시 --isolated나 별도 --user-data-dir가 필요합니다.

실제 예시

http://localhost:3000 을 1280px 폭과 390px 폭으로 각각 열어서 전체 화면을 캡처하고, 깨진 곳이 있는지 알려줘.

/pricing 페이지를 열고 콘솔 오류와 실패한 네트워크 요청을 알려줘.

흔한 실수와 쓰지 말아야 할 때

• npx로 서버를 띄우므로 Node 18 미만이거나 네트워크가 막혀 있으면 서버가 시작되지 않습니다. /mcp에서 연결 상태를 확인하세요.
• 로그인이 필요한 페이지를 영구 프로필로 열면 내 계정으로 동작합니다. 시험용 계정을 쓰세요.
• 열려 있는 페이지의 내용은 모두 컨텍스트에 들어갑니다. 아주 긴 페이지는 비용이 커지니 확인할 영역을 지정하세요.
• 이 도구는 화면을 사람 눈처럼 판단하지 않습니다. 디자인의 좋고 나쁨은 직접 보고 판단해야 합니다.

자주 묻는 질문