Playwright MCP로 브라우저 자동 제어하는 방법

Playwright MCP로 브라우저 자동 제어하는 방법

📌 이 글의 핵심 요약

Playwright MCP는 Microsoft가 만든 브라우저 자동화 엔진을 AI 에이전트와 연결하는 도구다. 자연어 명령 한 줄로 로그인, 클릭, 폼 입력까지 처리할 수 있으며, Claude Desktop·Cursor·VS Code 등 대부분의 MCP 클라이언트에서 동일하게 동작한다.

📋 목차

1. Playwright MCP가 뭔지 먼저 정리 2. 설치 방법 — 명령어 3줄이면 끝 3. 클라이언트별 설정 방법 4. 실전 활용 — 이렇게 쓰면 된다 5. 자주 겪는 오류와 해결법 6. 정리

---

Playwright MCP가 뭔지 먼저 정리

업무 자동화를 고민하다 보면 결국 브라우저 제어 문제에 부딪힌다. 로그인, 데이터 수집, 반복 클릭을 매번 손으로 하기엔 시간이 너무 아깝다. Playwright 코드를 직접 짜자니 진입장벽이 높다.

이 문제를 해결해 주는 것이 Playwright MCP다. Playwright는 Microsoft가 만든 브라우저 자동화 프레임워크고, MCP는 AI 모델이 외부 도구와 대화하는 표준 규약이다. 둘을 연결하면 AI 에이전트가 브라우저를 직접 제어한다.

⚙️ 핵심 작동 원리 — 접근성 트리(Accessibility Tree)

Playwright MCP는 스크린샷이 아니라 웹 페이지의 접근성 트리를 기반으로 동작한다. DOM 구조를 역할(role)·이름(name)·상태(state)로 정리한 텍스트 표현으로, 비전 모델 없이도 요소를 정확히 식별하고 상호작용할 수 있어 빠르고 안정적이다.

---

설치 방법 — 명령어 3줄이면 끝

Node.js가 설치된 환경이라면 Playwright MCP 세팅은 간단하다. 터미널을 열고 아래 순서대로 입력하면 된다.

# 1단계: Playwright MCP 최신 버전 실행 (설치 없이 바로 사용)
npx @playwright/mcp@latest

# 또는 글로벌 설치 후 사용
npm install -g @playwright/mcp

# 2단계: 브라우저 설치 (최초 1회)
npx playwright install
npx playwright install-deps

⚠️ 주의 — 브라우저 설치를 건너뛰면 실행 시 권한 오류가 발생한다. AI 클라이언트는 sudo 권한이 없어 자동 설치에 실패하는 경우가 많으니 반드시 터미널에서 수동으로 먼저 실행해야 한다.

---

클라이언트별 설정 방법

Claude Desktop 설정

설정 파일에 서버 정보를 추가하면 된다. macOS 기준 경로는 ~/Library/Application Support/Claude/claude_desktop_config.json이다.

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

Claude Code CLI 설정

Claude Code를 쓴다면 터미널 한 줄로 연결된다. -s user 옵션을 추가하면 모든 프로젝트에 공통 적용된다.

# 현재 프로젝트에만 적용
claude mcp add playwright -- npx @playwright/mcp@latest

# 모든 프로젝트에 적용
claude mcp add playwright -s user -- npx @playwright/mcp@latest

Cursor / VS Code 설정

Cursor는 설정 → MCP 탭에서 JSON 파일을 열어 동일한 형식으로 붙여넣으면 된다. VS Code는 명령 팔레트에서 Add MCP Server를 검색하면 GUI로 추가할 수 있다. 설정 후 반드시 클라이언트를 완전히 재시작해야 적용된다.

---

실전 활용 — 이렇게 쓰면 된다

설정을 마치면 AI 에이전트에게 자연어로 지시하는 것만으로 브라우저가 움직인다. 코드 한 줄 없이도 된다.

💬 자연어 지시 예시

· "네이버에 접속해서 '파이썬 강의' 검색하고 첫 번째 결과 제목 알려줘"
· "구글 폼에 이름·이메일 입력하고 제출 버튼 눌러줘"
· "이 쇼핑몰 로그인 페이지에서 이메일 입력하고 비밀번호 넣어줘"
· "지금 열린 페이지 스크린샷 찍어서 저장해줘"

내부적으로는 browser_navigate로 URL을 열고, browser_click과 browser_type을 반복하며 처리한다. 접근성 트리로 요소를 파악하기 때문에 CSS 셀렉터를 몰라도 동작한다.

🎯 실전 활용 시나리오

· E2E 테스트 자동화 — 로그인~결제 전 과정을 자연어 프롬프트로 자동 검증
· 반복 폼 입력 — 동일한 양식을 여러 번 제출해야 할 때
· 웹 데이터 수집 — 복잡한 페이지 구조로 일반 크롤러가 안 되는 경우
· 배포 후 스모크 테스트 — 주요 버튼·링크가 정상 작동하는지 빠르게 확인

💡 MCP 서버 vs CLI — 어떤 걸 써야 할까?

여러 단계를 이어서 처리해야 하면 MCP 서버가 유리하다. 스크린샷 한 장, 페이지 확인 한 번처럼 단순 작업은 CLI가 토큰 소비가 약 4배 적어 효율적이다.

---

자주 겪는 오류와 해결법

오류 상황	원인	해결 방법
브라우저 실행 실패	브라우저 미설치	npx playwright install 실행
설정 파일 오류	JSON 문법 오류	슬래시(/) 사용, 재시작 필수
동시 실행 충돌	동일 프로필 사용	--isolated 플래그 추가
MCP 도구 미인식	클라이언트 미재시작	완전 종료 후 재실행

✅ 장점

· 코드 없이 자연어로 제어
· 접근성 트리 기반으로 안정적
· 주요 AI 클라이언트 모두 지원
· 스크린샷·PDF 변환도 가능

❌ 주의점

· Node.js 환경 필수
· 브라우저 수동 설치 필요
· 복잡한 작업은 토큰 소비 많음
· 버전마다 옵션 변동 있음

---

정리

Playwright MCP는 브라우저 자동화의 진입장벽을 크게 낮춰준 도구다. 설치는 npx 한 줄, 설정은 JSON 몇 줄이면 충분하고 이후로는 자연어 지시만 하면 된다.

반복 웹 작업이 있거나 E2E 테스트가 필요하다면 한 번 세팅해두는 것만으로 생산성이 달라진다. Claude Desktop이나 Cursor에 연결해 간단한 크롤링부터 시작해보자.