윈도우에서 Playwright MCP를 Claude Code에 붙이기 — @playwright/mcp project 범위 설정과 첫 연결 확인

한 줄로

윈도우 PowerShell 7에서 claude mcp add playwright --scope project -- npx -y @playwright/mcp@latest --headless --isolated로 붙이고 승인하자 ✔ Connected가 나왔습니다. 저희 PC에서는 따로 브라우저를 내려받지 않아도 첫 페이지가 열렸습니다. 서버 설정 조회에서 기본 브라우저가 channel: "chrome"으로 나왔고, 이미 설치된 Chrome을 쓴 것으로 봅니다. 로컬 HTML 파일은 file:// 주소로 바로 열리지 않았습니다.

2026-09-28 보완: 아래 Windows 출력과 버전은 2026-09-17 기록입니다. 글 뒤쪽의 공개 클라이언트로 확인하기에는 내려받을 수 있는 새 예제와 별도 Linux 확인 범위를 덧붙였습니다. 기존 비공개 mcp_client.mjs를 복원했거나 Windows 실측을 다시 했다는 뜻은 아닙니다.

이런 분께

Claude Code에 Playwright MCP를 처음 붙이는 분. 개인 설정 파일(~/.claude.json)을 건드리지 않고 한 프로젝트에만 넣고 싶은 분. 붙인 뒤 file:///C:/... 주소를 열었다가 Access to "file:" protocol is blocked를 본 분.

실측 환경

먼저 패키지와 옵션 확인

npm view @playwright/mcp name version bin engines --json
npx -y @playwright/mcp@latest --help

npm view 결과는 이름 @playwright/mcp, 버전 0.0.81, 실행 파일 playwright-mcp, "node": ">=18"이었습니다. 공식 README(github.com/microsoft/playwright-mcp, 2026-09-17 확인)의 요구 사항도 Node.js 18 이상이고, Claude Code용 예시는 claude mcp add playwright npx @playwright/mcp@latest 한 줄입니다.

도움말에서 이번 실험에 쓴 옵션은 셋입니다.

  --headless                            run browser in headless mode, headed by
                                        default
  --isolated                            keep the browser profile in memory, do
                                        not save it to disk.
  --allow-unrestricted-file-access      allow access to files outside of the
                                        workspace roots. Also allows
                                        unrestricted access to file:// URLs. By
                                        default access to file system is
                                        restricted to workspace root directories
                                        (or cwd if no roots are configured)
                                        only, and navigation to file:// URLs is
                                        blocked.

--isolated를 넣은 이유가 있습니다. README의 User profile 절을 보면 기본값은 디스크에 남는 영구 프로필이고, 윈도우 위치는 %USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-{workspace-hash}입니다. 실험 흔적을 남기지 않으려고 프로필을 메모리에만 두는 쪽을 골랐습니다. 서버를 붙인 뒤 첫 도구 호출 전과 페이지 열기 실험 뒤에 %LOCALAPPDATA%\ms-playwright의 하위 항목 이름을 비교했을 때 차이는 없었습니다.

1단계 — project 범위로 추가

Set-Location 'C:\Users\User\AppData\Local\Temp\longtail_C2\proj'
claude mcp add playwright --scope project -e PLAYWRIGHT_BROWSERS_PATH='C:\Users\User\AppData\Local\Temp\longtail_C2\browsers17' -- npx -y '@playwright/mcp@latest' --headless --isolated

Added stdio MCP server playwright with command: npx -y @playwright/mcp@latest --headless --isolated to project config
File modified: C:\Users\User\AppData\Local\Temp\longtail_C2\proj\.mcp.json

-e PLAYWRIGHT_BROWSERS_PATH=…는 혹시 브라우저를 내려받게 되면 임시 폴더로 받으려고 넣었습니다. 결과적으로 이 폴더는 실험이 끝날 때까지 비어 있었습니다. 만들어진 .mcp.json(338바이트)은 이렇습니다.

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest",
        "--headless",
        "--isolated"
      ],
      "env": {
        "PLAYWRIGHT_BROWSERS_PATH": "C:\\Users\\User\\AppData\\Local\\Temp\\longtail_C2\\browsers17"
      }
    }
  }
}

claude mcp add --help에는 -s, --scope <scope>의 기본값이 "local"로 적혀 있어, --scope를 빼면 project 범위로 들어가지 않습니다. 범위별 저장 위치와 cmd /c 이야기는 Claude Code에 MCP 서버 붙이기에 적었습니다.

2단계 — 상태 확인

승인 전 claude mcp list와 claude mcp get playwright는 둘 다 대기 상태였습니다.

playwright: npx -y @playwright/mcp@latest --headless --isolated - ⏸ Pending approval (run `claude` to approve)

대화형 세션을 열지 않고 확인하려고 --settings로 그 실행에만 승인을 줬습니다. 여기서 PowerShell 따옴표에 한 번 걸렸습니다. '{\"enableAllProjectMcpServers\": true}'처럼 역슬래시를 넣었더니 Error: Invalid JSON provided to --settings와 종료 코드 1이 나왔습니다. 이 PC의 PowerShell 7.6.6은 $PSNativeCommandArgumentPassing이 Windows였고, 역슬래시 없이 쓰자 통과했습니다.

