Playwright MCP — LLM에게 브라우저를 주다

텍스트 기반 LLM의 가장 큰 한계는 실제로 화면을 인식할 수 없다는 점입니다.

코드를 아무리 잘 작성해도, 렌더링된 UI가 실제로 어떤 구조와 모습인지는 알 수 없습니다. Playwright MCP는 이 한계를 무너뜨립니다.

LLM이 브라우저를 제어한다는 것#

일반적으로 LLM은 텍스트 입력을 받아 텍스트를 출력합니다. UI 개발을 도울 때도 코드만 보고 판단합니다.

Playwright MCP 서버를 연결하면 LLM이 실제 브라우저를 열고, 페이지를 탐색하고, 렌더링된 페이지의 구조를 인식한 뒤 판단을 내릴 수 있습니다.

여기서 중요한 점이 하나 있습니다. Playwright MCP가 LLM에게 넘기는 것은 스크린샷 이미지가 아니라 접근성 트리(accessibility tree) 입니다. 즉 페이지의 DOM 구조를 시맨틱하게 정리한 텍스트를 보고 "이 버튼은 여기 있고, 이 입력칸은 비어 있다"를 판단합니다. 이미지를 직접 보는 비전(vision) 방식은 선택적으로 켤 수 있습니다 — 자세한 차이는 아래에서 다룹니다.

실무에서는? "AI가 화면을 본다"는 표현 때문에 스크린샷을 떠올리기 쉽지만, 기본 동작은 접근성 트리 기반입니다.
비전 모델 없이도 동작하고, 토큰을 훨씬 적게 쓰며, 같은 입력에 같은 결과를 내는 결정론적 동작이라 자동화에 유리합니다.

설치#

Claude Code가 실행되지 않고 있는 일반 터미널에서 아래 명령어를 실행합니다.

claude mcp add playwright npx @playwright/mcp@latest

이 명령어 하나로 MCP 서버 이름(playwright)과 실행 커맨드가 등록됩니다.

권한 설정#

Playwright 도구를 매번 승인하는 팝업이 번거롭다면 .claude/settings.local.json에 미리 허용해둘 수 있습니다.

{
  "permissions": {
    "allow": ["mcp__playwright"],
    "deny": []
  }
}

mcp__playwright 앞에 언더스코어가 두 개인 것에 주의하세요.

LLM이 브라우저로 할 수 있는 것#

Playwright MCP를 통해 LLM이 직접 수행할 수 있는 동작들입니다.

실무에서는? 클릭·입력은 좌표가 아니라 스냅샷이 부여한 ref ID로 요소를 지정합니다.
그래서 레이아웃이 조금 바뀌어도 동작이 깨지지 않고, 셀렉터를 사람이 직접 작성하지 않아도 됩니다.

실전 활용 — UI 프롬프트 자동 개선#

Playwright MCP의 진가는 시각적 피드백 루프에 있습니다.

예를 들어 컴포넌트 생성 프롬프트를 개선하고 싶다면 이렇게 요청할 수 있습니다.

Navigate to localhost:3000, generate a test component,
review the visual output, and improve the generation prompt
at @src/lib/prompts/generation.tsx to produce better results.

Claude는 아래 흐름으로 작업합니다.

1. 브라우저를 열고 앱으로 이동
2. 컴포넌트 생성
3. 스크린샷을 찍어 시각적 결과 확인
4. 코드가 아닌 눈으로 본 결과를 바탕으로 프롬프트 수정
5. 수정된 프롬프트로 재생성해 검증

여기서는 "여백이 어색하다", "색 대비가 약하다" 같은 디자인 판단이 필요하므로, 구조만 담긴 접근성 트리가 아니라 browser_take_screenshot으로 실제 이미지를 받아 봅니다. 코드만 보는 것과 달리 실제 렌더링 결과를 기반으로 판단하기 때문에 스타일 개선이 훨씬 정밀해집니다.

접근성 트리 vs 비전 모드#

Playwright MCP는 페이지를 인식하는 두 가지 방식을 제공합니다. 기본값은 접근성 트리이며, 비전 모드는 --vision 플래그로 켭니다.

대부분의 자동화는 접근성 트리만으로 충분합니다. 시각적 디자인 판단이 꼭 필요할 때만 스크린샷(또는 비전 모드)을 곁들이는 것이 토큰과 안정성 면에서 유리합니다.

GitHub Actions에서 Playwright MCP 사용하기#

CI 환경에서도 Playwright MCP를 활성화할 수 있습니다. .github/workflows 파일에 아래처럼 설정합니다.

mcp_config: |
  {
    "mcpServers": {
      "playwright": {
        "command": "npx",
        "args": [
          "@playwright/mcp@latest",
          "--allowed-origins",
          "localhost:3000;cdn.tailwindcss.com"
        ]
      }
    }
  }

GitHub Actions 환경에서는 사용할 도구를 allowed_tools에 명시해야 합니다.

allowed_tools: "mcp__playwright__browser_snapshot,mcp__playwright__browser_click,mcp__playwright__browser_navigate"

자주 마주치는 함정#

처음 쓸 때 막히기 쉬운 지점들을 정리했습니다.

• 브라우저 바이너리 미설치 — 첫 실행 시 Chromium이 없으면 동작하지 않습니다. npx playwright install chromium으로 미리 받아두면 안전합니다.
• headed vs headless — 로컬에서 직접 화면을 보며 디버깅하려면 headed가 편하고, CI에서는 headless로 돌립니다. 서버에 디스플레이가 없으면 headless가 기본입니다.
• --allowed-origins 누락 — CI에서 외부 CDN(예: cdn.tailwindcss.com)을 못 불러오면 화면이 깨집니다. 접근 가능한 origin을 세미콜론(;)으로 나열해줘야 합니다.
• 세션 상태 공유 — 한 번 연 브라우저는 탭·쿠키·로그인 상태를 유지합니다. 테스트 간 격리가 필요하면 명시적으로 새 컨텍스트를 열거나 정리하세요.

실무에서는? 가장 흔한 첫 실패는 브라우저 미설치와 origin 제한입니다.
"왜 빈 화면만 캡처되지?" 싶을 땐 이 두 가지부터 확인하면 대부분 해결됩니다.

LLM + 브라우저가 열어주는 가능성#

Playwright MCP는 단순한 테스트 자동화 도구가 아닙니다.

• Web Agent — 웹을 탐색하며 정보를 수집하거나 작업을 수행하는 에이전트
• UI 회귀 테스트 — 코드 변경 후 시각적 차이를 LLM이 직접 감지
• 접근성 검사 — 실제 렌더링 결과를 보고 접근성 문제 파악
• E2E 테스트 생성 — 브라우저 조작 흐름을 관찰해 테스트 코드 작성

텍스트와 코드만 다루던 LLM이 브라우저를 도구로 얻으면서, 할 수 있는 일의 범위가 근본적으로 달라집니다.

정리#