개발자를 위한 MCP 추천(3) - Playwright MCP 설치 및 사용방법(claude desktop, claude code, gemini cli)

안녕하세요! 갓대희 입니다. :- )

오늘은 이전 개발자를 위한 MCP 들을 소개하는글에 이어 계속 이어 나가려 한다.

3번째 글인  "Playwirght MCP"에 대해 쓰려고 한다. 

 

AI가 브라우저를 직접 조작하는 시대
Playwright MCP는 LLM이 자연어 명령으로 실제 브라우저를 제어할 수 있게 해주는 도구이다.
스크린샷 대신 접근성 트리를 사용하여 빠르고 정확한 웹 자동화를 구현한다.

웹 개발을 하다 보면 반복적인 테스트 작업에 지쳐본 경험이 다들 있을 것이다.
"이 작업을 AI가 대신 해줄 수 없을까?"라는 생각을 해본 적이 있다면, Playwright MCP가 바로 그 답이 될 수 있다. Playwright MCP는 AI가 실제 브라우저를 직접 조작할 수 있게 해주는 도구이다.
개발자가 자연어로 "이 사이트에 가서 로그인하고 데이터를 확인해줘"라고 말하면, AI가 실제로 브라우저를 열어서 그 작업을 수행한다.

 

Playwright MCP란?

간단히 말하면, AI가 Playwright를 직접 제어할 수 있게 해주는 브릿지 역할을 하는 서버다.

기존에는 테스트 스크립트를 직접 작성해야 했다면, 이제는 Claude에게 "네이버에 가서 '맛집'을 검색해줘"라고 자연어로 요청하면 실제로 브라우저에서 그 동작을 수행해준다.

 

설치 방법 🛠️

필수 조건

📋 시스템 요구사항

• Node.js 18 이상
• MCP 호환 클라이언트 : Claude Desktop, Cursor, Windsurf, VS Code, Zed 등

Claude Desktop 설정

 - Claude Desktop 설정 파일을 열어 보자.

 

 - 설정 파일 편집

// claude_desktop_config.json

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

 

  - Claude Desktop 재시작 > Claude Desktop을 완전히 종료하고 다시 실행하면 Playwright MCP가 연결된다.

 

Cursor 설정

 - Cursor Settings > Tools & Integrations > New MCP Server

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

 

Claude Code CLI

 - 설치하기 ( 해당 Local 프로젝트에만 설치 )

# macOS/Linux

claude mcp add playwright -- cmd /c npx -y @executeautomation/playwright-mcp-server

 

# Windows 네이티브 ( Windows에선 npx 직접 실행 문제를 피하기 위해 cmd /c 래퍼가 권장 된다고 한다.)
https://docs.anthropic.com/en/docs/claude-code/mcp

claude mcp add playwright -- npx -y @executeautomation/playwright-mcp-server

 

 - 설치하기 ( 전역 ) : 위치는 본인의 버전에 따라 2가지 정도로 추정된다 ( ~/.claude/settings.json 또는 ~/.claude.json )

ex) 해당 본인의 사용자 폴더의 claude.json 파일을 수정하여 직접 파일을 수정하여 주자.

 

Gemini CLI

Gemini CLI에서는 직접 설정 파일에 추가해 보겠다.

 

※ 하기 예시 실행 도중 하기와 같이 브라우저 실행 오류가 발생하는 경우 playwirght를 완전히 설치한 후 다시 설치해 주자.

npm uninstall playwright
npm install playwright@latest
npx playwright install

 

 

사용 예시

기본 웹 탐색 가장 간단한 예시부터 시작해보자.

✅ 사용자 명령
"구글에 가서 'Playwright MCP'를 검색해줘"

 - 너무 늦게 말한건가 싶지만, 내가 지금 작성한 포스팅은 ExecuteAutomation 버전을 포스팅 한 것이다. Microsoft의 Playwright와 기능상 차이점이 있다고하는데 이는 각자 사용해보며 원하는 방향으로 사용하면 될 것 같다. 

 

ex) 두사의 Playwirght 비교

 