claude --settings '{"enableAllProjectMcpServers": true}' mcp get playwright

playwright:
  Scope: Project config (shared via .mcp.json)
  Status: ✔ Connected
  Type: stdio
  Command: npx
  Args: -y @playwright/mcp@latest --headless --isolated
  Environment:
    PLAYWRIGHT_BROWSERS_PATH=C:\Users\User\AppData\Local\Temp\longtail_C2\browsers17

3단계 — 도구 목록과 페이지 열기: 2026-09-17 기록

✔ Connected는 연결 확인일 뿐이라 실제 도구 호출은 따로 해 봤습니다. .mcp.json의 명령·인자·환경변수를 그대로 읽어 서버를 띄우고, stdio로 initialize → notifications/initialized → tools/list → tools/call(browser_navigate) → browser_close 순서로 JSON-RPC를 보내는 node 스크립트(mcp_client.mjs)입니다. 윈도우에서 npx는 npx.cmd라서 spawn에 shell: true를 줬습니다. 이 스크립트는 이 글에서 내려받을 수 없는 당시 원자료입니다. 아래 명령은 실행 기록으로 남겼으며, 지금 따라 하려면 글 뒤쪽의 공개 mcp-smoke.mjs 예제를 쓰면 됩니다.

node mcp_client.mjs 'C:/Users/User/AppData/Local/Temp/longtail_C2/proj' - --caps config

