Claude에 브라우저 눈과 손을 달다 — Playwright MCP 플러그인

Claude Code는 기본적으로 파일과 터미널만 다룬다. 브라우저를 직접 보거나 조작할 수 없다. 그래서 "내가 배포한 UI가 제대로 동작하는지 확인해줘"라고 하면, Claude가 할 수 있는 것은 코드를 읽어서 추론하는 것뿐이다. 실제 브라우저를 열어서 확인하는 게 아니다.

Playwright MCP 플러그인은 이 제약을 제거한다. 설치하면 Claude Code가 브라우저를 직접 열고, 버튼을 클릭하고, 텍스트를 입력하고, 화면을 캡처할 수 있게 된다. "로그인 페이지에서 틀린 비밀번호를 입력했을 때 에러 메시지가 제대로 나오는지 확인해줘"라고 하면, Claude가 실제 브라우저에서 그 동작을 재현하고 결과를 보고한다.

그림에서 핵심은 "browser_screenshot → Claude가 이미지를 분석" 단계다. Claude는 텍스트뿐만 아니라 이미지도 이해할 수 있다. Playwright MCP가 화면을 캡처해서 Claude에게 돌려주면, Claude는 그 이미지를 분석해서 "에러 메시지가 빨간색 텍스트로 나왔고, 위치는 로그인 버튼 아래입니다"처럼 시각적 판단을 내린다. 화면을 직접 보고 판단하는 것이다.

3가지 구성요소와의 관계

GitHub MCP와 마찬가지로 Playwright MCP 플러그인도 서브에이전트의 3가지 구성요소 중 ② 도구 목록만 제공한다. 플러그인 자체에는 시스템 프롬프트도 트리거도 없다. 브라우저를 조작하는 도구들이 Claude Code에 추가되는 것뿐이다.

직접 E2E 테스트 에이전트를 만들어 보자. Playwright MCP가 제공하는 도구를 사용하는 SKILL.md다.

# ~/.claude/skills/e2e-tester/SKILL.md
---
name: e2e-tester
description: 브라우저로 직접 E2E 테스트를 수행하는 에이전트
triggers:
  - E2E 테스트
  - 브라우저 테스트
  - UI 확인해줘
  - 화면 보여줘
allowed-tools:
  - mcp__playwright__browser_navigate
  - mcp__playwright__browser_click
  - mcp__playwright__browser_type
  - mcp__playwright__browser_screenshot
  - mcp__playwright__browser_wait_for_element
  - mcp__playwright__browser_evaluate
---

당신은 QA 엔지니어로, 실제 브라우저에서 기능을 검증합니다.

## 테스트 절차

1. browser_navigate로 테스트할 URL로 이동한다.
2. browser_screenshot으로 초기 상태를 캡처해 확인한다.
3. 지시받은 동작을 browser_click, browser_type으로 실행한다.
4. browser_wait_for_element로 결과가 나타날 때까지 기다린다.
5. browser_screenshot으로 최종 상태를 캡처해 분석한다.

## 보고 형식

- 테스트 항목: 무엇을 확인했는지
- 결과: PASS / FAIL
- 근거: 화면에서 확인한 내용 (캡처 포함)

설치 방법

GitHub MCP와 달리 Playwright MCP는 인증이 필요 없다. 로컬에서 브라우저를 제어하는 방식이라 토큰이 없어도 된다. npx로 자동 실행되므로 Node.js만 설치되어 있으면 된다.

# 1단: 플러그인 설치 (npx 자동 처리)
/plugin install playwright@claude-plugins-official

# 처음 실행 시 Playwright 브라우저 다운로드가 자동으로 진행된다
# (Chromium ~200MB)

# 2단: 위 SKILL.md 파일 저장
mkdir -p ~/.claude/skills/e2e-tester
# (SKILL.md 내용 저장)

# 사용 예시
# 사용자: "localhost:3000 로그인 화면 E2E 테스트해줘"
# → e2e-tester 에이전트가 호출되어 실제 브라우저를 열고 테스트한다