항목	@playwright/mcp@latest (Microsoft 공식)	@executeautomation/playwright-mcp-server (ExecuteAutomation)
동작 방식	접근성 트리 기반, 구조적 데이터 중심	실제 브라우저 기반 자동화, 스크린샷·JS 실행 등 UI 제어 중심
장점	빠르고 결정론적이며 LLM 친화적, 리소스 효율적 (<70% 메모리 절감 보고 사례)(ScrapingBee, GitHub)	다양한 자동화 기능 제공 (스크린샷, 코드 생성, JS 실행 등); 유연한 도구 기반 사용(GitHub, Execute Automation, ScrapingBee)
단점	UI 기반 제어에는 제약, 시각적 상호작용 어려움	구조적 정보 부족, 시스템 리소스 부담 증가 가능
사용 사례	AI 기반 테스트 생성, 복잡 UI 없이 구조 중심 흐름에 적합(supatest.ai, Medium, DEV Community)	화면 기반 상호작용, 웹 스크래핑, 코드 녹화 등의 고도화 자동화 시나리오에 적합(GitHub, ScrapingBee)

 

이외의 여러가지 사용 예시도 참고해보자.

✅ 사용자 명령
"https://goddaehee.co.kr 열고 1280x720으로 보고, fullPage 스크린샷 찍어서 파일로 저장해줘.”"

 

✅ 사용자 명령
"GitHub에 로그인해줘. 아이디는 test@example.com, 비밀번호는 mypassword123"

✅ 사용자 명령
"온라인 쇼핑몰에서 상품을 주문하는 전체 과정을 테스트하는 Playwright 코드를 만들어줘"

✅ 사용자 명령
"뉴스 사이트에서 오늘의 주요 뉴스 제목 5개를 가져와줘"

✅ 자동 스크린샷 캡처
테스트 실행 중 자동으로 스크린샷을 찍어서 시각적으로 확인할 수 있다. 특히 에러가 발생했을 때 어떤 상태에서 실패했는지 바로 볼 수 있어서 디버깅이 훨씬 쉬워졌다.

✅ API와 UI 테스트 동시 지원
브라우저 UI 테스트뿐만 아니라 API 호출도 함께 할 수 있다. "이 버튼 클릭 후에 백엔드 API가 올바르게 호출되는지 확인해줘"라고 요청하면 실제로 네트워크 탭까지 모니터링해준다.

✅ 테스트 코드 자동 생성
자연어로 시나리오를 설명하면 해당하는 Playwright 코드를 자동으로 생성해준다. 이렇게 생성된 코드를 기반으로 정식 테스트 스위트에 추가할 수 있다.

 

효과적인 사용 팁

 - 명확한 지시사항 제공 AI가 더 정확하게 작업하려면 구체적인 지시를 해야 한다.

❌ 모호한 명령
"쇼핑몰에서 뭔가 사줘"

✅ 명확한 명령
"쿠팡에 가서 '무선마우스'를 검색하고, 가격이 3만원 이하인 상품 중 평점이 높은 것을 장바구니에 담아줘"

 - 단계별 접근 복잡한 작업은 단계를 나누어 진행하는 것이 효과적이다.

// 단계별 명령 예시

1. "GitHub에 로그인해줘"
   → 완료 확인 후
2. "새 저장소를 만들어줘. 이름은 'my-project'"
   → 완료 확인 후  
3. "README.md 파일을 생성하고 프로젝트 설명을 추가해줘"

 

 

 - 컨텍스트 정보 제공 AI가 작업을 더 잘 이해하도록 배경 정보를 제공하자.

✅ 컨텍스트가 포함된 명령
"사내 인사관리 시스템(https://hr.company.com)에 접속해서 신입사원 김철수의 정보를 입력해줘. 부서는 개발팀, 직급은 주임, 입사일은 2025-01-15야."

 

단순히 스크린샷이 아닌 접근성 스냅샷

MCP가 스크린샷 대신 "접근성 스냅샷"을 사용한다는 점도 표현해보고자 했다.

스크린샷은 시각적 변화에 취약하지만, 접근성 스냅샷은 웹페이지의 구조와 의미를 이해하고 구조화된 피드백을 제공한다는 점에서 차이가 있다.

MCP 동작 흐름: AI가 웹을 읽는 방법

사용자가 "로그인 테스트를 만들어줘"라고 요청했을 때:

1. LLM

명령 해석 및 계획 수립

→

2. MCP 서버

명령을 Playwright 액션으로 변환

→

3. Playwright

브라우저 실제 제어

→

4. 접근성 스냅샷

구조화된 피드백 제공

💡 접근성 스냅샷
• 의미 이해: 버튼이 버튼인지, 입력창이 입력창인지 구조적으로 파악
• 시각 독립: 색깔이나 위치가 바뀌어도 기능으로 요소를 찾음
• 결정론적: 같은 페이지면 항상 같은 스냅샷 생성
• 경량화: 스크린샷보다 용량이 작고 처리 속도 빠름

 

