Playwright MCP로 AI 에이전트에게 브라우저 자동화 맡기기

AI 코딩 에이전트를 쓰다 보면 “이 웹 페이지 좀 열어서 확인해줘”라고 말하고 싶을 때가 종종 있지 않나요? 배포한 사이트에 버그가 있는 것 같을 때, 특정 폼이 제대로 동작하는지 테스트하고 싶을 때, 혹은 경쟁사 사이트의 UI를 참고하고 싶을 때… 하지만 대부분의 AI 에이전트는 터미널 안에서만 동작하기 때문에 브라우저를 직접 다룰 수가 없습니다.

이 문제를 해결하는 것이 바로 Playwright MCP입니다. Microsoft에서 만든 이 MCP(Model Context Protocol) 서버를 AI 에이전트에 연결하면 브라우저를 열고 페이지를 탐색하고 버튼을 클릭하고 폼에 입력하는 작업을 자연어로 요청할 수 있게 됩니다.

이 글에서는 Playwright MCP가 어떻게 동작하는지 살펴보고 여러 MCP 클라이언트에 연결하는 방법과 실전 활용 팁까지 차근차근 알아보겠습니다.

Playwright MCP란?

Playwright MCP는 Playwright 브라우저 자동화 엔진을 MCP 서버로 감싼 것입니다. 쉽게 말해 AI 에이전트가 브라우저를 조종할 수 있게 해주는 중간 다리 역할이에요.

기존에 브라우저를 자동화하려면 Playwright 코드를 직접 작성해야 했습니다. 페이지를 열고 셀렉터로 요소를 찾고 클릭하고 결과를 확인하는 코드를 하나하나 짜야 했죠. 그런데 Playwright MCP를 사용하면 AI 에이전트에게 “로그인 페이지에서 이메일 입력하고 비밀번호 넣고 로그인 버튼 눌러줘”라고 말하기만 하면 됩니다.

여기서 핵심은 Playwright MCP가 스크린샷이 아니라 접근성 트리(accessibility tree)를 기반으로 동작한다는 점입니다. 접근성 트리란 웹 페이지의 DOM 구조를 역할(role), 이름(name), 상태(state)와 같은 정보로 정리한 것인데요. 보통 2~5KB 정도의 텍스트로 페이지 전체 구조를 표현할 수 있어서 비전 모델 없이도 정확하게 페이지를 이해하고 조작할 수 있습니다.

스크린샷 기반 접근 방식은 이미지를 분석해야 하니까 느리고 비용이 많이 드는 반면, 접근성 트리 기반은 빠르고 결정적(deterministic)이라서 같은 페이지에서 같은 작업을 시키면 항상 같은 결과가 나옵니다.

설치하기

Playwright MCP 서버를 사용하려면 Node.js 18 이상이 필요합니다. 그 외에는 별도 설치 과정 없이 npx로 바로 실행할 수 있어요.

Claude Code에서 설정

클로드 코드를 사용하고 있다면 터미널에서 한 줄만 실행하면 됩니다.

claude mcp add playwright -- npx -y @playwright/mcp@latest

이 명령어는 현재 프로젝트에 Playwright MCP 서버를 등록합니다. 이후 클로드 코드를 시작하면 자동으로 Playwright 서버가 함께 뜹니다.

팀 프로젝트에서 모든 개발자가 같은 설정을 공유하고 싶다면 프로젝트 루트에 .mcp.json 파일을 만들어 Git으로 관리하면 편해요. MCP 서버 설정에 관한 더 자세한 내용은 클로드 코드에서 MCP 서버 연동하기를 참고하세요.

.mcp.json

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

VS Code에서 설정

VS Code의 GitHub Copilot에서 Playwright MCP를 사용하려면 프로젝트의 .vscode/mcp.json 파일에 서버를 등록합니다.

.vscode/mcp.json

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

Cursor에서 설정

Cursor에서는 프로젝트의 .cursor/mcp.json 파일에 등록합니다.

.cursor/mcp.json

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

Claude Desktop에서 설정

Claude Desktop을 사용하고 있다면 설정 파일(claude_desktop_config.json)에 추가합니다.

claude_desktop_config.json

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

어떤 클라이언트를 쓰든 설정 패턴은 거의 동일합니다. npx @playwright/mcp@latest 명령어로 서버를 실행하는 것이 핵심이에요.

주요 도구 살펴보기

Playwright MCP 서버에는 AI 에이전트가 브라우저를 조작할 수 있는 20가지 이상의 도구가 있습니다. 크게 탐색, 상호작용, 관찰 세 가지로 나눌 수 있어요.

탐색 도구

탐색 도구는 브라우저에서 페이지를 오가는 기본적인 기능입니다.

browser_navigate는 가장 먼저 사용하게 될 도구로, 특정 URL로 이동합니다. browser_navigate_back으로 이전 페이지로 돌아갈 수도 있고, browser_tabs로 여러 탭을 관리할 수도 있어요.

상호작용 도구

실제로 페이지와 상호작용하는 도구가 여기에 속해요. AI 에이전트가 사람처럼 웹 페이지를 조작할 수 있게 해주는 도구예요.

