Chrome DevTools MCP

컨테이너에는 사전 구성된 Chrome DevTools MCP 서버가 포함되어 있어 Claude Code에 헤드리스 브라우저 자동화 기능을 제공합니다. 추가 설정 없이 웹 페이지를 탐색하고, 스크린샷을 찍고, DOM을 검사하고, 페이지 요소와 상호작용할 수 있습니다.

작동 방식

엔트리포인트는 포트 9222에서 원격 디버깅이 활성화된 영구적인 헤드리스 Chrome을 시작합니다. chrome-devtools-mcp MCP 서버는 Claude Code 설정에 등록되어 --browserUrl을 통해 이 공유 브라우저에 연결됩니다. 모든 세션은 하나의 브라우저 인스턴스와 쿠키 저장소를 공유하므로 로그인, 쿠키, 인증이 프로젝트 간에 유지됩니다.

사용 가능한 도구

도구	설명
navigate_page	URL로 이동하고 페이지가 로드될 때까지 대기
take_screenshot	현재 페이지의 PNG 스크린샷 캡처
take_snapshot	페이지의 접근성 트리 스냅샷 가져오기
click	페이지의 요소 클릭
type	입력 필드에 텍스트 입력
hover	요소 위에 마우스 호버
scroll	페이지 또는 특정 요소 스크롤
evaluate	페이지 컨텍스트에서 JavaScript 실행
get_console_logs	콘솔 로그 메시지 가져오기
get_page_info	페이지 메타데이터(제목, URL 등) 가져오기

아키텍처

브라우저 스택은 함께 작동하는 네 가지 구성 요소를 사용합니다:

1. Playwright Chromium — 빌드 시 npx playwright install --with-deps chromium을 통해 설치되는 ARM64 호환 Chromium 바이너리
2. Chrome 심볼릭 링크 — Puppeteer가 예상하는 경로(/opt/google/chrome/chrome)를 Playwright 바이너리에 연결
3. 공유 Chrome 프로세스 — chrome-browser.sh에 의해 --remote-debugging-port=9222로 시작되며, 충돌 시 자동 재시작
4. 글로벌 MCP 등록 — settings.json이 --browserUrl=http://localhost:9222로 chrome-devtools-mcp를 등록

Google Chrome은 ARM64용 .deb 패키지가 없으며, Ubuntu 24.04의 chromium-browser apt 패키지는 snap으로 리다이렉트되어 컨테이너에서 작동하지 않습니다. Playwright의 번들 Chromium이 ARM64 컨테이너에서 유일하게 안정적인 옵션입니다.

검증

컨테이너 내부에서 설정이 올바르게 작동하는지 확인합니다:

# Chrome 바이너리 응답 확인
/opt/google/chrome/chrome --version

# 심볼릭 링크 확인
ls -la /opt/google/chrome/chrome

# 원격 디버깅 활성화 확인
curl http://localhost:9222/json/version

# 셀프 테스트에 Chrome 검사 포함
claude-self-test

헤디드 모드 (VNC)

ENABLE_VNC=true일 때, 엔트리포인트는 Chrome을 시작하기 전에 VNC 스택을 시작합니다. chrome-browser.sh 스크립트는 DISPLAY가 설정된 것을 감지하고 가상 디스플레이에서 Chrome을 헤디드 모드로 실행하므로, VNC 뷰어에서 브라우저를 볼 수 있습니다.

http://localhost:6080/vnc.html을 열어 가상 디스플레이를 확인하세요. 자세한 내용은 원격 디스플레이 (noVNC)를 참조하세요.

문제 해결

원격 디버깅 실패, 프로필 잠금 오류, 중복 MCP 도구 등 일반적인 문제의 해결 방법은 문제 해결 — Chrome DevTools MCP를 참조하세요.