코딩 에이전트를 내 Chrome에 연결하기

권장 환경: LaunchRepo를 가장 잘 활용하려면 Claude나 Codex 데스크톱 앱 대신 터미널에서 Claude Code CLI 또는 Codex CLI를 사용할 것을 강력히 권장합니다. 이는 저희가 권장하는 워크플로일 뿐이며, 권한이 달라지거나 작업이 중단 없이 실행된다는 보장은 아닙니다.

Chrome 원격 디버깅을 통한 Chrome DevTools MCP를 사용하세요. 최신 Node.js LTS 릴리스, npm, Google Chrome이 필요합니다. 기록은 로컬 대시보드가 저장하고, Chrome은 에이전트가 제어합니다. 워커 하나로 시작하고, 실행하는 동안 MCP 연결을 계속 열어 두세요. 브라우저 확장 프로그램 방식의 연결이나 다른 브라우저 제어 통합은 사용하지 마세요.

설정 방식 고르기

• Chrome 144 이상: 자동 연결은 Windows, macOS, Linux에서 동작합니다.
• macOS: 터미널 권한을 확인하세요.
• 자동 연결을 쓸 수 없거나 별도 워커가 필요한 경우: macOS, Windows, Linux용 전용 프로필을 사용하세요.
• 제출하기 전: 연결 테스트를 수행하세요.

node --version, npm --version, chrome://version을 확인하세요. Windows에서는 Windows용 네이티브 Node/npm과 Chrome을 사용하세요. WSL을 쓰려면 연결을 따로 설정해야 합니다.

기존 Chrome 연결하기

1. Chrome 144 이상에서 chrome://inspect/#remote-debugging을 열고 원격 디버깅을 켜세요. 해당 설정이 보이지 않으면 아래 설명한 전용 프로필을 사용하세요(사용이 허용된 경우).
2. 에이전트의 MCP 설정에 Chrome DevTools MCP를 등록하세요. 아래 JSON은 macOS/Linux용 일반 예시이며, 에이전트에 따라 설정 형식이 다를 수 있습니다.

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect", "--no-usage-statistics", "--no-performance-crux"]
    }
  }
}

Windows에서는 "command": "cmd"와 다음 인수를 사용하세요.

["/c", "npx", "-y", "chrome-devtools-mcp@latest", "--autoConnect", "--no-usage-statistics", "--no-performance-crux"]

3. 무해한 브라우저 동작을 하나 실행하고, 의도한 창에서 Chrome의 연결 요청을 승인하세요. 그런 다음 아래 테스트를 수행하세요.

처음 실행할 때 패키지를 내려받습니다. 설정을 마친 뒤에는 테스트를 거친 버전으로 고정하세요. 공식 설정 문서와 클라이언트 설정 문서를 참고하세요.

전용 프로필: 운영체제 고르기

비공개 워크스페이스에서, 공유 폴더나 동기화 폴더 밖에서 실행하세요. 프로필에는 로그인 정보가 들어 있으므로 Git이 무시하도록 해 두세요. 필요한 계정에는 직접 로그인하세요. Chrome 136 이상에서는 이 디버깅 플래그를 쓰려면 기본값이 아닌 프로필이 필요합니다.

macOS

mkdir -p .browser/chrome
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir="$PWD/.browser/chrome" about:blank

Windows PowerShell

