Playwright MCP Server 설정 방법 (2026)

Playwright MCP 서버 설정 방법 (2026)

Playwright MCP 서버를 사용하면 AI 어시스턴트가 실제 브라우저를 제어할 수 있습니다. 페이지 이동, 요소 클릭, 폼 채우기, 스크린샷 캡처 및 엔드투엔드(E2E) 테스트 실행이 가능해집니다. 화면에 보이는 내용을 설명하는 대신, AI가 Model Context Protocol을 통해 웹 페이지와 직접 상호작용할 수 있습니다.

이 가이드에서는 Playwright MCP 서버를 설정하고 이를 Claude Desktop, Cursor, VS Code 및 Claude Code에 연결하는 방법을 단계별로 안내합니다.

Playwright MCP 서버란 무엇인가요?

Playwright MCP 서버는 Microsoft의 Playwright 브라우저 자동화 라이브러리를 MCP 호환 인터페이스로 래핑한 것입니다. AI 어시스턴트에 연결되면 다음과 같은 도구들이 AI에게 노출됩니다:

• URL로 이동 및 페이지 요소와 상호작용
• 버튼 클릭, 입력 필드 작성, 옵션 선택
• 전체 페이지 또는 특정 요소의 스크린샷 캡처
• 텍스트 콘텐츠 및 페이지 구조 추출
• 브라우저 컨텍스트에서 JavaScript 실행
• 인증 흐름 및 다중 페이지 워크플로우 처리

왜 수동 테스트 대신 Playwright MCP를 사용해야 하나요?

접근 방식	속도	정확도	AI 통합	설정
Playwright MCP + AI	빠름	높음	네이티브 지원	보통
수동 브라우저 테스트	느림	높음	없음	없음
스크린샷 + AI	빠름	낮음-보통	간접적	없음
Selenium 스크립트	보통	높음	없음	높음
Cypress	보통	높음	없음	보통

사전 요구 사항

요구 사항	상세 내용
Node.js	v18 이상
npm 또는 yarn	MCP 서버 설치용
MCP 호환 클라이언트	Claude Desktop, Cursor, Cline 또는 Claude Code
Chromium	Playwright가 자체 번들 브라우저를 설치함

1단계: Playwright MCP 서버 설치

공식 Playwright MCP 서버는 Microsoft에서 관리합니다. 전역으로 설치하거나 npx를 사용하여 직접 실행할 수 있습니다.

# 옵션 1: npx로 직접 실행 (권장)
npx @playwright/mcp@latest

# 옵션 2: 전역 설치
npm install -g @playwright/mcp

처음 실행할 때 Playwright가 브라우저 바이너리(Chromium, Firefox, WebKit)를 다운로드합니다. 이 과정은 잠시 시간이 소요될 수 있습니다.

브라우저를 수동으로 설치하려면 다음 명령어를 사용하세요:

npx playwright install

2단계: Claude Desktop 설정

Claude Desktop 설정 파일에 Playwright MCP 서버를 추가합니다.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Claude Desktop을 재시작하세요. MCP 도구를 사용할 수 있음을 나타내는 망치 아이콘이 표시되어야 합니다.

헤드 모드(Headed Mode)로 실행 (브라우저 가시화)

기본적으로 Playwright는 헤드리스(headless, 브라우저 창이 보이지 않음) 모드로 실행됩니다. 디버깅을 위해 브라우저를 확인하려면 다음과 같이 설정하세요:

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

브라우저 지정하기

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

지원되는 값: chromium (기본값), firefox, webkit.

3단계: Cursor 설정

Cursor 설정에서 Playwright MCP 서버를 추가하거나 프로젝트 루트에 .cursor/mcp.json 파일을 생성하세요:

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

Cursor 설정 > MCP 메뉴에서 서버가 연결되었는지 확인합니다.

4단계: Cline 설정 (VS Code)

Cline 확장 프로그램 설정에서 MCP Servers 섹션으로 이동하여 다음을 추가합니다:

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

Cline은 새 대화를 시작할 때 사용 가능한 도구들을 자동으로 감지합니다.

5단계: Claude Code 설정 (CLI)

Claude Code의 경우, 전역 MCP 설정에 Playwright MCP 서버를 추가하거나 명령줄을 통해 전달합니다.

# MCP 설정을 직접 전달
claude --mcp-config playwright-mcp.json

playwright-mcp.json 파일을 생성합니다:

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

또는 지속적인 액세스를 위해 ~/.claude/mcp_servers.json에 추가합니다:

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

사용 가능한 MCP 도구

Playwright MCP 서버는 AI 어시스턴트에게 다음과 같은 도구들을 제공합니다:

도구	설명
browser_navigate	URL로 이동
browser_click	페이지의 요소 클릭
browser_fill	입력 필드에 텍스트 입력
browser_screenshot	페이지 스크린샷 캡처
browser_select	드롭다운 옵션 선택
browser_hover	요소 위로 마우스 커서 올리기
browser_press_key	키보드 키 누르기
browser_get_text	요소에서 텍스트 콘텐츠 추출
browser_evaluate	페이지 내에서 JavaScript 실행
browser_wait	요소가 나타날 때까지 대기
browser_close	브라우저 닫기