initialize (2.5s): {"name":"Playwright","version":"1.64.0-alpha-2026-09-14"} protocol 2025-06-18 
tools/list (2.5s): 27 tools
browser_get_config (3.0s):
"browser": {
    "launchOptions": {
      "headless": true,
      "channel": "chrome",

도구는 기본 26개였고, 설정 조회용 browser_get_config가 켜지는 --caps config를 붙였을 때 27개였습니다. browser_get_config가 보여 준 channel이 chrome입니다. 브라우저 다운로드 없이 페이지가 열린 이유가 이것이라고 보지만, 실제로 실행된 파일 경로는 확인하지 않았습니다(이 PC의 C:\Program Files\Google\Chrome\Application 아래에 153.0.8010.47 폴더가 있었습니다).

같은 파일(proj\test.html)을 세 가지 방법으로 열었습니다.

A의 오류 원문입니다.

### Error
Error: Access to "file:" protocol is blocked. Attempted URL: "file:///C:/Users/User/AppData/Local/Temp/longtail_C2/proj/test.html"

B와 C의 응답에는 - [Snapshot](.playwright-mcp\page-2026-09-17T09-16-12-784Z.yml)처럼 스냅샷 파일 경로가 붙었고, 작업 폴더 아래 .playwright-mcp 폴더에 130바이트짜리 .yml이 생겼습니다.

- generic [active] [ref=e1]:
  - heading "Hello from a local file" [level=1] [ref=e2]
  - paragraph [ref=e3]: playwright-mcp check

로컬 파일을 확인하는 용도라면 B처럼 로컬 HTTP로 여는 편이 기본 제한을 그대로 둡니다. C의 옵션은 도움말 설명대로 작업 폴더 밖 파일 접근까지 풀기 때문입니다.

4단계 — 지우기

$ claude mcp remove playwright --scope project
Removed MCP server playwright from project config
File modified: C:\Users\User\AppData\Local\Temp\longtail_C2\proj\.mcp.json

.mcp.json은 {"mcpServers": {}}(22바이트)로 비었고, 제거 뒤 claude mcp list 출력에서 longtail_C2 또는 --isolated가 든 줄은 0개였습니다. %USERPROFILE%\.claude.json에서 longtail_C2 문자열도 0건이었습니다(내용은 열지 않고 건수만 셈). 실험이 끝난 뒤 임시 폴더 longtail_C2(1.5G)는 rm -rf로 지웠고, 남은 폴더는 없었습니다.

결과

실패한 것

• --settings JSON을 PowerShell에서 역슬래시로 이스케이프한 첫 시도는 Invalid JSON provided to --settings로 실패했습니다.
• 첫 스크립트 실행은 서버가 3.2초에 끝났는데도 스크립트가 약 3분(183초) 뒤에야 끝났습니다. 요청마다 건 180초 제한 타이머가 node를 붙잡고 있었고, 타이머에 unref()를 붙인 뒤에는 서버 종료와 함께 끝났습니다.
• 설치된 Chrome 버전을 chrome.exe --version으로 보려 했지만 버전 줄은 나오지 않고 chrome.exe 프로세스가 계속 떠 있었습니다. 그 프로세스(PID 하나)만 종료했고, 버전은 설치 폴더 이름으로만 확인했습니다.

2026-09-17 실측에서 확인하지 않은 것

• 대화형 claude의 승인 화면과 /mcp 화면, 대화 중 Claude가 도구를 부르는 모습.
• 창이 뜨는(headed) 기본 모드. 이번에는 --headless만 썼습니다.
• Chrome이 설치되지 않은 PC에서의 기본 동작. 전용 Chromium을 쓰는 경우는 Playwright 브라우저 실행 파일이 없을 때에 적었습니다.
• --isolated 없이 쓸 때 생기는 영구 프로필 폴더.
• local·user 범위 추가, 명령 프롬프트(cmd.exe)에서의 입력, --extension 모드.

공개 클라이언트로 확인하기 — 2026-09-28 추가

별도 빈 폴더를 만들고 mcp-smoke.mjs와 playwright-test.html을 원래 이름으로 저장합니다. 새 클라이언트는 MCP SDK로 연결하고 도구 목록을 읽은 뒤, 지정한 도구를 한 번 호출하고 연결을 닫습니다. .mcp.json을 읽거나 Claude Code의 승인 상태를 바꾸지 않습니다. Node.js와 npm이 필요합니다.

그 폴더에서 다음 패키지를 고정 버전으로 설치합니다.

npm init -y
npm install --save-exact @modelcontextprotocol/sdk@1.30.1 @playwright/mcp@0.0.82

브라우저를 이 예제 폴더에 받으려면 PowerShell에서 환경변수를 지정합니다. 설치와 MCP 실행 모두 같은 터미널에서 이 값을 유지합니다.

$env:PLAYWRIGHT_BROWSERS_PATH = Join-Path $PWD 'browsers-check'

Git Bash나 Linux Bash에서는 위 한 줄 대신 다음을 씁니다.

export PLAYWRIGHT_BROWSERS_PATH="$PWD/browsers-check"

먼저 브라우저를 열지 않고 서버 연결과 도구 목록만 확인할 수 있습니다.

node mcp-smoke.mjs -- node node_modules/@playwright/mcp/cli.js --headless --isolated --browser chromium

페이지까지 열려면 이 MCP 버전이 요구하는 브라우저를 설치합니다. 일반 playwright 패키지용 브라우저와 번호가 다를 수 있습니다. 브라우저가 없을 때의 별도 설치 절차도 참고하세요.

node node_modules/@playwright/mcp/cli.js install-browser chrome-for-testing

같은 폴더에서 두 번째 터미널을 열어 테스트 HTML만 제공하는 로컬 HTTP 서버를 시작하고 그대로 둡니다.

node -e "const http=require('node:http'); const fs=require('node:fs'); http.createServer((req,res)=>{res.setHeader('Content-Type','text/html; charset=utf-8'); res.end(fs.readFileSync('playwright-test.html'));}).listen(8765,'127.0.0.1');"

첫 번째 터미널의 폴더에 navigate.json을 아래 내용으로 저장합니다.

{"url":"http://127.0.0.1:8765/playwright-test.html"}

환경변수를 지정한 첫 번째 터미널에서 도구를 호출합니다. 서버를 node로 직접 실행하므로 새 예제에는 npx.cmd용 shell: true가 필요하지 않습니다.

node mcp-smoke.mjs --call browser_navigate --args-file navigate.json -- node node_modules/@playwright/mcp/cli.js --headless --isolated --browser chromium

성공 판단 기준은 event: "result"의 결과가 오류가 아니고 페이지 제목 DADDYNOTE browser check가 포함되는 것입니다. connected와 도구 목록만 나왔다고 페이지를 열었다고 판단하면 안 됩니다. 끝나면 두 번째 터미널에서 Ctrl+C로 HTTP 서버를 닫습니다. 브라우저 실행 파일이 없다는 결과라면 설치와 호출 때의 PLAYWRIGHT_BROWSERS_PATH 값 및 오류가 요구하는 브라우저 경로를 비교합니다.

2026-09-28에 새 예제를 확인한 환경은 Linux, Node.js 24.19.0, SDK 1.30.1, @playwright/mcp 0.0.82입니다. 실제 서버 연결과 도구 25개 목록 조회까지 성공했습니다. 전용 브라우저 다운로드는 ZIP 오류로 완료하지 못했으므로, 위 기본 설치 경로의 복구와 HTTP 페이지 열기 성공은 이번 확인 결과로 제시하지 않습니다. 로컬 HTTP 서버는 200 응답을 확인했습니다. 별도로 확보한 Chromium 153.0.8010.0을 지정해 MCP 페이지 이동도 시도했지만, 서버 내부 Unix 소켓의 listen EPERM으로 실패했습니다. 새 클라이언트는 이때 isError: true와 종료 코드 1을 반환했습니다. 브라우저를 직접 실행한 제목 확인 결과는 브라우저가 없을 때 글의 추가 기록에 구분했습니다. PowerShell 문법과 Windows 실행은 새로 실측하지 않았습니다. 옵션과 브라우저 설치 위치는 공식 MCP README와 Playwright 브라우저 문서를 같은 날 다시 확인했습니다.

함께 보기

• Claude Code에 MCP 서버 붙이기
• Playwright 브라우저 실행 파일이 없을 때
• Claude Code settings.json 위치와 우선순위