구성

Matthias Rohmer
José Luis Zapata

에이전트용 Chrome DevTools를 구성하여 브라우저와 상호작용하는 방식, 사용 설정된 도구, 데이터 처리 방식을 맞춤설정할 수 있습니다.

모델 컨텍스트 프로토콜 (MCP) 클라이언트 구성 파일의 args 배열에 명령줄 플래그를 전달하여 서버를 구성합니다. 일반적으로 config.json 파일입니다.

예를 들어 헤드리스 모드에서 Chrome을 실행하고 Canary 채널을 사용하려면 다음 구성을 사용합니다.

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--headless",
        "--channel=canary"
      ]
    }
  }
}

일반적인 구성 시나리오

다음 시나리오에서는 에이전트용 Chrome DevTools를 구성하는 일반적인 방법을 설명합니다.

헤드리스 모드로 실행

표시되는 브라우저 창 없이 백그라운드 작업을 실행하려면 헤드리스 (UI 없음) 모드에서 Chrome을 실행합니다. 서버 인수에 --headless 플래그를 추가합니다.

기존 브라우저 세션에 연결

기본적으로 에이전트용 DevTools는 새 Chrome 인스턴스를 시작합니다. 하지만 에이전트를 기존 브라우저 세션에 연결할 수 있습니다. 이미 시작한 세션에서 상담사가 문제를 조사해야 하는 경우 (예: 이미 로그인한 경우) 유용합니다.

다음 두 가지 방법으로 기존 세션에 연결할 수 있습니다.

자동 연결 (Chrome 144 이상)

--autoConnect 플래그를 사용하면 MCP 서버가 활성 Chrome 인스턴스에 자동으로 연결됩니다.

  1. 실행 중인 Chrome 브라우저에서 chrome://inspect/#remote-debugging로 이동하여 원격 디버깅을 사용 설정합니다.
  2. MCP 구성에 --autoConnect를 추가합니다. json "args": ["chrome-devtools-mcp@latest", "--autoConnect"]
  3. 에이전트가 연결을 시도하면 Chrome에 권한을 요청하는 대화상자가 표시됩니다. 허용을 클릭합니다.

수동 연결