고급 설정 옵션 ⚙️

실제 업무에서 사용할 때는 다양한 옵션을 활용할 수 있다. 특히 테스트 환경에 따라 설정을 조정하면 더 효율적으로 사용할 수 있다.

옵션	설명	추천 상황
--headless	브라우저를 백그라운드에서 실행	CI/CD
--browser chrome	사용할 브라우저 지정	크로스 브라우저 테스트
--port 8931	서버가 열릴 포트 지정	Docker 환경
--isolated	매 세션마다 프로필 초기화	클린 테스트
--vision	스크린샷 기반 상호작용	복잡한 UI 요소

설정 예시

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y", 
        "@executeautomation/playwright-mcp-server",
        "--browser", "chrome",
        "--isolated",
        "--headless"
      ]
    }
  }
}

💡 설정 파일로도 가능
복잡한 설정은 별도 config 파일로 관리할 수 있다: npx @executeautomation/playwright-mcp-server --config ./my-mcp-config.json

 

지원 기능과 주요 도구들

ExecuteAutomation의 Playwright MCP Server에서 실제로 제공하는 기능들 정리. 이런 옵션이 있다는 걸 알고 자연어로 요청한다면 더 다양한 업무를 요청할 수 있지 않을까?

핵심 기능 개요

• 콘솔 로그 모니터링: 브라우저 콘솔의 오류, 경고, 정보 로그 실시간 수집
• 코드 생성: 사용자 동작을 기록하여 Playwright 테스트 코드 자동 생성
• 웹 스크래핑: 페이지의 텍스트, HTML 콘텐츠 추출
• 스크린샷 기능: 전체 페이지 또는 특정 요소의 이미지 캡처
• JavaScript 실행: 브라우저 컨텍스트에서 임의의 JavaScript 코드 실행
• 기본 웹 상호작용: 클릭, 입력, 드롭다운 선택, 호버 등

 

브라우저 자동화 도구

🌐 페이지 탐색 및 설정

도구명	기능	주요 옵션
Playwright_navigate	URL로 이동, 브라우저 설정	browserType, viewport, headless
playwright_go_back/forward	브라우저 뒤로/앞으로 가기	-
playwright_custom_user_agent	사용자 에이전트 설정	userAgent

🖱️ 사용자 상호작용

도구명	기능	특징
Playwright_click	요소 클릭	CSS 셀렉터 기반
playwright_click_and_switch_tab	링크 클릭 후 새 탭 전환	탭 관리 자동화
Playwright_iframe_click/fill	아이프레임 내 요소 조작	중첩 프레임 지원
Playwright_fill	입력 필드 채우기	텍스트 입력 자동화
Playwright_select	드롭다운 선택	SELECT 태그 지원
playwright_upload_file	파일 업로드	input[type='file'] 지원
playwright_drag	드래그 앤 드롭	복잡한 UI 상호작용
playwright_press_key	키보드 입력	특수키 지원

📊 데이터 수집 및 분석

도구명	기능	옵션
Playwright_screenshot	스크린샷 캡처	fullPage, base64, 요소별
playwright_get_visible_text	보이는 텍스트 추출	숨겨진 요소 제외
playwright_get_visible_html	HTML 콘텐츠 추출	스크립트/스타일 제거 옵션
Playwright_console_logs	콘솔 로그 수집	타입별 필터링, 검색
playwright_save_as_pdf	PDF 저장	페이지 포맷, 마진 설정

 

코드 생성 기능

가장 인상적인 기능 중 하나가 바로 테스트 코드 자동 생성이다. 사용자의 동작을 실시간으로 기록해서 Playwright 테스트 코드로 변환해준다.

📝 코드 생성 도구들

도구명	기능	용도
start_codegen_session	코드 생성 세션 시작	액션 기록 시작
end_codegen_session	세션 종료 및 테스트 파일 생성	최종 코드 출력
get_codegen_session	세션 정보 조회	진행 상황 확인
clear_codegen_session	세션 클리어	재시작 준비

 

네트워크 모니터링

API 테스트나 네트워크 요청 검증을 위한 도구들도 제공한다.

도구명	기능
Playwright_expect_response	HTTP 응답 대기 시작
Playwright_assert_response	응답 검증 및 내용 확인

기타

🗂️ 탭 관리 & 기타

기능	명령어
새 탭 열기	browser_tab_new
탭 전환	browser_tab_select
URL 이동	browser_navigate
뒤로/앞으로	browser_navigate_back/forward
테스트 코드 생성	browser_generate_playwright_test

 