browser_click은 페이지의 요소를 클릭하는데, 접근성 스냅샷에서 가져온 요소 참조(ref)와 사람이 읽을 수 있는 설명을 함께 전달해요. browser_type으로 입력 필드에 텍스트를 타이핑하고 browser_select_option으로 드롭다운에서 옵션을 선택할 수 있습니다.

browser_hover로 마우스를 올려 툴팁을 확인하거나 browser_drag로 드래그앤드롭을 수행하거나 browser_press_key로 Enter나 Escape 같은 키보드 입력을 보낼 수도 있어요. browser_file_upload로 파일 업로드까지 가능하고요.

browser_handle_dialog는 알림창(alert)이나 확인창(confirm) 같은 브라우저 다이얼로그를 처리합니다. “정말 삭제하시겠습니까?” 같은 확인 팝업이 뜨면 AI 에이전트가 대신 확인이나 취소 버튼을 눌러줄 수 있어요.

관찰 도구

페이지의 현재 상태를 파악하는 도구도 있습니다.

browser_snapshot은 페이지의 접근성 트리를 텍스트로 가져옵니다. AI 에이전트가 현재 페이지에 어떤 요소가 있는지 파악하고 다음 행동을 결정하는 데 가장 중요한 도구예요. browser_take_screenshot으로 페이지를 스크린샷으로 찍을 수도 있지만, 상호작용을 위해서는 반드시 browser_snapshot을 써야 합니다.

browser_console_messages로 브라우저 콘솔 로그를 확인하고, browser_network_requests로 네트워크 요청을 모니터링할 수 있어서 디버깅에도 유용합니다.

browser_evaluate는 브라우저에서 JavaScript를 직접 실행합니다. DOM 조작이나 데이터 추출 등 도구만으로 처리하기 어려운 작업에 활용할 수 있어요.

동작 원리

AI 에이전트에게 “example.com에 접속해서 Sign Up 버튼을 클릭해줘”라고 요청하면 어떤 일이 벌어질까요? 내부적으로는 이런 흐름으로 진행됩니다.

먼저 AI 에이전트가 browser_navigate를 호출해서 브라우저가 example.com으로 이동합니다. 페이지 로드가 완료되면 Playwright MCP 서버가 자동으로 접근성 스냅샷을 찍어서 AI 에이전트에게 돌려줍니다. 이 스냅샷에는 페이지의 모든 상호작용 가능한 요소 정보가 들어있어요.

접근성 스냅샷 (예시)

- heading "Example Domain" [ref=1]
- paragraph "This domain is for use in illustrative examples..."
- link "More information..." [ref=2]
- button "Sign Up" [ref=3]

AI 에이전트는 이 스냅샷을 분석해서 “Sign Up” 버튼의 참조값(ref=3)을 찾아내고, browser_click을 호출합니다. 클릭 후에 다시 스냅샷을 받아서 페이지가 어떻게 변했는지 확인하고, 필요한 다음 행동을 결정하는 식입니다.

이 과정이 반복되면서 AI 에이전트가 마치 사람처럼 웹 페이지를 탐색하게 됩니다. 개발자가 할 일은 자연어로 원하는 작업을 설명하는 것뿐이에요.

실전 활용 사례

Playwright MCP가 특히 유용한 상황을 몇 가지 살펴볼게요.

배포 후 확인

새 버전을 배포한 뒤 “production 사이트 열어서 메인 페이지 잘 뜨는지 확인해줘”라고 하면 AI 에이전트가 사이트를 방문해서 주요 요소가 정상적으로 렌더링되는지 확인해줍니다. 간단한 스모크 테스트를 자연어로 수행할 수 있는 거죠.

웹 스크래핑

문서 사이트에서 API 레퍼런스를 가져오거나 경쟁 서비스의 요금 체계를 정리할 때도 활용할 수 있습니다. “이 문서 페이지에서 모든 API 엔드포인트 목록을 가져와서 표로 정리해줘”라고 하면 페이지를 탐색하면서 데이터를 수집합니다.

폼 테스트

회원가입 폼이나 결제 폼이 제대로 동작하는지 테스트할 때 유용합니다. 필수 입력 필드를 비워두고 제출했을 때 적절한 에러 메시지가 나오는지, 올바른 데이터를 넣었을 때 성공하는지 등을 AI 에이전트가 직접 확인할 수 있어요.

시각적 디버깅

“이 페이지에서 모바일 뷰포트로 전환해서 네비게이션 메뉴가 어떻게 보이는지 스크린샷 찍어줘”처럼 시각적인 확인이 필요할 때도 도움이 됩니다. browser_resize로 뷰포트 크기를 변경한 뒤 browser_take_screenshot으로 스크린샷을 찍을 수 있으니까요.

로그인이 필요한 작업

브라우저가 눈에 보이는 상태로 열리기 때문에 로그인이 필요한 사이트에서도 활용할 수 있습니다. AI 에이전트에게 로그인 페이지를 열게 한 뒤, 직접 아이디와 비밀번호를 입력해서 로그인하고, 그 다음 작업을 AI에게 맡기면 됩니다. 세션 쿠키가 유지되니까 이후에는 인증된 상태에서 작업이 가능합니다.

