Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 07. 01:51

CloakBrowser MCP: CloakBrowser Chromium 런타임을 사용하는 Playwright MCP 도구

요약

CloakBrowser MCP는 Playwright MCP의 인터페이스를 유지하면서 Chromium 런타임만 CloakBrowser로 교체할 수 있게 해주는 오픈 소스 MCP 서버입니다. AI 에이전트가 브라우저 자동화를 통해 프론트엔드 디버깅이나 UI 검증 등을 수행할 수 있도록 지원합니다.

핵심 포인트

  • Playwright MCP의 도구 스키마와 응답을 그대로 유지
  • CloakBrowser Chromium 실행 파일을 사용하도록 설정 브릿지 역할
  • 가벼운 설계로 유지보수 용이성 확보
  • AI 에이전트의 브라우저 자동화 워크플로 최적화

브라우저 자동화 (Browser automation)는 AI 에이전트 (AI agents)를 위한 가장 유용한 도구 카테고리 중 하나가 되고 있습니다.

만약 에이전트가 페이지를 열고, 접근성 트리 (accessibility tree)를 검사하며, 버튼을 클릭하고, 양식을 채우고, 콘솔 출력 (console output)을 읽고, 스크린샷을 찍을 수 있다면, API만으로는 해결하기 어려운 작업들을 도울 수 있습니다: 프론트엔드 흐름 (frontend flows) 디버깅, 문서 확인, 온보딩 (onboarding) 테스트, 생성된 UI 검증, 그리고 브라우저 전용 버그 재현 등이 이에 해당합니다.

Playwright MCP는 이미 해당 워크플로우를 위한 강력한 기반을 제공하고 있습니다. 이는 MCP 클라이언트 (MCP clients)에게 Playwright를 중심으로 구축된 브라우저 자동화 인터페이스를 제공합니다. CloakBrowser MCP를 만들게 된 질문은 더 구체적이었습니다:

기존의 Playwright MCP 도구들을 그대로 사용하면서, Chromium 런타임 (Chromium runtime)만 다르게 사용하고 싶다면 어떻게 해야 할까?

그것이 바로 cloakbrowser-mcp가 하는 일입니다.

CloakBrowser MCP란 무엇인가?

cloakbrowser-mcp는 CloakBrowser Chromium 실행 파일과 함께 업스트림(upstream) @playwright/mcp를 실행하는 오픈 소스 모델 컨텍스트 프로토콜 (Model Context Protocol) 서버입니다.

이 프로젝트는 의도적으로 가볍게 설계되었습니다:

  • 업스트림 Playwright MCP가 브라우저 도구 스키마 (schemas), 설명 (descriptions), 그리고 응답 (responses)을 소유합니다.
  • cloakbrowser-mcp는 launchOptions.executablePath가 CloakBrowser를 가리키도록 하는 Playwright MCP 설정을 생성합니다.
  • 업스트림 브라우저 도구들은 변경 없이 그대로 전달됩니다.
  • 이 브릿지 (bridge)는 오직 두 가지 로컬 진단 도구 (diagnostic tools)만을 추가합니다.

해당 로컬 도구는 다음과 같습니다:

  • cloakbrowser_binary_info
  • cloakbrowser_bridge_info

그 외 모든 것은 업스트림 Playwright MCP에서 제공됩니다.

저장소 (Repository):

https://github.com/swimmwatch/cloakbrowser-mcp

문서 (Docs):

https://swimmwatch.github.io/cloakbrowser-mcp/

npm:

https://www.npmjs.com/package/cloakbrowser-mcp

이것이 아닌 것

이것은 커스텀 브라우저 자동화 API가 아닙니다.

Playwright MCP 도구 계약 (tool contracts)을 다시 작성하는 포크 (fork)도 아닙니다.

이것은 CAPTCHA 해결 서비스가 아니며, 적절한 테스트 환경 제어, 허용 목록 (allowlists), 또는 사이트 소유자가 승인한 자동화 경로를 대체하는 용도로 취급되어서는 안 됩니다.

목표는 더 좁고 유지보수가 용이합니다. 즉, Playwright MCP 인터페이스 (surface)를 익숙하게 유지하면서, 사용자가 로컬 또는 Docker 기반의 에이전트 워크플로 (workflows)에서 CloakBrowser Chromium을 사용하여 해당 인터페이스를 실행할 수 있도록 하는 것입니다.

왜 업스트림 (upstream) Playwright MCP 계약을 유지해야 하는가?

