Claude Code와 Playwright MCP 사용 방법: 완벽한 설정 가이드

Playwright MCP란 무엇인가요?

Playwright MCP 서버는 모든 Model Context Protocol 클라이언트에 브라우저 자동화 기능을 제공합니다. AI에 픽셀을 “보도록” 요청하는 대신, 서버는 페이지의 구조화된 접근성 스냅샷을 반환하고 모델은 참조 ID로 요소와 상호작용합니다. 이는 루프를 빠르고, 결정론적이며, 비전 모델 오버헤드가 없게 만듭니다. VS Code, Cursor, Windsurf, Claude Desktop, Claude Code 및 다른 모든 MCP 클라이언트와 함께 작동합니다.

Claude Code의 경우, 이는 터미널의 에이전트가 이제 브라우저를 열고, 클릭하고, 양식을 작성하고, 네트워크 요청을 모의할 수 있으며, 스크린샷을 캡처하고, 심지어 사용자 정의 Playwright 스크립트를 실행할 수 있다는 의미입니다 — 모두 자연어 프롬프트에서 제어됩니다.

사전 요구사항

시작하기 전에 다음이 있는지 확인하세요:

• Node.js 18 이상 설치됨
• Claude Code 설치 및 로그인됨 (터미널에서 claude 실행하여 확인)
• 편하게 작업할 수 있는 터미널

그것이 전부입니다 — Playwright MCP는 첫 실행 시 자체 브라우저 바이너리를 다운로드합니다.

비즈니스 성장 준비가 되셨나요?

오늘 무료 평가판을 시작하고 며칠 내로 결과를 확인하세요.

데모 요청 로그인

Playwright MCP 통합 설정

Playwright MCP를 Claude Code에 연결하는 것은 한 줄의 명령입니다. 다음 단계에 따라 설정하세요:

Playwright MCP 서버 추가

터미널을 열고 다음을 실행하세요:

claude mcp add playwright npx @playwright/mcp@latest

이는 Claude Code가 브라우저 도구가 필요할 때마다 npx를 통해 시작하는 playwright라는 새로운 MCP 서버를 등록합니다. 첫 번째 호출은 패키지와 필요한 브라우저 바이너리를 다운로드하므로 첫 번째에는 시간을 주세요.

연결 확인

새로운 Claude Code 세션을 시작하고 /mcp 명령을 실행하세요:

claude

/mcp

playwright가 연결된 서버로 나열되어 있고, 노출된 도구 (탐색, 클릭, 입력, 스크린샷, 네트워크 모의 등)를 확인해야 합니다.

선택사항: 대신 JSON 구성 사용

구성 파일을 직접 편집하려면 표준 MCP 형식을 사용하여 동일한 서버를 ~/.claude.json (또는 프로젝트 범위 .mcp.json)에 추가할 수 있습니다:

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

파일을 편집한 후 Claude Code를 다시 시작하면 서버가 /mcp에 나타납니다.

Claude Code에서 첫 번째 브라우저 자동화

서버가 연결되면 프롬프트는 이제 실제 브라우저를 제어할 수 있습니다. Playwright 문서의 정규적인 첫 상호작용을 시도하세요:

https://demo.playwright.dev/todomvc로 이동하여 몇 가지 할 일 항목을 추가하세요.

Claude Code는 브라우저를 열고 페이지의 접근성 스냅샷을 요청하고 요소 참조로 입력을 찾고 각 할 일을 입력하고 터미널의 결과를 확인합니다.

어느 브라우저가 열리는지에 대한 주의: 기본적으로 이는 headed 모드에서 Chromium을 시작합니다. 이를 변경하려면 MCP 구성의 args에 플래그를 추가하고 Claude Code를 다시 시작하세요: 창을 숨기려면 --headless 또는 엔진을 전환하려면 --browser=firefox|webkit|msedge.

접근성 스냅샷이 작동하는 방식

Playwright MCP 도구가 실행되면 픽셀 대신 페이지의 구조화된 스냅샷 — 요소 역할, 텍스트 내용 및 참조 ID를 반환합니다. Claude는 스냅샷을 읽고 ref=e5와 같은 참조를 사용하여 텍스트 상자에 입력하거나 ref=e10을 사용하여 체크박스를 전환합니다. 픽셀 푸싱 없음, 취약한 CSS 선택자 없음 — 모델이 추론할 수 있는 구조화된 페이지 상태만 있습니다.

뉴스레터 가입

최신 팁, 트렌드 및 특가 정보를 무료로 받아보세요.

이메일 주소

구독

Claude Code에서 사용할 수 있는 핵심 기능

Playwright MCP가 연결되면 팀원에게 줄 같은 프롬프트가 Claude Code에서 작동합니다:

• 탐색: “example.com으로 이동”, “뒤로 가기”, “페이지 새로고침”.
• 클릭 및 입력: “제출 버튼 클릭”, “이메일 필드에 test@example.com 입력”.
• 스크린샷: “가격 책정 섹션의 스크린샷 캡처”.
• 키보드 및 마우스: 키 누르기, 마우스 오버, 드래그 앤 드롭.
• 탭 및 대화상자: 새 탭 열기, 탭 간 전환, 팝업 수락 또는 거부.
• 네트워크 모니터링: “페이지 로드 이후 만들어진 요청 나열”.
• API 모의: “/api/users 엔드포인트를 모의하여 빈 배열 반환”.
• 저장소 상태: 인증된 세션을 파일에 저장하고 나중에 다시 로드합니다.