한 가지 주의할 점이 있다. Playwright MCP는 헤드리스(headless) 모드로 기본 동작한다 — 브라우저 창이 화면에 나타나지 않고 백그라운드에서 실행된다. 디버깅 목적으로 브라우저를 눈으로 보고 싶다면 플러그인 설정에서 headless를 끌 수 있다.

설치 후 파일 구조

설치 후 파일 구조는 GitHub MCP와 동일하게 두 개뿐이다. 하지만 .mcp.json의 내용이 완전히 다르다 — HTTP 원격 접속이 아니라 로컬 프로세스 실행 방식이다.

~/.claude/plugins/cache/claude-plugins-official/playwright/unknown/
  .claude-plugin/
    plugin.json     ← 플러그인 메타데이터 (이름·설명·작성자: Microsoft)
  .mcp.json         ← 로컬 MCP 서버 실행 명령

// .mcp.json — 실제 파일 전체
{
  "playwright": {
    "command": "npx",                    // 로컬 프로세스 방식
    "args": ["@playwright/mcp@latest"]   // 최신 버전을 그때그때 다운로드해 실행
  }
}

GitHub MCP의 "type": "http"와 달리 여기는 "command": "npx"다. Claude Code가 이 플러그인을 활성화하면 백그라운드에서 npx @playwright/mcp@latest를 실행해 로컬 MCP 서버 프로세스를 띄운다. 이 프로세스가 Chromium 브라우저를 제어하고, Claude Code가 그 프로세스와 JSON-RPC로 통신한다. 인증이 따로 없는 이유는 브라우저가 로컬 머신에서만 동작하기 때문이다.

plugin.json의 작성자 필드를 보면 GitHub MCP와 차이가 있다.

// .claude-plugin/plugin.json
{
  "name": "playwright",
  "description": "Browser automation and end-to-end testing MCP server by Microsoft.
    Enables Claude to interact with web pages, take screenshots, fill forms,
    click elements, and perform automated browser testing workflows.",
  "author": { "name": "Microsoft" }   // Microsoft 제작·배포
}

이 두 파일 어디에도 시스템 프롬프트(①)와 트리거(③)가 없다. GitHub MCP와 동일하게 도구 목록(②)만 제공하는 플러그인이다. 앞서 작성한 e2e-tester/SKILL.md가 없으면 Playwright 도구들은 사용자가 직접 "browser_navigate 도구로 localhost:3000 열어줘"라고 요청해야만 동작한다. SKILL.md가 시스템 프롬프트와 트리거를 붙여줘야 비로소 "UI 확인해줘" 한 마디로 자동화가 동작한다.

어떤 효과가 있나

Playwright MCP가 가장 효과적인 순간은 코드를 배포한 직후다. 코드를 고치고 나서 "정말 제대로 동작하는지" 확인하는 과정이 자동화된다. 기존에는 개발자가 직접 브라우저를 열고 클릭해가며 확인해야 했지만, 이제 Claude에게 "방금 고친 비밀번호 재설정 흐름 테스트해줘"라고 하면 된다.

두 번째 효과는 회귀 테스트 자동화다. "매번 PR이 올라올 때마다 로그인 → 메인 페이지 이동 → 데이터 로드 순서로 기본 동작을 확인한다"는 루틴을 만들어 두면, Claude가 자동으로 브라우저를 열어 확인하고 결과를 보고한다. Playwright 코드를 직접 짜지 않아도 된다.

세 번째 효과는 덜 알려져 있지만 중요하다. Claude가 이미지를 분석한다는 것이다. 단순히 클릭 좌표를 계산하는 도구가 아니다. "이 버튼의 색상이 디자인 가이드(파란색 #2563EB)와 일치하는지 확인해줘"라고 하면, Claude가 스크린샷을 찍고 화면에서 실제 색상을 확인한 뒤 판단을 내린다. 시각적 UI 검증이 자동화되는 것이다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.