실제 활용 사례

웹 애플리케이션 테스트

http://localhost:3000/login으로 이동해서 로그인 흐름을 테스트해줘:
1. 이메일 필드에 "test@example.com" 입력
2. 비밀번호 필드에 "password123" 입력
3. "Sign In" 버튼 클릭
4. 대시보드가 로드되었는지 확인하기 위해 스크린샷 캡처
5. 환영 메시지에 "Welcome, Test User"라고 나오는지 확인

AI는 Playwright MCP 도구를 사용하여 각 단계를 실행하고 결과를 보고합니다.

문서 스크래핑

https://platform.openai.com/docs/api-reference/chat/create 페이지로 이동해서
모든 요청 매개변수, 타입, 설명을 추출해줘.
추출한 내용을 TypeScript interface 형식으로 작성해줘.

시각적 회귀 테스트(Visual Regression Testing)

http://localhost:3000으로 이동해서 다음 항목들의 스크린샷을 찍어줘:
1. 홈페이지 히어로 섹션
2. 가격 페이지
3. 로그인 페이지
4. 대시보드 (테스트 계정으로 로그인 후)

각 스크린샷을 디자인 사양과 비교하고 시각적인 차이점이 있다면 보고해줘.

자동화된 폼 테스트

http://localhost:3000/signup으로 이동해서 폼 유효성 검사를 테스트해줘:
1. 빈 폼을 제출하고 에러 메시지를 스크린샷으로 찍어줘
2. 잘못된 이메일을 입력하고 유효성 검사 확인
3. 8자 미만의 비밀번호를 입력하고 확인
4. 모든 항목을 올바르게 채운 뒤 성공적으로 제출되는지 확인

고급 설정

사용자 지정 유저 데이터 디렉토리 사용

실행 간에 쿠키와 세션을 유지하려면 다음과 같이 설정하세요:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--user-data-dir", "/tmp/playwright-mcp-data"
      ]
    }
  }
}

사용자 지정 뷰포트 설정

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

Playwright 테스트 코드 생성

AI에게 앱과 상호작용하게 한 뒤, 재사용 가능한 Playwright 테스트 스크립트를 생성하도록 요청하는 강력한 워크플로우를 구성할 수 있습니다.

http://localhost:3000/shop에서 결제 흐름을 따라 이동해줘:
1. 장바구니에 제품 추가
2. 결제 페이지 이동
3. 배송 정보 입력
4. 구매 완료

그 다음, CI/CD를 위해 이 전체 흐름을 자동화하는 Playwright 테스트 파일(checkout.spec.ts)을 생성해줘.

AI는 MCP 도구를 사용해 앱과 상호작용하며 학습한 내용을 바탕으로 적절한 Playwright 테스트 코드를 작성합니다.

문제 해결

"Browser failed to launch" (브라우저 실행 실패): npx playwright install을 실행하여 브라우저 바이너리가 다운로드되었는지 확인하세요. Linux에서는 npx playwright install-deps를 통해 시스템 종속성을 추가로 설치해야 할 수도 있습니다.

"Element not found" (요소를 찾을 수 없음) 에러: 웹 페이지 로딩에 시간이 걸릴 수 있습니다. AI에게 요소를 조작하기 전에 browser_wait을 사용하도록 요청하세요. 동적인 SPA는 명시적인 대기 시간이 필요한 경우가 많습니다.

스크린샷이 공백이거나 검게 나옴: 지정된 시스템의 헤드리스 모드에서 발생할 수 있는 현상입니다. --headed 모드로 실행하여 디버깅하거나 GPU 드라이버가 최신 버전인지 확인하세요.

높은 메모리 사용량: Playwright 브라우저 인스턴스는 메모리를 소모합니다. 세션 사이에 browser_close를 사용하여 브라우저를 닫으세요. 동시에 많은 탭을 여는 것을 피하십시오.

시간 초과 후 MCP 서버 연결 끊김: 일부 MCP 클라이언트에는 유휴 시간 초과(idle timeout) 설정이 있습니다. 브라우저가 오랫동안 유휴 상태였다면 서버 연결이 끊길 수 있습니다. 대화를 새로 시작하여 다시 연결하세요.

마치며

Playwright MCP 서버는 AI 어시스턴트와 실제 브라우저 상호작용 사이의 간극을 메워줍니다. 스크린샷을 설명하거나 수동으로 테스트를 실행하는 대신, AI가 직접 웹 애플리케이션을 탐색하고 조작하며 검증할 수 있습니다. 여기에 AI가 생성한 테스트 스크립트까지 결합하면 개발과 QA 모두에 강력한 워크플로우가 완성됩니다.

이미지, 비디오 또는 말하는 아바타와 같은 AI 생성 미디어를 다루는 프로젝트라면, 종량제 요금제로 모든 미디어 생성을 처리하는 통합 API인 Hypereal AI를 확인해 보세요.

Hypereal AI 무료 체험하기 -- 35 크레딧 제공, 신용카드 불필요.