단일 도구 호출 이상이 필요한 워크플로우의 경우 Claude Code에 browser_run_code를 호출하고 Playwright 스크립트를 인라인으로 실행하도록 요청할 수 있습니다 — 어설션, 데이터 추출 또는 몇 줄의 명령형 코드의 이점을 얻을 수 있는 모든 것에 유용합니다.

유용한 구성 옵션

Playwright MCP에는 알아두면 좋은 몇 가지 플래그가 있습니다. 구성의 args 배열에 추가하거나 claude mcp add 명령 뒤에 --를 추가하세요.

헤드리스 모드

브라우저는 기본적으로 headed 모드로 실행되므로 무슨 일이 일어나고 있는지 볼 수 있습니다. 헤드리스로 실행하려면 — CI 또는 원격 셸에 유용 — --headless를 전달하세요:

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

브라우저 선택

--browser 플래그로 엔진을 전환하세요. 지원되는 값은 chrome, firefox, webkit 및 msedge입니다:

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

프로필 모드

Playwright MCP는 세 가지 프로필 모드를 지원합니다:

• 지속적 (기본값): 로그인 상태 및 쿠키가 세션 간에 유지됩니다.
• 격리됨: --isolated를 전달하여 각 세션을 새로 시작하고, 선택적으로 --storage-state로 시드합니다.
• 브라우저 확장: --extension을 전달하여 Playwright MCP Bridge 확장을 통해 기존 브라우저 탭에 연결합니다.

독립형 HTTP 서버

디스플레이가 연결되지 않은 곳 (또는 IDE 워커에서)에 headed 브라우저를 실행해야 하는 경우 서버를 별도로 시작하고 HTTP를 통해 연결합니다.

두 번째 터미널을 열기 — 전체 세션 동안 열어두기 — 그곳에서 서버를 시작하세요:

npx @playwright/mcp@latest --port 8931

터미널을 열어두세요. 이것이 localhost:8931에서 브라우저를 노출하므로 자신의 브라우저에서 세션을 볼 수 있고 Claude Code가 연결할 수 있는 것입니다. 터미널을 닫으면 서버가 종료됩니다.

그런 다음 Claude Code를 실행하는 터미널에서 구성을 업데이트하여 엔드포인트를 가리키세요:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

훔칠 가치가 있는 실용적인 워크플로우

Playwright MCP가 연결되면 Claude Code는 엔드 투 엔드 테스트 스캐폴딩, 버그 재현, API 모의 확인, 페이지 감사 및 릴리스 스모크 테스트를 처리할 수 있습니다 — 브라우저를 제어하고 다시 보고하는 모든 것.

이러한 프롬프트가 실제로 작동하게 하는 두 가지가 있습니다. 첫째, 프로젝트 루트의 CLAUDE.md는 스테이징 URL, 데모 자격증명 및 에이전트가 따라야 할 모든 규칙을 문서화합니다 — 없으면 “데모 사용자로 로그인"은 고정할 것이 없습니다. 둘째, Claude Code가 이슈 또는 티켓에서 컨텍스트를 가져오려면 두 번째 MCP 서버를 연결하세요 — GitHub MCP 서버 가 일반적인 선택입니다. 둘 다 건너뛰면 Claude Code는 (합리적으로) 이슈 #482가 무엇인지 물어봅니다.

Claude Code와 Playwright MCP를 쌍으로 사용하는 이유는 무엇인가요?

몇 가지 이유가 이 조합을 이기기 어렵게 만듭니다:

• 터미널 네이티브: 모든 것이 이미 작업하는 곳에서 발생합니다. 별도의 테스트 러너로 컨텍스트 전환 없음.
• 접근성 우선: 스냅샷은 속도와 신뢰성에서 스크린샷을 이기며, 비전 모델 없이 작동합니다.
• 실제 Playwright 기반: Playwright로 코드에서 할 수 있는 모든 것을 여기서 할 수 있습니다 — 멀티 브라우저, 네트워크 모의, 저장소 상태 등.
• 다른 MCP 서버와 조합 가능: Playwright를 GitHub, 데이터베이스 또는 모니터링 MCP 서버와 함께 스택하고 Claude Code는 모두에서 엔드 투 엔드로 작업을 이동할 수 있습니다.
• 개방형 표준: MCP는 휴대 가능합니다. 동일한 Playwright 서버는 클라이언트를 전환하면 Cursor, VS Code, Windsurf 및 Claude Desktop에서 작동합니다.

서버를 추가하고 /mcp를 실행하여 확인하고 다음 “로그인 페이지를 테스트하러 가기” 프롬프트는 실제 브라우저 세션이 됩니다 — Claude Code에 의해 제어되고, headed 모드에서 감시되거나 (또는 감시되지 않음) 접근성 스냅샷을 통해 검증 가능합니다.