Playwright MCP 서버는 AI 에이전트나 자연어 기반 자동화 툴이 브라우저를 제어할 수 있도록 해주는 MCP(Model Context Protocol) 서버입니다.
- Playwright 기반 브라우저 자동화 기능을 자연어 명령으로 실행할 수 있게 중간 브릿지 역할을 수행합니다.
- Claude Desktop, Cursor, VS Code 등과 함께 활용되며 LLM(대형 언어 모델) 기반 브라우저 자동화를 가능하게 합니다.
환경 구축 및 설치 방법
1. Node.js 설치
Playwright MCP 서버는 Node.js 기반으로 동작합니다.
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# 버전 확인
node -v
npm -v
2. Playwright MCP 서버 설치
npm install -g @executeautomation/playwright-mcp-server
- 전역(global) 설치로 명령어가 시스템 전체에서 사용 가능
- 설치 후 MCP 서버가
npx
로 실행됩니다.
MCP 서버 연동 설정
1. Claude Desktop 예시
claude_desktop_config.json
설정파일에서 MCP 서버 등록
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@executeautomation/playwright-mcp-server"]
}
}
- 파일 수정 후 Claude Desktop 재시작
- UI 상에서 MCP 연결 상태 확인 가능 (초록불 → 정상 연결)
2. VS Code, Cursor 등
설정 파일(mcp.json
) 또는 확장 설정에서 MCP 서버 추가
{
"playwright": {
"command": "npx",
"args": ["-y", "@executeautomation/playwright-mcp-server"]
}
}
npx 실행 시 Playwright 브라우저 자동 설치 및 실행이 함께 진행됩니다.
활용 사례 및 자동화 흐름
대표 기능
기능 | 설명 |
---|---|
웹사이트 탐색 | 자연어 명령으로 특정 URL 접속 |
입력 자동화 | 로그인 폼, 검색창 등 자동 입력 |
클릭 | 버튼, 메뉴 등 클릭 시뮬레이션 |
스크린샷 | 브라우저 화면 저장 |
E2E 테스트 | 시나리오 기반 사용자 행동 테스트 |
스크롤/탭 전환 | 복잡한 UX도 제어 가능 |
실전 예시 시나리오
사용자 명령 | 동작 예시 |
---|---|
“demo.playwright.dev/todomvc로 이동해줘” | 브라우저 열고 해당 사이트 접속 |
“할 일 항목에 ‘회의 준비’ 추가해줘” | 입력 도구로 텍스트 입력 |
“첫 번째 항목 체크해줘” | 체크박스 클릭 자동화 |
“스크린샷 찍어서 저장해줘” | 이미지 파일 저장 |
Claude, Copilot, GPT 등 LLM과 결합하면 “말로 하는 자동화”가 실현됩니다.
보안 체크리스트
Playwright MCP 서버는 실제 브라우저 제어 기능을 갖추고 있으므로, 보안 위험에 주의해야 합니다.
항목 | 점검 포인트 |
---|---|
접근 제어 | 로컬 또는 제한된 네트워크에서만 MCP 포트를 개방할 것 |
명령 제한 | LLM이 실행 가능한 명령을 제한하거나 승인 후 실행 구조 채택 |
세션 격리 | 브라우저 세션은 자동화마다 별도 인스턴스로 실행 |
로그 감사 | 어떤 명령이 언제 실행되었는지 로그 기록 필수 |
리소스 제한 | 무한 스크롤, 무한 반복 등 방지 설정 필요 (e.g. max step count) |
브라우저 자동화 코드 예시
자연어 명령 없이 직접 자동화 코드로도 MCP 서버를 활용할 수 있습니다.
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://demo.playwright.dev/todomvc');
await page.fill('.new-todo', '보안 점검');
await page.press('.new-todo', 'Enter');
await page.screenshot({ path: 'todo.png' });
await browser.close();
})();
이 코드를 MCP 서버가 내부적으로 실행하도록 유도할 수 있으며, LLM이 코드를 생성하게 할 수도 있습니다.
참고 자료 정리
구분 | 요약 |
---|---|
목적 | AI/LLM 기반 브라우저 자동화를 위한 MCP 브릿지 |
설치 | Node.js + @executeautomation/playwright-mcp-server |
연동 | Claude, VS Code, Cursor 등에서 설정 추가 |
기능 | URL 탐색, 입력, 클릭, 스크린샷, 자동화 테스트 등 |
보안 | 접근제한, 실행 로그, 세션 격리, 명령 검증 필요 |
아래는 LLM과 웹 자동화를 연결하는 새로운 방식! 공식 Playwright MCP입니다. OpenAI 등 LLM 기반 도구들이 웹 페이지와 구조적으로 상호작용할 수 있도록 해주는 브라우저 자동화 서버입니다. 기존처럼 스크린샷 기반이 아닌, 접근성 스냅샷(Accessibility Tree) 을 사용하기 때문에 더 가볍고, 빠르며, 정확합니다.
즉, 화면을 "보는" 것이 아니라, DOM 구조를 이해하고 조작합니다.
항목 | 설명 |
---|---|
✅ 빠르고 경량 | 스크린샷 불필요. Playwright의 접근성 트리 사용 |
✅ 시각모델 불필요 | GPT 등 LLM에 최적화된 구조적 데이터만 사용 |
✅ 명확한 동작 | UI 요소 위치 기반 클릭보다 신뢰성 높음 |
✅ 다양한 브라우저 지원 | Chromium, Firefox, WebKit, Edge 등 가능 |
공식 MCP 설치 및 시작하기
1️⃣ 요구 사항
- Node.js 18 이상
- MCP 지원 클라이언트: VS Code / Cursor / Claude Desktop / Windsurf 등
2️⃣ 설치 예시
.vscode/settings.json
또는 MCP 지원 도구에서 다음처럼 설정
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
3️⃣ 실행
npx @playwright/mcp@latest
👉 이 명령어로 MCP 서버가 실행되며, LLM 도구에서 이를 통해 웹에 접근하게 됩니다.
주요 설정 옵션
옵션 | 설명 |
---|---|
--headless |
브라우저를 백그라운드에서 실행 |
--browser chrome |
사용할 브라우저 지정 |
--port 8931 |
서버가 열릴 포트 지정 |
--isolated |
매 세션마다 프로필 초기화 (로그인 정보 저장 안함) |
--storage-state=경로 |
초기 로그인 상태 불러오기 |
--user-data-dir=경로 |
사용자 프로필 위치 지정 |
--vision |
접근성 트리 대신 스크린샷 기반 상호작용 (Vision Mode) |
💡 설정 파일로도 가능
npx @playwright/mcp@latest --config ./my-mcp-config.json
작동 원리
Snapshot Mode (기본값)
- DOM 구조와 접근성 트리를 기반으로 웹 요소 식별
ref
,element
등의 키값으로 클릭/입력 수행
Vision Mode (옵션)
- 마우스 좌표(x, y) 기반으로 스크린샷 처리
- 시각적 위치 기반 자동화 (LLM이 좌표 사용 가능할 때 적합)
지원 명령어 (인터페이스)
📄 페이지 정보
명령어 | 설명 |
---|---|
browser_snapshot |
페이지의 접근성 트리 구조 캡처 |
browser_take_screenshot |
화면 스크린샷 저장 (행동은 불가) |
browser_pdf_save |
페이지를 PDF로 저장 |
browser_network_requests |
네트워크 요청 목록 조회 |
browser_console_messages |
콘솔 메시지 조회 |
🖱️ 사용자 동작
동작 | 명령어 |
---|---|
클릭 | browser_click |
입력 | browser_type |
드래그 | browser_drag |
드롭다운 선택 | browser_select_option |
키보드 입력 | browser_press_key |
대기 | browser_wait_for |
🌐 탐색
동작 | 명령어 |
---|---|
URL 이동 | browser_navigate |
이전/다음 페이지 | browser_navigate_back , browser_navigate_forward |
🗂️ 탭 관리
동작 | 명령어 |
---|---|
탭 열기 | browser_tab_new |
탭 전환 | browser_tab_select |
탭 닫기 | browser_tab_close |
🧪 테스트 코드 생성
동작 | 명령어 |
---|---|
Playwright 테스트 생성 | browser_generate_playwright_test |
💾 사용자 프로필
모드 | 설명 |
---|---|
Persistent | 로그인 정보와 세션을 디스크에 저장 (기본값) |
Isolated | 매 세션 초기화 (테스트 시 유용) |
💡 디스크 경로는 OS별로 아래와 같습니다.
OS | 경로 |
---|---|
Windows | %USERPROFILE%\AppData\Local\ms-playwright\mcp-chrome-profile |
macOS | ~/Library/Caches/ms-playwright/mcp-chrome-profile |
Linux | ~/.cache/ms-playwright/mcp-chrome-profile |
🐳 Docker에서 실행
npx @playwright/mcp@latest --port 8931
👉 클라이언트에서 연결
{
"mcpServers": {
"playwright": {
"url": "http://localhost:8931/sse"
}
}
}
✨ 활용 사례
시나리오 | 설명 |
---|---|
🔍 웹 UI 테스트 자동화 | 테스트 시나리오를 LLM이 직접 작성, 수행 |
🧭 LLM 웹 조작 | 버튼 클릭, 양식 입력, PDF 다운로드 등 자동화 |
🧪 QA/CI 통합 | Playwright 테스트를 자동 생성하여 코드에 삽입 |
👁️ Vision Mode 학습 | LLM이 화면 기반 마우스 좌표로 행동 가능 시 활용 |
댓글