클로드에서 플레이라이트 사용법, 브라우저를 대신 눌러줍니다

클로드에게 “이 사이트 로그인해서 주문 내역 캡처해줘”라고 시켰을 때 클로드가 직접 크롬을 열어 그대로 해주는 상태가 됩니다. Playwright MCP를 붙이면 됩니다.

클로드는 기본적으로 브라우저를 조작하지 못합니다. 화면을 볼 수도, 버튼을 누를 수도 없습니다. Playwright MCP는 이 사이를 이어주는 다리입니다. 마이크로소프트가 만든 브라우저 자동화 도구인 Playwright를 클로드가 도구로 쓸 수 있게 열어줍니다.

이 글에서는 Playwright MCP가 정확히 뭘 하는지, Claude Code와 Claude Desktop 각각에 어떻게 설치하는지, 실제로 뭘 시킬 수 있는지, 그리고 처음 붙일 때 자주 막히는 지점을 정리했습니다.

Playwright MCP가 클로드에서 하는 일

MCP는 Model Context Protocol의 약자로, 클로드 같은 AI가 외부 도구를 표준 방식으로 불러 쓰게 하는 규약입니다. Playwright MCP는 그 규약을 따르는 서버 중 하나이고, 안에 Playwright가 들어 있습니다.

클로드에 붙이면 이런 흐름이 생깁니다.

자연어 지시가 클로드와 Playwright MCP를 거쳐 실제 브라우저 조작으로 바뀌고, 그 결과가 스냅샷으로 되돌아옵니다

여기서 핵심은 클로드가 스크린샷 이미지를 보고 좌표를 찍어 누르는 방식이 아니라는 점입니다. Playwright MCP는 페이지의 접근성 트리, 즉 버튼과 입력창에 붙은 역할과 이름 정보를 텍스트로 클로드에 넘깁니다. 클로드는 “로그인 버튼”이라는 이름을 보고 그 요소를 지목하고, Playwright가 실제로 클릭합니다. 비전 모델 없이 동작하기 때문에 빠르고 결과가 잘 흔들리지 않습니다.

준비물은 Node.js 하나

설치 명령이 npx로 시작하기 때문에 Node.js가 필요합니다. LTS 버전을 설치하면 됩니다. 터미널에서 node -v가 버전을 출력하면 준비가 된 것입니다.

브라우저는 따로 받지 않아도 됩니다. Playwright MCP가 처음 실행될 때 크로미움을 자동으로 내려받습니다.

Claude Code에 Playwright MCP 설치하기

Claude Code를 쓴다면 터미널에서 아래 명령을 실행합니다.

claude mcp add playwright npx @playwright/mcp@latest

Playwright MCP 서버를 등록하고 설정을 ~/.claude.json에 저장하는 명령입니다. 다음 Claude Code 세션부터 바로 쓸 수 있습니다.

Playwright 공식 문서의 Claude Code 설치 안내

설정 범위는 뒤에 옵션으로 지정합니다. 기본값은 현재 폴더에서 나만 쓰는 local 범위입니다.

• claude mcp add -s user playwright npx @playwright/mcp@latest : 내 모든 프로젝트에서 사용
• claude mcp add -s project playwright npx @playwright/mcp@latest : .mcp.json에 기록해 팀과 공유하고 git으로 버전 관리

혼자 여러 프로젝트에서 쓸 계획이면 -s user로 한 번만 등록해두는 편이 편합니다.

Claude Desktop에 Playwright MCP 설치하기

Claude Desktop은 설정 파일을 직접 편집합니다. 앱에서 Settings로 들어가 Developer 탭의 Edit config를 열면 claude_desktop_config.json이 열립니다. 파일 위치는 운영체제마다 다릅니다.

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

이 파일에 아래 내용을 넣습니다. 이미 다른 MCP 서버가 있다면 mcpServers 안에 playwright 항목만 추가합니다.

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

Claude Desktop은 설정 파일에 서버 정보를 직접 적어 넣습니다

저장한 뒤 Claude Desktop을 완전히 종료했다가 다시 켜야 반영됩니다.

연결됐는지 확인하기

Claude Code에서는 /mcp를 입력하면 등록된 서버 목록과 상태가 나옵니다. playwright가 connected로 보이면 됩니다. claude mcp list로도 확인할 수 있습니다.

Claude Desktop에서는 입력창 아래 도구 아이콘을 누르면 사용 가능한 도구 목록에 browser_로 시작하는 항목들이 나타납니다.

첫 실행에서 크로미움을 내려받느라 첫 명령이 느릴 수 있습니다. 한 번 받고 나면 이후로는 바로 뜹니다.

실제로 시켜보기

연결이 됐으면 평소처럼 말로 시키면 됩니다. 클로드가 알아서 필요한 도구를 골라 씁니다.

playwright.dev 에 접속해서 첫 화면을 스크린샷으로 저장해줘

이렇게 시키면 클로드는 browser_navigate로 주소를 열고, browser_take_screenshot으로 이미지를 저장합니다.

조금 더 실용적인 예를 들면 이렇습니다.

우리 스테이징 사이트 로그인 페이지에 들어가서
아이디 test@example.com, 비밀번호는 클립보드에 있는 값으로 로그인하고
대시보드가 뜨는지 확인한 다음, 이 과정을 Playwright 테스트 코드로 만들어줘

