AI가 브라우저를 직접 조종한다 — Playwright MCP 1편: 설치부터 첫 자동화까지

"셀레늄 짜기 귀찮다", "브라우저 자동화 코드 유지보수가 너무 힘들다" — 이 고민을 한 번에 날려버리는 도구가 Microsoft에서 공식 출시됐다. Playwright MCP는 Claude, Cursor, VS Code 같은 AI 클라이언트가 실제 브라우저를 자연어 명령으로 직접 제어하게 해준다. 셀렉터도, wait 코드도, 예외 처리도 AI가 알아서 한다.

---

핵심 요약

→ Playwright MCP는 Microsoft 공식 패키지(@playwright/mcp)로, AI 에이전트에게 브라우저 조작 도구를 제공하는 MCP 서버
→ 비전 모델(스크린샷) 없이 접근성 트리(Accessibility Tree) 기반으로 동작 — 빠르고 토큰 효율적
→ Claude Desktop, Claude Code, Cursor, VS Code, Windsurf 등 MCP 클라이언트라면 어디든 연결 가능
→ browser_navigate, browser_click, browser_type, browser_snapshot 등 34개 도구 내장
→ Node.js 18+ 만 있으면 추가 설치 없이 npx로 즉시 실행
→ 주의: 검색하면 커뮤니티 패키지 @executeautomation/playwright-mcp-server가 먼저 뜨는데, Microsoft 공식 패키지는 @playwright/mcp
→ 2026년 기준 GitHub Star 30,000+, 실사용 현장에서 이미 표준으로 자리잡는 중

---

1. Playwright MCP가 뭔가요?

기존 브라우저 자동화 방식은 이랬다.

# ❌ 기존 방식: 셀렉터 찾고, wait 넣고, 예외 처리하고...
page.goto("https://example.com")
page.wait_for_selector("#login-btn")
page.click("#login-btn")
page.fill("input[name='email']", "test@test.com")

Playwright MCP를 쓰면 이렇게 바뀐다.

# ✅ AI에게 자연어로 지시
"example.com에 접속해서 로그인 버튼 클릭하고 이메일 입력란에 test@test.com 입력해줘"

AI(Claude, Cursor 등)가 MCP 서버에게 명령을 보내고, 서버가 실제 Playwright로 브라우저를 제어한다. 결과(페이지 상태, URL, 접근성 트리 스냅샷)는 다시 AI에게 구조화된 형태로 돌아온다.

# Playwright MCP 동작 흐름

[AI 클라이언트]  ←→  [Playwright MCP 서버]  ←→  [실제 브라우저]
 Claude/Cursor       @playwright/mcp          Chromium/Firefox/WebKit
  자연어 명령          34개 도구 실행           실제 DOM 조작

핵심 차이점은 접근성 트리 사용이다. 스크린샷을 찍어 이미지로 분석하는 방식(비전 모델)은 토큰을 많이 먹고 느리다. Playwright MCP는 브라우저 DOM의 접근성 구조를 텍스트로 읽기 때문에 훨씬 빠르고 정확하다.

---

2. 사전 준비 — Node.js 확인

# Node.js 버전 확인 (18 이상이어야 함)
node --version

# v16이라면 업그레이드 필요 — v16에서 실행 시 "performance is not defined" 에러 발생
# Node.js 공식 사이트에서 LTS 버전(v22 권장) 설치: https://nodejs.org

---

3. 클라이언트별 설치 방법

Claude Desktop

claude_desktop_config.json 파일에 아래 내용을 추가한다.

// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: C:\Users\{유저명}\AppData\Roaming\Claude\claude_desktop_config.json

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

# ⚠️ Windows 사용자 주의
# 설정 변경 후 Claude Desktop을 완전히 종료 + 작업 관리자에서 프로세스까지 종료해야 적용됨
# 그냥 X 버튼으로 닫으면 백그라운드에서 계속 실행 중

Claude Code (터미널)

# 한 줄로 끝 — 프로젝트 디렉터리에서 실행
claude mcp add playwright npx @playwright/mcp@latest

# --scope project: 팀 공유용 (버전 관리에 포함됨)
claude mcp add playwright npx @playwright/mcp@latest --scope project

# --scope user: 내 계정 전체에 적용
claude mcp add playwright npx @playwright/mcp@latest --scope user

Cursor

# Cursor Settings → MCP → Add new MCP Server
# Type: command
# Command: npx @playwright/mcp@latest

VS Code