$launchrepoChrome = @(
  "$env:ProgramFiles\Google\Chrome\Application\chrome.exe",
  "${env:ProgramFiles(x86)}\Google\Chrome\Application\chrome.exe",
  "$env:LOCALAPPDATA\Google\Chrome\Application\chrome.exe"
) | Where-Object { Test-Path $_ } | Select-Object -First 1
if (-not $launchrepoChrome) { throw 'Locate Google Chrome first' }
New-Item -ItemType Directory -Force '.browser/chrome' | Out-Null
$launchrepoProfile = (Resolve-Path '.browser/chrome').Path
Start-Process -FilePath $launchrepoChrome -ArgumentList "--remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 --user-data-dir=`"$launchrepoProfile`" about:blank"

Linux

launchrepo_chrome=$(command -v google-chrome || command -v google-chrome-stable)
if [ -z "$launchrepo_chrome" ]; then
  echo "Install or locate Google Chrome first."
else
  mkdir -p .browser/chrome
  "$launchrepo_chrome" \
    --remote-debugging-address=127.0.0.1 \
    --remote-debugging-port=9222 \
    --user-data-dir="$PWD/.browser/chrome" about:blank
fi

Chrome을 실행한 터미널은 열어 두세요. MCP 인수의 --autoConnect를 --browserUrl=http://127.0.0.1:9222로 바꾸세요. 두 옵션을 함께 쓰면 안 됩니다. 포트는 로컬에만 두고, 절대 외부로 터널링하지 마세요. 리스너를 확인하세요. macOS에서는 lsof -nP -iTCP:9222 -sTCP:LISTEN, Linux에서는 ss -ltnp 'sport = :9222', Windows에서는 Get-NetTCPConnection -State Listen -LocalPort 9222 | Select-Object LocalAddress, OwningProcess를 실행합니다. 루프백 주소만 허용됩니다. 다른 프로그램이 포트를 쓰고 있다면 비어 있는 포트를 골라 두 설정을 모두 바꾸세요. 관련 없는 브라우저를 강제 종료하거나 사용 중인 프로필 잠금 파일을 삭제하지 마세요.

macOS 권한

MCP를 실행하는 앱이 무엇인지 확인하세요. Terminal, iTerm, 또는 사용하는 에디터/에이전트 앱입니다. macOS가 보호된 Chrome 파일에 대한 접근을 거부한다면:

1. 시스템 설정 → 개인정보 보호 및 보안 → 전체 디스크 접근 권한을 여세요.
2. + 버튼으로 실제 호스트 앱을 추가하고, 인증한 뒤 활성화하세요.
3. 앱을 완전히 종료했다가 다시 열고, 다시 연결한 뒤 테스트를 반복하세요.

이것은 권한 점검일 뿐, 모든 CDP 연결에 필요한 요건이 아닙니다. 연결이 잘 된다면 불필요하게 더 넓은 권한을 주지 마세요. CDP만 쓰는 연결에는 보통 손쉬운 사용, 자동화, 화면 기록 권한이 필요 없습니다. Chrome의 연결 승인은 이와 별개이며, 재시작 후 다시 요청될 수 있습니다.

연결 테스트하기

에이전트에게 새 탭에서 https://example.com을 열고, 페이지 제목과 본문의 메인 헤딩을 읽고, 그 탭을 식별해 달라고 요청하세요. 그 창을 직접 지켜보세요. MCP 프로세스가 실행 중이라는 사실만으로는 아무것도 증명되지 않습니다. 다음으로 대상 디렉터리에 로그인하고, 실제로 로그인된 계정이 의도한 계정인지 확인하세요. OAuth가 성공했다는 것만으로 로그인이 증명되지는 않습니다. 메일함은 합의된 권한 범위 안에서 확인하세요.

이어서 같은 탭에서 에이전트가 navigator.webdriver를 평가하게 하세요. 값은 반드시 false여야 합니다. true라면 MCP 설정에 --autoConnect(전용 프로필이면 --browserUrl)가 빠져 있어 Chrome DevTools MCP가 자체 자동화 Chrome을 띄운 것입니다. 이 상태에서는 Cloudflare Turnstile 같은 봇 검사가 계속 “확인 중”에 머물고, 직접 풀 수 있는 챌린지가 나타나지 않습니다. 설정을 고치고 에이전트 세션을 다시 시작한 뒤 테스트를 반복하세요. 스텔스 플래그나 스크립트로 이 값을 숨기지 마세요.

onboarding.json이나 SESSION.md에는 통과/실패 여부와 민감하지 않은 메모만 저장하세요. 쿠키, 인증 링크, 브라우저 세션 기록은 복사하지 마세요. CAPTCHA와 2단계 인증은 직접 완료하세요. 제출(Submit) 후 타임아웃이 나면 다시 시도하기 전에 플랫폼에서 상태를 확인하세요. 엉뚱한 창이 움직이면 멈추고 연결을 점검하세요. 이 테스트를 거치지 않고는 이 지침만으로 내 OS와 에이전트 조합이 제대로 동작한다고 보증할 수 없습니다.

워커 두 개와 창 정리

실행 플래너는 제출 10건, 워커 최대 2개로 시작합니다. 워커마다 서로 다른 플랫폼 배정, Chrome 프로필, 포트, MCP 연결이 필요합니다. 예를 들어 .browser/worker-1은 9222, .browser/worker-2는 9223을 쓰세요. 각각 따로 테스트하세요. 호스트가 워커를 서로 다른 연결로 나눠 줄 수 없다면 하나만 쓰세요.

제출마다 전용 창을 하나씩 쓰세요. 제출이 확인되면 증거와 결과를 저장한 다음, 그 창과 그 창에서 연 로그인/인증 탭만 닫으세요. 개인 창, 공유 메일함, 대시보드, 저장되지 않은 폼, 사람에게 넘긴 작업은 열어 두세요. MCP로 창을 닫을 수 없다면 그 창에 속한 탭을 닫고, 소유자가 직접 정리해야 할 남은 항목을 기록하세요. 프로필은 그대로 두고, 마지막 창을 닫아 MCP 연결이 끊기면 다시 연결하세요. 다음 단계는 온보딩 가이드에서 설명합니다.