설치 매뉴얼
개요
Playwright 앱은 쿼리 명령어로 웹 브라우저를 조작합니다. API를 제공하지 않는 사이트를 에이전트나 운영자가 화면으로 읽고 조작할 수 있습니다. 브라우저는 소나 호스트에서 실행되지 않습니다. 별도의 Playwright MCP 서버에서 실행되고, 이 앱은 그 서버와 MCP(HTTP 기반 JSON-RPC)로 통신합니다.
소나 (playwright 앱)
| MCP over HTTP <- 앱은 이 프로토콜만 말한다
v
Playwright MCP 서버 (별도 호스트 또는 컨테이너)
|__ Chromium + 시스템 라이브러리
| HTTPS
v
대상 웹사이트
따라서 앱 설치는 두 부분입니다. MCP 서버를 설치하는 일과, 그 위치를 소나에 알려주는 일입니다. 소나 호스트에는 Node.js도 Chromium도 설치하지 않습니다.
아래 순서대로 진행하세요.
- 파일 스토어 앱이 설치되어 있지 않다면 먼저 설치합니다.
- Playwright MCP 서버를 설치합니다 — 아래 리눅스 또는 윈도우.
- 서버를 접속 프로파일 또는 시스템 프로퍼티로 소나에 등록합니다.
- 로그인이 필요한 사이트마다 자격증명 프로파일을 등록합니다. 계정이 필요 없는 사이트는 이 단계가 필요하지 않습니다.
적용 범위
모든 조작이 스크린샷을 저장하므로 이 앱이 없으면 시작되지 않습니다.
쿼리 명령어와 REST API 모두 관리자(클러스터 관리자 또는 회사 관리자)를 요구하고, 그 위에서
접속 프로파일 권한으로 대상 범위가 다시 좁혀집니다.
요구 사항
| 항목 | 요구사항 | 비고 |
|---|---|---|
| 소나 버전 | 5.0.2603.0 이상 | |
| 선행 앱 | 파일 스토어 | 스크린샷 저장용. 없으면 앱이 시작되지 않습니다 |
| MCP 서버 호스트 | 리눅스(도커 권장) 또는 윈도우 | Chromium이 이곳에서 실행됩니다 |
| 네트워크 허용 | TCP/8931 (소나 → MCP 서버, Outbound) | 방화벽 정책 반영 필요 |
| 네트워크 허용 | HTTPS (MCP 서버 → 대상 사이트, Outbound) | 사이트에 접속하는 주체는 서버이며 소나가 아닙니다 |
| 권한 | 관리자(클러스터 관리자 또는 회사 관리자) | 쿼리 명령어와 REST API 모두 동일 |
리눅스에 MCP 서버 설치
도커를 권장합니다. 이미지에 Chromium과 그것이 요구하는 시스템 공유 라이브러리가 이미 들어 있는데, 그 부분이 직접 설치할 경우 root 권한 패키지 설치를 요구하는 대목입니다.
docker run -d --name playwright-mcp --restart unless-stopped \
-p 8931:8931 \
mcr.microsoft.com/playwright/mcp \
--port 8931 --host 0.0.0.0 --allowed-hosts sonar-host \
--headless --isolated \
--ignore-https-errors --output-dir /tmp/playwright-mcp
sonar-host는 소나 호스트가 이 서버에 접속할 때 사용할 호스트명이나 주소로 바꿉니다. 아래 Host 헤더 검증을 참고하세요. 설치 시 가장 자주 틀리는 옵션입니다.
도커를 쓸 수 없으면 Node.js LTS를 설치하고 서버를 직접 실행합니다. 이 경우 Chromium이 요구하는 공유 라이브러리를 호스트에서 먼저 충족해야 하며, 최소 이미지에서는 별도 설치가 필요합니다.
npx --yes @playwright/mcp@latest install chromium
npx --yes @playwright/mcp@latest --port 8931 --host 0.0.0.0 \
--allowed-hosts sonar-host --headless --isolated \
--ignore-https-errors --output-dir /var/lib/playwright-mcp
상시 운영은 셸에 띄워 두지 말고 systemd 유닛으로 등록하세요.
윈도우에 MCP 서버 설치
도커 단계가 없습니다. 윈도우 Chromium은 필요한 라이브러리를 자체 포함하므로 관리자 권한 패키지 설치가 없습니다.
# 1) Node.js LTS 설치 후 브라우저 설치
npx --yes @playwright/mcp@latest install chromium
# 2) 서버 실행
npx --yes @playwright/mcp@latest --port 8931 --host 0.0.0.0 --allowed-hosts sonar-host --headless --isolated --ignore-https-errors --output-dir C:\playwright-mcp
상시 운영은 윈도우 서비스로 등록합니다. 예를 들어 NSSM을 사용합니다.
nssm install playwright-mcp "C:\Program Files\nodejs\npx.cmd" "--yes @playwright/mcp@latest --port 8931 --host 0.0.0.0 --allowed-hosts sonar-host --headless --isolated --ignore-https-errors --output-dir C:\playwright-mcp"
nssm start playwright-mcp
서버 옵션
| 옵션 | 필요한 이유 |
|---|---|
| --headless | 화면 없는 서버에서 실행합니다. |
| --isolated | 세션마다 빈 프로필로 시작합니다. 이것을 빼면 로그인 쿠키가 서버 디스크에 남고, 그 파일이 저장된 자격증명과 동등해집니다. |
| --ignore-https-errors | 자체서명 인증서를 쓰는 사이트에는 사실상 필수입니다. 이 옵션이 없으면 그런 콘솔은 ERR_CERT_AUTHORITY_INVALID로 접속 자체가 실패합니다. |
| --output-dir | 서버가 자체 스크린샷 파일을 떨어뜨리는 위치입니다. 앱은 응답에 실려 오는 이미지를 파일 스토어에 저장하므로 이 디렉토리는 임시 용도이며 비워도 됩니다. |
| --host / --allowed-hosts | --host는 바인딩 주소, --allowed-hosts는 허용할 Host 헤더 목록입니다. 원격 접속에는 둘 다 필요합니다. 아래를 참고하세요. |
Host 헤더 검증
서버는 Host 헤더를 검사하며 기본값은 바인딩한 호스트명뿐입니다. --host 0.0.0.0만으로는 부족합니다. 그렇게 띄운 서버에 IP 주소로 접속하면 Access is denied(HTTP 403)로 거부되고 localhost만 통과합니다. 접속할 호스트를 나열하세요.
--allowed-hosts에 별표 하나를 지정하면 검사를 끌 수 있지만, 이 검사는 DNS 리바인딩 방어 목적이므로 접속할 호스트를 명시하는 편이 낫습니다.
보안
가능한 모든 망에 브라우저를 띄울 수 있습니다.
- 방화벽으로 8931 포트를 소나 호스트만 접근하도록 제한하세요. 전용망 배치를 권장합니다.
- 공개망에 노출하지 마세요. 노출된 서버는 그 망의 접근 권한을 익명 호출자에게 넘기는 것과
같습니다.
- 망이 분리된 환경에서는 망마다 서버를 두고 서버마다 접속 프로파일을 하나씩 등록하세요.
소나에 서버 등록
두 가지 방법이 있고, 어느 쪽이든 명령어에서 서버를 지정할 필요는 없습니다.
접속 프로파일
시스템 > 접속 프로파일에서 추가를 클릭하고 Playwright MCP 서버 유형을 선택합니다.
| 구분 | 항목 | 설정 |
|---|---|---|
| 필수 | MCP URL | 서버 엔드포인트. 기본값은 http://localhost:8931/mcp |
| 선택 | HTTP 프록시 | 호스트:포트 |
| 선택 | 접속 타임아웃 / 읽기 타임아웃 | 초 단위. 미지정 시 30초 / 60초 |
| 선택 | 화면 안정화 타임아웃 | 사이트가 화면을 다 그릴 때까지 허용하는 시간. 미지정 시 10초 |
| 선택 | 화면 크기 | 브라우저 창 크기. 미지정 시 1600x900 |
등록된 서버가 하나뿐이면 명령어에서 지정하지 않아도 그 서버를 사용합니다. 여러 대를 등록한 경우에만 mcp 옵션으로 고릅니다.
접속 테스트 버튼은 서버가 응답하는지, 그리고 실제로 Playwright MCP 서버인지 확인합니다. 사이트는 열지 않습니다.
버튼으로 접는데, 접힌 메뉴는 작게 보이는 것이 아니라 CSS로 숨겨져 접근성 스냅샷에서 아예
사라집니다. 그러면 메뉴가 없는 화면을 읽게 됩니다. 브레이크포인트를 1300px 이상으로 두는
사이트가 흔하므로 기본값은 1600x900입니다.
시스템 프로퍼티
프로파일을 만들지 않고 서버 주소만 설정해도 됩니다.
환경변수 PLAYWRIGHT_SERVER_URL도 같은 역할을 합니다. 등록된 프로파일이 있으면 프로파일이 우선합니다. 셋 중 아무것도 없으면 명령어가 그 사실을 알리며 거부합니다.
자격증명 프로파일 등록
로그인이 필요한 사이트에만 해당합니다. 시스템 > 접속 프로파일에서 추가를 클릭하고 Playwright 자격증명 유형을 선택합니다.
| 구분 | 항목 | 설정 |
|---|---|---|
| 필수 | 로그인 이름 | 로그인에 사용할 계정 |
| 선택 | 암호 | 계정 암호 |
| 선택 | OTP 방식 | manual(기본)은 실행할 때마다 사람이 코드를 입력하고, totp는 시드로 생성 |
| 선택 | TOTP 시드 | base32 시드. OTP 방식이 totp일 때 사용 |
| 선택 | 읽기 전용 | true면 이 계정을 쓰는 모든 세션에서 입력과 폼 제출을 거부 |
암호와 TOTP 시드는 플랫폼이 암호화해 보관합니다. 이 프로파일에는 사이트 주소도 서버 주소도 없습니다. 어디로 갈지는 명령어의 url이, 어느 서버로 갈지는 mcp가 정합니다. 그래서 같은 계정을 여러 주소에 쓸 때 프로파일을 주소마다 만들지 않아도 됩니다.
수준으로 취급해야 합니다.
설치 확인
계정이 필요 없는 사이트를 열어 화면을 읽어 봅니다. 스냅샷이 돌아오면 서버와 네트워크 경로가 정상이며, 스크린샷까지 저장되면 파일 스토어도 정상입니다.
playwright-open url="https://www.example.com/"
playwright-observe session-id="SESSION_ID"
playwright-screenshot session-id="SESSION_ID"
playwright-close session-id="SESSION_ID"
playwright-open이 반환한 session_id를 다른 명령어에 넘깁니다.
세션은 닫히거나 유휴 상태로 회수될 때까지 공용 서버의 브라우저를 점유하므로, 작업이 끝나면 닫으세요.
버전 고정
도구 이름과 스키마는 서버 버전에 따라 달라질 수 있습니다. 운영 환경에서는 @playwright/mcp@버전 형식으로 버전을 지정하거나 태그가 붙은 도커 이미지로 고정하고, 올린 뒤에는 MCP 서버 프로파일의 접속 테스트로 browser_* 도구가 그대로인지 확인하세요.
폐쇄망 반입
# 인터넷 구간
docker pull mcr.microsoft.com/playwright/mcp
docker save mcr.microsoft.com/playwright/mcp -o playwright-mcp.tar
# 폐쇄망
docker load -i playwright-mcp.tar
도커를 쓸 수 없으면 Node.js와 @playwright/mcp npm 패키지, playwright install chromium 산출물(리눅스는 ~/.cache/ms-playwright, 윈도우는 %USERPROFILE%\AppData\Local\ms-playwright)을 함께 반입합니다.