샌드박스 환경과 같이 --autoConnect를 사용할 수 없는 경우 디버깅 포트를 사용하여 Chrome을 수동으로 시작하고 --browser-url를 사용하여 연결할 수 있습니다.

  1. 원격 디버깅이 사용 설정되고 맞춤 사용자 데이터 디렉터리가 있는 터미널에서 Chrome을 시작합니다.
    • macOS: shell /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
    • Windows: shell start chrome --remote-debugging-port=9222 --user-data-dir=%TEMP%\chrome-profile-stable
    • Linux: shell google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
  2. 이 포트에 연결하도록 에이전트를 구성합니다. json "args": ["chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]

임시 디렉터리 외부에서 파일 액세스 허용

파일을 읽거나 쓰는 도구 (예: 스크린샷, trace 저장 또는 확장 프로그램 로드)는 구성된 작업공간 루트 내의 경로에만 액세스할 수 있습니다. 서버는 MCP 루트 기능을 통해 MCP 클라이언트가 제공하는 루트와 --filesystemRoot(별칭 --workspace)로 전달하는 모든 디렉터리를 사용합니다. 클라이언트가 루트를 제공하지 않고 --filesystemRoot를 설정하지 않으면 파일 액세스가 OS 임시 디렉터리로 제한됩니다. 다른 경로에 대한 요청은 Access denied: ... is not within any of the configured workspace roots 오류와 함께 실패합니다.

프로젝트 디렉터리에 대한 액세스를 허용하려면 서버 인수에 --filesystemRoot를 추가합니다. 플래그를 반복하여 여러 디렉터리를 허용할 수 있습니다.

"args": ["chrome-devtools-mcp@latest", "--filesystemRoot=/path/to/project"]

구성 옵션 참조

다음 섹션에는 사용 가능한 구성 플래그가 나와 있습니다. 최신 옵션 및 업데이트는 Chrome DevTools MCP GitHub 저장소를 참고하세요.

연결 옵션

이 옵션을 사용하여 서버가 Chrome에 연결되는 방식을 구성합니다.

플래그 유형 기본값 설명
--autoConnect 또는 --auto-connect 부울 false 로컬에서 실행되는 Chrome (144 이상) 인스턴스에 자동으로 연결됩니다. chrome://inspect/#remote-debugging를 사용하여 원격 디버깅을 사용 설정해야 합니다.
--browserUrl 또는 --browser-url
-u		 문자열 false 실행 중인 디버그 가능한 Chrome 인스턴스 (예: http://127.0.0.1:9222)에 연결합니다.
--wsEndpoint 또는 --ws-endpoint
-w		 문자열 false 실행 중인 Chrome 인스턴스에 연결할 WebSocket 엔드포인트입니다 (예: ws://127.0.0.1:9222/devtools/browser/<id>). --browserUrl의 대안입니다.
--wsHeaders 또는 --ws-headers 문자열 false JSON 형식의 WebSocket 연결용 커스텀 헤더입니다 (예: '{"Authorization":"Bearer token"}'). --wsEndpoint에서만 작동합니다.

브라우저 실행 옵션

이러한 옵션은 MCP 서버가 Chrome을 시작할 때 적용됩니다.

플래그 유형 기본값 설명
--headless 부울 false 헤드리스 (UI 없음) 모드로 Chrome을 실행합니다.
--channel 문자열 stable 사용할 Chrome 채널을 지정합니다. 선택지는 canary, dev, beta, stable입니다.
--executablePath 또는 --executable-path
-e		 문자열 false 맞춤 Chrome 실행 파일의 경로입니다.
--userDataDir 또는 --user-data-dir 문자열 설명 참조 사용자 데이터 디렉터리의 경로입니다. 기본값은 $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE입니다.
--isolated 부울 false 브라우저가 닫힐 때 자동으로 정리되는 임시 사용자 데이터 디렉터리를 만듭니다.
--viewport 문자열 false 초기 표시 영역 크기 (예: 1280x720). 헤드리스 모드에서 최대 크기는 3840x2160입니다.
--proxyServer 또는 --proxy-server 문자열 false Chrome에 전달된 프록시 서버 구성입니다.
--chromeArg 또는 --chrome-arg 배열 false Chrome에 전달할 추가 인수입니다.
--ignoreDefaultChromeArg 또는 --ignore-default-chrome-arg 배열 false Chrome의 기본 인수를 명시적으로 사용 중지합니다.

보안 및 개인 정보 보호 옵션

이러한 옵션을 사용하여 보안 설정 및 데이터 개인 정보 보호를 관리합니다.

플래그 유형 기본값 설명
--acceptInsecureCerts 또는 --accept-insecure-certs 부울 false 자체 서명 및 만료된 인증서와 관련된 오류를 무시합니다. 주의해서 사용하세요.
--blockedUrlPattern 또는 --blocked-url-pattern 배열 false 지정된 URL 패턴을 차단하여 네트워크 액세스를 제한합니다 (URLPattern 사용). 탐색 및 하위 리소스를 차단합니다.
--allowedUrlPattern 또는 --allowed-url-pattern 배열 false 지정된 URL 패턴만 허용하여 네트워크 액세스를 제한합니다. Chrome 149 이상이 필요합니다.
--redactNetworkHeaders 또는 --redact-network-headers 부울 false 민감한 네트워크 헤더를 클라이언트에 반환하기 전에 수정합니다.
--usageStatistics 또는 --usage-statistics 부울 true 도구를 개선하기 위해 사용 통계 수집을 사용 설정합니다. CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS 또는 CI 환경 변수를 사용하여 사용 중지할 수도 있습니다.
--performanceCrux 또는 --performance-crux 부울 true 성능 트레이스의 URL을 Google CrUX API로 전송하여 실제 사용자 환경 데이터를 가져옵니다.
--javascriptEvaluation 또는 --javascript-evaluation 부울 true JavaScript 실행을 사용 중지하려면 false로 설정합니다. 사용 중지되면 스크립트 평가 도구가 사용 중지되고 navigate_page의 initScript 매개변수가 사용 중지되며 javascript:, data: 또는 vbscript: URL로 이동이 허용되지 않습니다.
--filesystemRoot 또는 --filesystem-root
--workspace		 배열 OS 임시 디렉터리 파일 액세스 도구가 MCP 클라이언트에서 제공하는 루트 외에 사용할 수 있는 디렉터리입니다. 두 번 이상 지정할 수 있습니다. 임시 디렉터리 외부의 파일 액세스 허용을 참고하세요.
--allowUnrestrictedPaths 또는 --allow-unrestricted-paths 부울 false 지원 중단됨: 대신 --workspace=/를 사용하세요. MCP 클라이언트가 루트를 제공하지 않을 때 적용되는 경로 제한을 사용 중지합니다.

기능 카테고리

이러한 플래그를 사용하여 도구 그룹을 사용 설정하거나 사용 중지할 수 있습니다.

플래그 유형 기본값 설명
--categoryInput 또는 --category-input 부울 true 입력과 관련된 도구를 사용 설정합니다.
--categoryNavigation 또는 --category-navigation 부울 true 탐색과 관련된 도구를 사용 설정합니다.
--categoryEmulation 또는 --category-emulation 부울 true 에뮬레이션 관련 도구를 사용 설정합니다.
--categoryNetwork 또는 --category-network 부울 true 네트워크 관련 도구를 사용 설정합니다.
--categoryPerformance 또는 --category-performance 부울 true 성능 관련 도구를 사용 설정합니다.
--categoryDebugging 또는 --category-debugging 부울 true 디버깅과 관련된 도구를 사용 설정합니다.
--categoryMemory 또는 --category-memory 부울 true 메모리와 관련된 도구를 사용 설정합니다.
--categoryExtensions 또는 --category-extensions 부울 false 확장 프로그램과 관련된 도구를 사용 설정합니다. 파이프 연결에서만 지원됩니다.
--categoryPwa 또는 --category-pwa 부울 false 프로그레시브 웹 앱 (설치, 실행, 제거, OS 상태)을 자동화하는 도구를 사용 설정합니다. 파이프 연결에서만 지원됩니다.
--categoryExperimentalThirdParty 또는 --category-experimental-third-party 부울 false 검사된 페이지에서 노출되는 서드 파티 개발자 도구를 사용 설정합니다.
--categoryExperimentalWebmcp 또는 --category-experimental-webmcp 부울 false WebMCP 도구 디버깅을 사용 설정합니다. WebMCP 기능이 사용 설정된 Chrome 149 이상이 필요합니다.
--memoryDebugging 또는 --memory-debugging 부울 false 메모리 디버깅 도구를 사용 설정합니다.

스크린샷 옵션

이러한 옵션을 사용하여 에이전트가 스크린샷을 캡처하는 방법을 맞춤설정합니다.

플래그 유형 기본값 설명
--screenshotFormat 또는 --screenshot-format 문자열 false 기본 출력 형식 (png)을 재정의합니다. 선택사항: jpeg, png, webp jpeg 및 webp 형식은 크기가 작아 AI 대화에서 컨텍스트 크기를 줄이는 데 도움이 됩니다.
--screenshotQuality 또는 --screenshot-quality 숫자 false jpeg 및 webp의 압축 품질 (0~100)을 재정의합니다.
--screenshotMaxWidth 또는 --screenshot-max-width 숫자 false 최대 너비(픽셀)입니다. 더 큰 스크린샷은 축소됩니다.
--screenshotMaxHeight 또는 --screenshot-max-height 숫자 false 최대 높이(픽셀)입니다. 큰 스크린샷은 축소됩니다.

실험용 옵션

이 옵션을 사용하여 개발 중인 실험 기능을 사용 설정합니다.

플래그 유형 기본값 설명
--experimentalDevtools 또는 --experimental-devtools 부울 false DevTools 타겟에 대한 자동화를 사용 설정합니다.
--experimentalVision 또는 --experimental-vision 부울 false 좌표 기반 도구 (예: click_at)를 사용 설정합니다. 일반적으로 스크린샷을 보고 정확한 좌표를 생성할 수 있는 컴퓨터 사용 모델이 필요합니다.
--experimentalStructuredContent 또는 --experimental-structured-content 부울 false 구조화된 형식의 콘텐츠를 출력합니다.
--experimentalIncludeAllPages 또는 --experimental-include-all-pages 부울 false 모든 종류의 페이지 (예: 웹 뷰 및 백그라운드 페이지)가 포함됩니다.
--experimentalScreencast 또는 --experimental-screencast 부울 false 스크린캐스트 도구를 노출합니다 (PATH에 ffmpeg 필요).
--experimentalFfmpegPath 또는 --experimental-ffmpeg-path 문자열 false ffmpeg 실행 파일의 경로입니다.
--experimentalScreencastFps 또는 --experimental-screencast-fps 숫자 false 스크린캐스트 녹화의 초당 프레임 수입니다. 값이 낮을수록 ffmpeg에서 인코딩할 수 있는 것보다 빠르게 프레임을 생성하는 페이지의 메모리 압박을 줄일 수 있습니다.

기타 옵션

이러한 옵션을 사용하여 로깅, 페이지 라우팅, 소스 맵을 구성하거나 간소화된 도구 집합을 사용 설정합니다.

플래그 유형 기본값 설명
--slim 부울 false 탐색, 스크립트 실행, 스크린샷의 세 가지 도구로 구성된 간단한 세트를 노출합니다. 기본적인 브라우저 작업에 유용합니다.
--pageIdRouting 또는 --page-id-routing 부울 true 페이지 범위 도구에 pageId가 필요하며 페이지 ID로 요청을 라우팅하므로 동시 에이전트 세션에 유용합니다. 사용 중지하려면 --no-page-id-routing를 사용합니다.
--sourceMaps 또는 --source-maps 부울 true DevTools에서 소스 맵을 사용 설정합니다. 사용 중지하려면 --no-source-maps을 사용합니다.
--logFile 또는 --log-file 문자열 false 디버그 로그를 쓸 파일의 경로입니다. NODE_DEBUG 환경 변수를 *로 설정하여 상세 로그를 사용 설정합니다.
--config 문자열 false JSON 구성 파일의 경로입니다.

환경 변수

다음 환경 변수를 사용하여 서버를 구성할 수도 있습니다.

  • CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 설정하면 사용 통계 수집이 사용 중지됩니다 (--no-usage-statistics와 동일).
  • CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: 설정된 경우 업데이트에 대한 주기적 검사를 사용 중지합니다.
  • CI: 설정된 경우 사용 통계 수집을 사용 중지합니다.
  • NODE_DEBUG: *로 설정하여 상세 디버그 로깅을 사용 설정합니다 (--logFile와 함께 작동).