Playwright CDP MCP

Playwright and Chrome DevTools Protocol 기반으로 브라우저 페이지를 실행하거나 기존 Chrome/Edge 디버그 세션에 연결하고, 페이지 이동, 스크린샷 캡처, 텍스트/DOM 확인, 클릭, 입력, 스크롤을 수행하는 MCP 서버입니다.

주요 기능

• browser_launch: MCP 서버가 제어하는 Chrome, Edge, Chromium 브라우저를 실행합니다.
• browser_connect_cdp: --remote-debugging-port로 실행 중인 Chromium 계열 브라우저에 연결합니다.
• browser_list_pages: 열린 페이지/탭 목록을 조회합니다.
• browser_select_page: 제어할 페이지/탭을 선택합니다.
• browser_navigate: 지정한 URL로 이동합니다.
• browser_screenshot: 현재 화면 또는 전체 페이지 스크린샷을 base64 이미지로 반환합니다.
• browser_get_text: 문서 본문의 visible text를 추출합니다.
• browser_snapshot: 주요 텍스트와 상호작용 요소의 간단한 DOM 스냅샷을 반환합니다.
• browser_click: CSS selector로 요소를 클릭합니다.
• browser_click_xy: viewport 좌표를 클릭합니다. recording 중에는 클릭 지점의 DOM 정보를 함께 수집해 테스트 export 시 locator 기반 클릭으로 승격을 시도합니다.
• browser_type: CSS selector로 입력 요소에 텍스트를 입력합니다.
• browser_press_key: 키보드 키 또는 키 조합을 누릅니다.
• browser_scroll: 마우스 휠 스크롤을 수행합니다.
• browser_wait_for_selector: selector가 특정 상태가 될 때까지 기다립니다.
• browser_evaluate: 페이지에서 JavaScript를 실행합니다. 기본값은 비활성화입니다.
• browser_recording_start: 브라우저 액션 기록을 시작합니다.
• browser_recording_stop: 브라우저 액션 기록을 중지하고 기록된 액션을 반환합니다.
• browser_recording_clear: 기록된 액션을 비웁니다.
• browser_recording_status: 기록 상태와 액션 목록을 반환합니다.
• browser_recording_export: 기록된 액션을 Playwright 테스트 코드 또는 JSON으로 내보냅니다.
• browser_close: 브라우저 연결 또는 세션을 닫습니다.

사전 준비

1. Node.js 20 이상을 설치합니다.
2. 로컬에 Chrome, Microsoft Edge, Chromium 중 하나를 설치합니다.
3. 기존 브라우저 세션에 연결하려면 브라우저를 CDP 포트가 열린 상태로 실행합니다.

OCR 기능은 @developer.k/mcp-ocr-engine 패키지를 사용하므로 Node.js 20 이상이 필요합니다. 영어와 한국어 언어 데이터는 해당 패키지의 npm 의존성으로 함께 설치되며, 원격 OCR API 없이 eng, kor, kor+eng 언어 설정을 사용할 수 있습니다.

Chrome 예시:

chrome --remote-debugging-port=9222 --user-data-dir=/tmp/mcp-chrome-profile

Edge 예시:

msedge --remote-debugging-port=9222 --user-data-dir=/tmp/mcp-edge-profile

Windows에서는 실행 파일이 PATH에 없을 수 있습니다. 이 경우 Chrome 또는 Edge 실행 파일의 전체 경로를 사용하세요.

& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:TEMP\mcp-chrome-profile"

설치해서 사용하기

MCP 클라이언트 설정 예시:

{
  "mcpServers": {
    "playwright-cdp": {
      "command": "npx",
      "args": ["-y", "playwright-cdp-mcp"]
    }
  }
}

기본 CDP URL을 환경 변수로 지정할 수도 있습니다.