클로드는 페이지를 열고 접근성 스냅샷으로 입력창을 찾은 뒤 browser_type과 browser_click으로 로그인을 진행하고, 대시보드 요소가 보이는지 스냅샷으로 확인합니다. 마지막으로 방금 실행한 동작을 @playwright/test 형식의 .spec.ts 파일로 정리해줍니다. 직접 셀렉터를 찾아 적는 수고 없이 실제로 눌러본 경로 그대로 테스트가 나옵니다.

버그 재현에도 씁니다. “이 URL 열어서 결제 버튼 누르고 콘솔에 뭐가 찍히는지 알려줘”라고 하면 browser_console_messages와 browser_network_requests로 에러 로그와 실패한 요청을 가져와 보여줍니다.

Playwright MCP가 클로드에 쥐여주는 도구들

설치하면 기본으로 켜지는 도구는 20개가 조금 넘습니다. 이동, 클릭, 입력, 폼 채우기, 스냅샷, 스크린샷, 콘솔과 네트워크 로그 조회, 탭 관리 정도가 항상 활성화됩니다.

설치만 하면 켜지는 기본 도구들. 테스트 코드 생성이나 트레이스 기록 같은 기능은 옵션으로 추가한다

테스트 단언문 생성이나 트레이스 기록, PDF 저장처럼 특수한 기능은 기본에서 빠져 있고, 설정에서 --caps 옵션으로 켭니다. 예를 들어 테스트 코드를 자주 만든다면 --caps testing을 붙입니다. 도구 수가 적을수록 클로드가 덜 헷갈리고 토큰도 아끼기 때문에 필요한 것만 켜는 구조입니다.

자주 막히는 지점

공식 패키지가 두 개처럼 보입니다. 검색하면 @executeautomation/playwright-mcp-server가 같이 나오는데, 이건 커뮤니티 프로젝트입니다. 마이크로소프트 공식 패키지는 @playwright/mcp입니다. 문서와 도구 이름이 다르니 처음엔 공식 쪽으로 맞추는 편이 낫습니다.

로그인이 매번 풀립니다. Playwright MCP는 기본적으로 지속 프로필을 써서 쿠키와 로그인 상태를 로컬에 저장합니다. 한 번 로그인해두면 다음 세션에도 유지됩니다. 반대로 매번 깨끗한 상태로 시작하고 싶으면 설정 args에 --isolated를 넣습니다. 저장해둔 로그인 상태 파일을 쓰려면 --storage-state=경로를 함께 지정합니다.

브라우저 창이 뜨는 게 거슬립니다. 기본값은 실제 창을 띄우는 모드입니다. 클로드가 뭘 하는지 눈으로 보여서 처음엔 유용하지만, 창을 안 띄우려면 args에 --headless를 추가합니다.

긴 작업에서 토큰이 빠르게 줍니다. 스냅샷 하나가 페이지 구조 전체를 텍스트로 담기 때문에, 요소가 많은 페이지를 여러 번 오가면 컨텍스트가 금방 찹니다. 페이지를 옮길 때마다 스냅샷을 다시 받으므로, 한 번에 시킬 일을 명확히 좁혀서 지시하는 편이 좋습니다.

Node 버전이 낮으면 npx가 실패합니다. @playwright/mcp는 최신 Node LTS를 기준으로 합니다. 설치는 됐는데 서버가 failed로 뜨면 node -v부터 확인합니다.

정리

Claude Code는 claude mcp add playwright npx @playwright/mcp@latest 한 줄, Claude Desktop은 설정 파일에 서버 항목 하나면 클로드가 브라우저를 직접 조작하게 됩니다. 접근성 트리 기반이라 스크린샷을 읽어 좌표를 찍는 방식보다 빠르고 안정적이며, 눌러본 경로를 그대로 Playwright 테스트로 뽑아내는 게 가장 잘 맞는 용도입니다.

더 깊은 설정과 도구 전체 목록은 Playwright MCP 공식 문서와 GitHub 저장소에 있습니다.

자주 묻는 질문

Playwright MCP를 쓰려면 Playwright를 따로 설치해야 하나요. 아니요. @playwright/mcp 패키지 안에 Playwright가 들어 있고, 브라우저는 첫 실행 때 자동으로 내려받습니다. 프로젝트에 Playwright가 이미 있어도 상관없습니다.

Claude Code와 Claude Desktop에 동시에 붙일 수 있나요. 됩니다. 둘은 설정 위치만 다르고 같은 서버를 씁니다. 다만 두 쪽에서 동시에 브라우저를 조작하면 프로필이 충돌할 수 있으니 한 번에 한 곳에서 쓰는 게 안전합니다.

로그인이 필요한 사이트도 자동화되나요. 기본 지속 프로필을 쓰면 한 번 로그인한 상태가 유지되므로 이후 자동화가 됩니다. 2단계 인증이 걸린 사이트는 처음 한 번 창이 뜬 상태에서 직접 로그인해주면 됩니다.

ChatGPT나 다른 AI에서도 되나요. Playwright MCP는 MCP를 지원하는 클라이언트면 다 붙습니다. VS Code, Cursor, Windsurf 등에서도 같은 방식으로 씁니다. 클라이언트별 설정 방법은 공식 문서의 Client Setup 항목에 정리돼 있습니다.