설정 옵션

Playwright MCP 서버는 여러 명령줄 옵션으로 동작을 커스터마이즈할 수 있습니다.

브라우저 선택

기본적으로 Chrome이 사용되지만, 다른 브라우저를 지정할 수도 있습니다.

npx @playwright/mcp@latest --browser firefox

Chrome, Firefox, WebKit(Safari 엔진), Microsoft Edge를 지원합니다.

헤드리스 모드

CI/CD 환경이나 서버에서 실행할 때는 브라우저 창을 띄우지 않는 헤드리스 모드가 필요합니다.

npx @playwright/mcp@latest --headless

격리된 세션

기본적으로 Playwright MCP는 브라우저 프로필을 유지해서 로그인 상태나 쿠키가 세션 간에 보존됩니다. 매번 깨끗한 환경에서 시작하고 싶다면 --isolated 옵션을 사용하세요.

npx @playwright/mcp@latest --isolated

뷰포트 크기 지정

모바일 테스트 등을 위해 브라우저 창 크기를 지정할 수 있습니다.

npx @playwright/mcp@latest --viewport-size 375,812

저장된 인증 상태 불러오기

미리 저장해둔 쿠키와 로컬 스토리지를 불러와서 로그인된 상태로 시작할 수 있습니다.

npx @playwright/mcp@latest --storage-state auth.json

설정 파일로 관리

옵션이 많아지면 설정 파일로 관리하는 게 편합니다. JSON 파일에 모든 설정을 모아두고 --config 옵션으로 불러올 수 있어요.

playwright-mcp.config.json

{
  "browser": {
    "browserName": "chromium",
    "headless": false,
    "viewport": {
      "width": 1280,
      "height": 720
    }
  }
}

npx @playwright/mcp@latest --config playwright-mcp.config.json

MCP vs CLI: 언제 무엇을 쓸까?

Microsoft는 Playwright MCP 서버와 함께 @playwright/cli라는 CLI 도구도 제공합니다. 둘 다 브라우저 자동화를 가능하게 하지만 용도가 다릅니다.

MCP 서버는 브라우저 컨텍스트를 계속 유지하면서 여러 작업을 이어서 수행하는 데 적합합니다. 페이지를 열고 이리저리 탐색하고 여러 단계에 걸쳐 폼을 작성하는 것처럼 상태가 지속되어야 하는 시나리오에 유리해요.

CLI는 한 번에 하나의 작업을 수행하고 결과를 파일로 저장하는 방식입니다. 도구 스키마나 접근성 트리를 로드하지 않아서 토큰 소비가 약 4배 적습니다. 코딩 에이전트처럼 파일 시스템에 접근할 수 있는 환경에서 토큰 효율이 중요할 때 더 적합합니다.

정리하면, 장시간 브라우저를 열어두고 상호작용해야 하면 MCP를 쓰고, 스크린샷 한 장 찍거나 페이지 하나 확인하는 간단한 작업이면 CLI가 나을 수 있습니다.

알아두면 좋은 팁

Playwright MCP를 실무에서 잘 쓰기 위한 팁을 몇 가지 알려드릴게요.

처음 사용할 때 AI 에이전트가 Playwright MCP 도구를 인식하지 못하고 Bash로 Playwright를 실행하려고 할 수 있습니다. 이런 경우 “Playwright MCP를 사용해서”라고 명시적으로 언급해주면 됩니다. 한 번 올바른 도구를 사용하기 시작하면 이후에는 알아서 잘 선택합니다.

스크린샷(browser_take_screenshot)으로는 상호작용을 수행할 수 없습니다. 항상 browser_snapshot으로 접근성 트리를 먼저 가져오고, 거기서 얻은 요소 참조를 기반으로 클릭이나 입력을 해야 합니다. 스크린샷은 시각적 확인 용도로만 사용하세요.

인증이 필요한 사이트를 자주 테스트한다면 --storage-state 옵션으로 인증 상태를 파일로 저장해두는 것이 좋습니다. 매번 로그인 과정을 거치지 않아도 되니까요.

마치며

Playwright MCP를 사용하면 AI 에이전트의 활동 영역이 터미널에서 브라우저로 확장됩니다. 코드만 다루던 에이전트가 이제 웹 페이지도 탐색하고 조작할 수 있게 되는 거죠.

설치는 npx @playwright/mcp@latest 한 줄이면 끝납니다. Claude Code, VS Code, Cursor, Claude Desktop 등 대부분의 MCP 클라이언트에서 동일한 방식으로 설정할 수 있어요. 접근성 트리 기반이라 비전 모델 없이도 정확하게 동작하고 배포 확인부터 폼 테스트, 웹 스크래핑까지 여러 시나리오에 바로 적용할 수 있습니다.

아직 AI 에이전트에 MCP 서버를 연결해본 적이 없다면, MCP 서버 연동 가이드부터 시작해보세요. MCP의 기본 개념이 궁금하다면 Model Context Protocol 소개도 함께 읽어보시면 좋겠습니다.

This work is licensed under CC BY 4.0