활용 분야

 - 테스트 자동화

🧪 테스트 시나리오

• 회원가입/로그인 프로세스 테스트
• 쇼핑몰 주문 과정 검증
• 폼 유효성 검사 테스트
• 다국어 사이트 번역 확인
• 반응형 웹 레이아웃 테스트

 - 

업무 자동화

⚡ 반복 작업 자동화

• 정기적인 데이터 수집 및 리포트 생성
• 소셜미디어 콘텐츠 자동 포스팅
• 경쟁사 가격 모니터링
• 고객 지원 티켓 자동 분류
• 정기적인 시스템 상태 점검

 - 데이터 수집

✅ 실제 활용 예시
"부동산 사이트에서 강남구 아파트 매매가 정보를 수집해서 엑셀로 정리해줘"

AI가 자동으로:

• 부동산 사이트 접속
• 검색 조건 설정 (강남구, 아파트, 매매)
• 여러 페이지 순회하며 데이터 수집
• 구조화된 형태로 정리
• 엑셀 파일로 저장

 

주의사항 및 모범 사례 ⚠️

 -  윤리적 사용

⚠️ 주의사항
• 웹사이트의 이용약관과 robots.txt 준수
• 과도한 요청으로 서버에 부하 주지 않기 ( 이런경우 프록시 우회 설정이 추가적으로 필요하다. )
• 개인정보 수집 시 관련 법규 준수
• 저작권이 있는 콘텐츠 무단 수집 금지

 

 -  성능 최적화

💡 최적화 팁
• 적절한 대기: 페이지 로딩을 기다리되 불필요한 지연 피하기
• 명확한 셀렉터: 구체적인 요소 설명으로 검색 시간 단축
• 배치 처리: 비슷한 작업을 묶어서 한 번에 처리

 

 -  안정성 확보

✅ 안정적인 자동화를 위한 팁
• 단계별 검증: 각 단계가 성공했는지 확인
• 예외 처리: 예상치 못한 상황에 대한 대안 준비
• 정기적인 점검: 사이트 변경에 따른 스크립트 업데이트
• 로그 관리: 실행 과정을 기록하여 문제 원인 파악

 

자주 묻는 질문 ❓

Q: 기존 Playwright 스크립트와 함께 사용할 수 있나요?

A: 네, 전혀 문제없습니다. MCP 서버로 프로토타이핑하고 생성된 코드를 기존 테스트 스위트에 통합하는 방식으로 사용하고 있어요.

Q: 성능상 오버헤드가 크지 않나요?

A: 개발/테스트 단계에서는 충분히 감수할 만한 수준이에요. 프로덕션 CI/CD에서는 생성된 순수 Playwright 코드를 사용하는 것을 추천합니다.

Q: 복잡한 비즈니스 로직도 테스트할 수 있나요?

A: 시나리오를 단계별로 나누어서 설명하면 대부분 가능해요. 다만 매우 복잡한 로직은 부분별로 나누어서 접근하는 것이 좋습니다.

Q: 어떤 브라우저를 지원하나요?

A: Chromium, Firefox, WebKit을 모두 지원합니다. 기본적으로 Chromium을 사용하며, `--browser` 옵션으로 다른 브라우저를 선택할 수 있습니다.

Q: 모바일 웹사이트도 테스트할 수 있나요?

A: 네, `--device` 옵션으로 다양한 모바일 기기를 에뮬레이션할 수 있습니다. "iPhone 15", "Samsung Galaxy S23" 등의 프리셋을 사용하거나 커스텀 해상도를 설정할 수 있습니다.

Q: 실행 중에 에러가 발생하면 어떻게 하나요?

A: AI가 자동으로 재시도하거나 대안을 찾으려고 합니다. 만약 계속 실패한다면 "스크린샷을 찍어서 현재 상황을 보여줘" 또는 "다른 방법으로 시도해줘"라고 요청하세요.

Q: 보안이 중요한 사이트에서도 사용해도 되나요?

A: 개인 계정 정보나 민감한 데이터는 AI에게 직접 전달하지 마세요. 테스트용 계정을 별도로 만들거나, 개발/스테이징 환경에서 사용하는 것을 권장합니다.

 

참고 자료

• ExecuteAutomation/mcp-playwright GitHub - 공식 저장소 및 문서
• Playwright MCP Server 공식 문서 - 설치 및 사용법 가이드
• NPM 패키지 - 최신 버전 및 설치 정보
• Claude MCP 공식 문서 - MCP 프로토콜 이해를 위한 공식 가이드