{
  "mcpServers": {
    "playwright-cdp": {
      "command": "npx",
      "args": ["-y", "playwright-cdp-mcp"],
      "env": {
        "BROWSER_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

로컬 개발

저장소를 받은 뒤 패키지 디렉터리에서 실행합니다.

cd playwright-cdp-mcp
npm install
npm run build
npm start

로컬 빌드 결과물을 직접 실행하는 MCP 설정 예시:

{
  "mcpServers": {
    "playwright-cdp": {
      "command": "node",
      "args": ["/path/to/playwright-cdp-mcp/build/index.js"]
    }
  }
}

또는

{
  "mcpServers": {
    "playwright-cdp": {
      "command": "node",
      "args": ["./build/index.js"],
      "cwd": "/path/to/playwright-cdp-mcp"
    }
  }
}

cwd는 실제 패키지 디렉터리로 바꾸세요. Windows라면 예를 들어 C:\\path\\to\\playwright-cdp-mcp처럼 적습니다.

Docker

이미지 빌드:

docker build -t playwright-cdp-mcp .

Docker 기반 MCP 설정 예시:

{
  "mcpServers": {
    "playwright-cdp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "BROWSER_CDP_URL=http://host.docker.internal:9222",
        "playwright-cdp-mcp"
      ]
    }
  }
}

Docker 컨테이너 안에서 새 브라우저를 실행하려면 별도의 Chromium 설치와 실행 옵션이 필요할 수 있습니다. 일반적으로는 호스트에서 CDP 포트를 연 브라우저를 실행하고 browser_connect_cdp로 연결하는 구성이 단순합니다.

JSON 호출 예시

CDP 브라우저에 연결

{
  "url": "http://127.0.0.1:9222"
}

새 브라우저 실행

{
  "headless": false,
  "channel": "chrome",
  "viewport_width": 1280,
  "viewport_height": 720
}

브라우저 실행 파일을 직접 지정할 수도 있습니다.

{
  "headless": false,
  "executable_path": "/path/to/chrome"
}

페이지 이동

{
  "url": "https://example.com",
  "wait_until": "domcontentloaded",
  "timeout_ms": 30000
}

스크린샷 캡처

{
  "full_page": false,
  "type": "png"
}

요소 클릭과 입력

{
  "selector": "input[name='q']",
  "text": "Model Context Protocol",
  "clear": true
}

{
  "selector": "button[type='submit']"
}

브라우저 액션 기록 시작

{
  "test_name": "search flow",
  "prefer_fill": true,
  "include_comments": true
}

기록된 액션을 Playwright 테스트로 내보내기

{
  "format": "playwright-test",
  "test_name": "search flow"
}

browser_click_xy로 좌표 클릭을 수행한 경우 recorder는 클릭 지점의 가까운 a, button, input, [role], [data-testid] 요소를 찾아 metadata와 selector 후보를 저장합니다. export 시 안정적인 role/label/text/selector가 있으면 page.mouse.click() 대신 page.getByRole() 또는 page.locator() 기반 클릭으로 생성합니다. 안정적인 locator를 만들 수 없을 때만 좌표 클릭으로 fallback합니다.

OCR 도구

OCR 도구는 @developer.k/mcp-ocr-engine 패키지를 사용합니다. 영어와 한국어 언어 데이터는 해당 패키지의 npm 의존성으로 함께 설치되므로 원격 OCR API 없이 eng, kor, kor+eng을 사용할 수 있습니다.

browser_ocr_page

현재 viewport 또는 전체 페이지 스크린샷에 OCR을 수행합니다.

{
  "full_page": false,
  "language": "kor+eng",
  "preprocess": {
    "scale": 2,
    "grayscale": true
  }
}

인식된 텍스트, 단어, 줄, 이미지 metadata, viewport metadata, OCR bounding box를 반환합니다. full_page가 false이면 좌표는 viewport 기준이고, true이면 전체 페이지 이미지 기준입니다.

browser_ocr_element

CSS selector로 선택한 요소의 clipped screenshot에 OCR을 수행합니다.

{
  "selector": "#preview",
  "language": "eng"
}

반환되는 단어와 줄 좌표는 viewport 기준 좌표로 변환됩니다.

browser_find_text

현재 viewport 또는 전체 페이지 스크린샷의 OCR 결과에서 텍스트를 찾습니다.

{
  "text": "Login",
  "match": "contains",
  "scope": "auto",
  "language": "eng",
  "min_confidence": 60
}

일치하는 OCR 단어 또는 줄의 bounding box와 center point를 반환합니다. 단일 토큰 검색에는 scope: "word", 여러 단어 구문 검색에는 scope: "line"을 사용할 수 있고, scope: "auto"는 공백 포함 여부에 따라 단어 또는 줄 검색을 자동 선택합니다. 줄 단위 구문 검색에서는 OCR 단어 위치를 사용할 수 있으면 일치한 단어 범위로 box를 좁히고, 그렇지 않으면 전체 줄 box를 반환합니다.

LLM 채팅 프롬프트 예시

MCP가 연결된 LLM 채팅에서 아래처럼 자연어로 요청할 수 있습니다.

CDP로 열린 브라우저에 연결하고 현재 탭 목록을 보여줘.

현재 페이지의 텍스트와 클릭 가능한 주요 요소를 요약해줘.

현재 화면을 캡처하고, 검색창이 있으면 selector 기반으로 검색어를 입력해줘.

https://example.com 으로 이동한 뒤 제목과 본문 텍스트를 확인해줘.

OCR 프롬프트

https://www.naver.com을 열고 현재 화면에서 OCR로 "일본어" 텍스트를 찾아줘. 찾으면 bounding box와 center point를 알려줘.

https://www.naver.com을 최대 10번 새로고침하면서 매번 OCR로 "못하시는 분"을 찾아줘. 발견하면 즉시 멈추고, 인식된 텍스트와 confidence, bounding box, center point를 알려줘.

현재 페이지에서 OCR로 "Sign in" 문구를 찾아줘. 여러 단어로 된 문구니까 line 또는 auto scope를 사용하고, 가능하면 실제로 일치한 단어 범위의 bounding box로 좁혀서 알려줘.

CSS selector "#preview"에 해당하는 요소만 OCR로 읽고, 감지된 텍스트를 요약해줘. confidence가 낮은 단어는 좌표도 같이 보여줘.

현재 viewport 스크린샷을 찍고 "kor+eng" 언어로 OCR을 실행한 다음, 화면에 보이는 이미지 텍스트가 DOM 텍스트와 다른지 비교해줘.

OCR로 "로그인" 텍스트를 찾아줘. confidence가 80 이상이면 center point를 클릭하고, 여러 개가 있으면 클릭하지 말고 후보 목록을 먼저 보여줘.

Recording 프롬프트

"naver search flow"라는 이름으로 Playwright 테스트 기록을 시작해줘. https://www.naver.com으로 이동해서 "Model Context Protocol"을 검색하고 제출한 다음, 기록을 Playwright 테스트 코드로 export해줘.

텍스트 redaction을 켠 상태로 recording을 시작해줘. 로그인 페이지로 이동해서 아이디와 비밀번호를 입력하고 로그인 버튼을 클릭한 뒤, 기록을 JSON으로 export해줘.

다음 흐름을 recording해줘: 대상 페이지를 열고, 검색 input이 나타날 때까지 기다리고, "playwright cdp"를 입력하고, Enter를 누르고, 결과 제목이 나타날 때까지 기다려줘. comments를 포함해서 Playwright 테스트로 export해줘.

기존 recording을 모두 지우고 새 recording을 시작해줘. 내가 다음에 요청하는 브라우저 동작들을 수행한 뒤, export하기 전에 recording status를 먼저 보여줘.

recording을 시작해줘. 좌표 클릭이 발생하면 export할 때 가능한 한 안정적인 locator 기반 클릭으로 승격해줘. 좌표 클릭으로 fallback되는 경우에는 주석을 포함해줘.

OCR과 Recording 조합 프롬프트

recording을 시작해줘. https://www.naver.com을 열고 OCR로 "일본어"가 나올 때까지 새로고침한 뒤, 발견된 OCR match의 center point를 클릭하고, 전체 과정을 Playwright 테스트 코드로 export해줘.

현재 페이지에서 OCR로 "못하시는 분"을 찾아줘. 발견하면 해당 match의 center point 클릭을 recording에 남기고, 그 액션을 Playwright 테스트로 export해줘.

현재 페이지로 이동하는 테스트를 recording해줘. OCR로 "Sign in" 문구가 보이는지 검증하고, 가능하면 가장 가까운 버튼을 selector 기반으로 클릭하는 테스트 코드로 만들어줘.

JavaScript 실행 권한

browser_evaluate는 임의 JavaScript 실행 기능이므로 기본적으로 비활성화되어 있습니다. 필요한 경우에만 환경 변수로 활성화하세요.

{
  "env": {
    "BROWSER_ALLOW_EVALUATE": "true"
  }
}

배포

npm run build
npm pack --dry-run
npm login
npm publish

scope 패키지(@scope/playwright-cdp-mcp) 경우:

npm publish --access public

주의 사항

• playwright-core는 브라우저 바이너리를 내려받지 않습니다. 로컬에 Chrome, Edge, Chromium 중 하나가 설치되어 있어야 합니다.
• 기존 브라우저에 연결하려면 --remote-debugging-port로 실행된 Chromium 계열 브라우저가 필요합니다.
• 좌표 클릭보다 selector 기반 도구를 우선 사용하세요. 좌표는 화면 크기와 레이아웃 변화에 취약합니다.
• 로그인 페이지, 관리자 콘솔, 결제 화면 등 민감한 페이지의 스크린샷과 DOM 텍스트는 MCP 클라이언트 로그에 남을 수 있습니다.
• browser_evaluate는 신뢰할 수 있는 환경에서만 활성화하세요.