// .vscode/mcp.json (프로젝트 단위 설정)
{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

---

4. 첫 번째 브라우저 자동화 실행

설치가 끝나면 Claude Desktop에서 바로 테스트할 수 있다.

테스트 1 — 페이지 접속 + 스냅샷

"playwright로 https://playwright.dev 에 접속해서 페이지 구조 알려줘"

Claude가 browser_navigate → browser_snapshot 도구를 순서대로 호출하고, 페이지의 접근성 트리를 텍스트로 돌려준다.

테스트 2 — 폼 자동 입력

"https://the-internet.herokuapp.com/login 에 접속해서
 username에 'tomsmith', password에 'SuperSecretPassword!' 입력하고 로그인 버튼 눌러줘"

# Claude가 내부적으로 실행하는 MCP 도구 호출 순서
browser_navigate("https://the-internet.herokuapp.com/login")
browser_snapshot()                          # 접근성 트리로 입력 필드 확인
browser_type(element="username", text="tomsmith")
browser_type(element="password", text="SuperSecretPassword!")
browser_click(element="Login button")
browser_snapshot()                          # 로그인 결과 확인

테스트 3 — 스크린샷 저장

"naver.com 접속해서 스크린샷 찍어줘"

browser_take_screenshot 도구가 실행되며 이미지를 반환한다.

---

5. 주요 내장 도구 34개 — 카테고리별 정리

# 핵심 자동화 도구
browser_navigate(url)          # 페이지 이동
browser_click(element)         # 요소 클릭
browser_type(element, text)    # 텍스트 입력
browser_snapshot()             # 접근성 트리 스냅샷 (텍스트 기반, 토큰 효율적)
browser_take_screenshot()      # 화면 캡처 (비전 모델 필요 시)

# 탭 관리
browser_tab_new(url)           # 새 탭 열기
browser_tab_list()             # 열린 탭 목록
browser_tab_select(index)      # 탭 전환
browser_tab_close()            # 탭 닫기

# 고급 조작
browser_scroll(direction)      # 스크롤
browser_hover(element)         # 마우스 오버
browser_select_option()        # 드롭다운 선택
browser_file_upload()          # 파일 업로드
browser_evaluate(script)       # JavaScript 직접 실행

# 어설션 (테스트 자동화)
browser_assert_text()          # 텍스트 존재 확인
browser_assert_url()           # 현재 URL 확인

---

6. 브라우저 설정 커스터마이징

// 브라우저 종류 변경 (기본값: Chromium)
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--browser", "firefox"]
      // "webkit", "firefox", "chromium" 선택 가능
    }
  }
}

// 헤드리스 모드 (브라우저 창 숨김 — CI/CD 환경에서 유용)
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    }
  }
}

// 뷰포트 크기 지정
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--viewport-size", "1920,1080"
      ]
    }
  }
}

---

7. 자주 발생하는 오류와 해결법

# ❌ 오류: "performance is not defined"
# 원인: Node.js 16 이하 사용
# 해결: node --version 확인 후 18+ 업그레이드

# ❌ 오류: MCP 서버가 Claude Desktop에 안 뜸
# 원인: Claude Desktop이 완전히 종료 안 됨 (백그라운드 프로세스 잔존)
# 해결: 작업 관리자(Windows) 또는 Activity Monitor(Mac)에서 Claude 프로세스 완전 종료 후 재시작

# ❌ 오류: @executeautomation/playwright-mcp-server 설치 후 동작 이상
# 원인: 커뮤니티 패키지 (Microsoft 공식 아님) — API 구조 다름
# 해결: Microsoft 공식 패키지 @playwright/mcp 사용

# ❌ 오류: npx 명령어를 찾을 수 없음
# 원인: npm이 설치 안 됨 (Node.js 설치 시 함께 설치됨)
# 해결: Node.js 재설치

---

✅ 이런 경우 Playwright MCP를 써라

✅ Claude Desktop / Cursor에서 자연어로 브라우저를 제어하고 싶을 때
✅ E2E 테스트 코드를 AI가 자동으로 짜게 하고 싶을 때
✅ 반복적인 웹 스크래핑 작업을 자동화하고 싶을 때
✅ 스크린샷 없이 빠른 DOM 기반 자동화가 필요할 때

❌ 이런 경우엔 다른 방법 고려
❌ 토큰 효율이 극도로 중요한 고처리량 에이전트 → @playwright/cli 방식 고려 (MCP 대비 4배 토큰 절약)
❌ 로그인 세션 유지가 핵심인 프로덕션 환경 → 2편에서 다룰 세션 퍼시스턴스 설정 필요
❌ Shadow DOM이 많은 최신 디자인 시스템 → 별도 selector 전략 필요

 

✅ 시리즈 전체 요약

✅ 1편 — Playwright MCP 설치 + Claude Desktop/Cursor/VS Code 연결 https://cell-devlog.tistory.com/277
✅ 2편 — 자연어 스크래핑·폼 자동화·로그인 세션 영구 유지 https://cell-devlog.tistory.com/278
✅ 3편 — 에러 핸들링·샤딩·Docker·GitHub Actions CI 파이프라인 https://cell-devlog.tistory.com/279
✅ 4편 — 클라우드 브라우저 MCP 생태계 비교 + 상황별 선택 기준 https://cell-devlog.tistory.com/280