모든 서버가 조금씩 다른 도구 인터페이스 (tool surface)를 만들어내면 브라우저 MCP 서버를 사용하는 것이 고통스러워질 수 있습니다.

도구 이름, 스키마 (schemas), 그리고 동작이 어긋나면 사용자는 각 런타임 (runtime)마다 동일한 브라우저 워크플로를 새로 배워야 합니다. 클라이언트 (clients)와 프롬프트 (prompts)의 이식성 또한 떨어지게 됩니다.

cloakbrowser-mcp는 정반대의 접근 방식을 취합니다. 브릿지 (bridge)를 작게 유지하여 업스트림 Playwright MCP가 브라우저 도구에 대한 권위 (authoritative)를 유지하도록 합니다.

이는 몇 가지 이유로 중요합니다:

  1. 기존 Playwright MCP 워크플로가 익숙하게 유지됩니다.
  2. 병렬적인 도구 모델을 재설계하지 않고도 업스트림의 개선 사항을 채택할 수 있습니다.
  3. 브릿지는 런타임 배선 (runtime wiring), 진단 (diagnostics), 패키징 (packaging), 그리고 패리티 체크 (parity checks)에 집중할 수 있습니다.
  4. 사용자가 업스트림 Playwright MCP와 동작을 더 쉽게 비교할 수 있습니다.

또한 이 프로젝트는 CI에서 업스트림 기본 도구들과의 패리티 체크를 수행하므로, 전달되는 도구 인터페이스 (tool surface)의 변경 사항을 개발 중에 확인할 수 있습니다.

npm을 이용한 빠른 시작

Node.js 20 이상이 필요합니다.

npx -y cloakbrowser-mcp@latest --help
npx -y cloakbrowser-mcp@latest doctor
npx -y cloakbrowser-mcp@latest

서버를 MCP 클라이언트에 연결하기 전에 로컬 진단 체크를 수행하려면 doctor를 먼저 사용하세요:

npx -y cloakbrowser-mcp@latest doctor --json

기본 전송 방식 (transport)은 stdio이며, 이는 대부분의 로컬 MCP 클라이언트 설정이 기대하는 방식입니다.

Streamable HTTP를 사용하는 경우:

npx -y cloakbrowser-mcp@latest \
  --transport streamable-http \
  --http-port 3000

이렇게 하면 다음 주소로 MCP가 노출됩니다:

또한 다음과 같은 상태 확인 (health probes) 기능을 제공합니다:

curl http://127.0.0.1:3000/healthz
curl http://127.0.0.1:3000/readyz

MCP 클라이언트 설정 (MCP client config)

대부분의 MCP 클라이언트는 동일한 stdio 형태인 command, args, 그리고 선택 사항인 env를 사용합니다.

{
  "mcpServers": {
    "cloakbrowser": {
...

Claude Desktop, Cursor, VS Code, Cline, Continue, Windsurf, Goose, Warp, Codex와 같은 클라이언트에서 동일한 패턴을 사용하십시오. 클라이언트가 JSON 대신 TOML 또는 YAML을 사용하는 경우 주변 설정 형식만 조정하면 됩니다.

Docker

Docker는 반복 가능한 런타임 (runtime)이 필요할 때 유용합니다. 이미지는 고정된 공식 Playwright MCP 이미지를 기반으로 하며 브리지 (bridge)를 포함하고 있습니다.

docker pull swimmwatch/cloakbrowser-mcp:latest
docker run --rm --init -i \
  -v "$PWD/artifacts:/data" \
...

Docker에서 스트리밍 가능한 HTTP (Streamable HTTP)를 사용하는 경우:

docker run --rm --init -p 127.0.0.1:3000:3000 \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
...

동일한 이미지는 GitHub Container Registry에도 게시되어 있습니다:

ghcr.io/swimmwatch/cloakbrowser-mcp

어떤 도구들이 나타나야 하나요?

MCP 클라이언트에 도구 목록을 요청하십시오. 다음과 같은 업스트림 (upstream) Playwright MCP 브라우저 도구들이 보여야 합니다:

  • browser_navigate
  • browser_click
  • browser_type
  • browser_snapshot
  • browser_take_screenshot
  • browser_console_messages
  • browser_network_requests
  • browser_evaluate
  • browser_tabs

또한 다음 두 가지 로컬 진단 도구도 보여야 합니다:

  • cloakbrowser_binary_info
  • cloakbrowser_bridge_info

진단 도구는 다음과 같은 실질적인 설정 질문에 답하기 위해 존재합니다:

  • 어떤 브리지 (bridge) 버전이 실행 중인가?
  • 어떤 업스트림 Playwright MCP 패키지/버전이 해결(resolved)되었는가?
  • 어떤 브라우저 엔진 (browser engine)이 구성되었는가?
  • CloakBrowser 바이너리 (binary)는 어디에 있는가?
  • 어떤 출력 디렉토리 (output directory)가 활성화되어 있는가?

설정 (Configuration)

기본 설정 네임스페이스 (namespace)는 업스트림 Playwright MCP 네임스페이스입니다:

PLAYWRIGHT_MCP_*

Cloak 전용 브리지 토글 (bridge toggles)의 경우:

CLOAK_PLAYWRIGHT_MCP_*

일반적인 예시:

PLAYWRIGHT_MCP_HEADLESS=true
PLAYWRIGHT_MCP_OUTPUT_DIR=/tmp/cloakbrowser-artifacts
PLAYWRIGHT_MCP_OUTPUT_MODE=stdout
...

로컬 HTTP 전송 (local HTTP transport)의 경우:

CLOAK_PLAYWRIGHT_MCP_TRANSPORT=streamable-http
CLOAK_PLAYWRIGHT_MCP_HTTP_HOST=127.0.0.1
CLOAK_PLAYWRIGHT_MCP_HTTP_PORT=3000
...

로컬 개발 환경 외부로 HTTP를 노출하는 경우, 인증 토큰 (auth token)을 설정하세요:

CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN=...

운영 참고 사항 (Operational notes)

실제 워크플로 (workflow)에서 사용하기 전에 알아두어야 할 몇 가지 세부 사항이 있습니다:

  • 첫 번째 브라우저 작업 시 CloakBrowser 바이너리 (binary)가 이미 캐시되어 있지 않다면 다운로드될 수 있습니다.
  • MCP의 표준 입출력 (stdio)이 프로토콜 메시지를 위해 stdout을 사용하므로, 런타임 로그 (runtime logs)가 stdout으로 출력되어서는 안 됩니다.
  • Docker 실행 시 stdio 연결이 유지되도록 -i 옵션을 유지해야 합니다.
  • 브라우저 자식 프로세스 (child processes)가 올바르게 회수(reaped)될 수 있도록 Docker 실행 시 --init을 포함해야 합니다.
  • 특히 Docker 환경에서는 아티팩트 (artifacts)를 알려진 출력 디렉토리에 작성해야 합니다.
  • 재현성 (reproducibility)을 위해 latest 대신 특정 버전을 고정(pin)하여 사용하세요.

예시:

npx -y cloakbrowser-mcp@1.3.0

또는:

docker run --rm --init -i \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:1.3.0

언제 사용해야 하나요? (When should you use it?)

다음과 같은 경우에 적합합니다:

  • Playwright MCP 호환 브라우저 도구가 필요한 경우
  • 로컬 stdio MCP 서버가 필요한 경우
  • Docker 사용이 가능한 브라우저 자동화 런타임 (browser automation runtime)이 필요한 경우
  • HTTP를 통해 연결되는 클라이언트를 위한 스트리밍 가능한 HTTP (Streamable HTTP)가 필요한 경우
  • 상위 Playwright MCP 도구의 계약 (contracts)을 변경하지 않고 CloakBrowser Chromium 런타임을 사용하고자 하는 경우
  • 서버를 에이전트 (agent)에 연결하기 전에 간단한 진단 (diagnostics)을 수행하고자 하는 경우

다음과 같은 경우에는 적합하지 않을 수 있습니다:

  • 호스팅된 브라우저 서비스 (hosted browser service)가 필요한 경우
  • Playwright MCP 도구 대신 커스텀 고수준 브라우저 API (custom high-level browser API)를 원하는 경우
  • 워크플로가 브라우저 자동화 대신 공식 API를 사용해야 하는 경우
  • 테스트 환경이 퍼스트 파티 테스트 키 (first-party test keys)나 화이트리스트 (allowlists)로 문제를 해결할 수 있는 경우

시도해 보기 (Try it)

가장 빠른 방법은 다음과 같습니다:

npx -y cloakbrowser-mcp@latest doctor

다음으로 stdio 설정을 MCP 클라이언트에 추가합니다:

{
  "mcpServers": {
    "cloakbrowser": {
...

프로젝트 링크:

피드백을 환영합니다. 특히 로컬 에이전트 워크플로우에서 Playwright MCP를 이미 사용하고 계신 분들의 의견을 부탁드립니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0