benjaminr/chrome-devtools-mcp

MCP (Model Context Protocol)를 통해 Chrome DevTools Protocol 통합을 제공하는 MCP (Model Context Protocol) 서버입니다. 이를 통해 Chrome의 개발자 도구에 연결하여 웹 애플리케이션을 디버깅할 수 있습니다.

간편한 원클릭 설치를 위해 Claude Desktop Extension (.dxt)로 제공됩니다!

이 MCP 서버는 Claude와 Chrome의 디버깅 기능 사이의 가교 역할을 합니다. Claude Desktop에 설치하면 다음과 같은 작업을 수행할 수 있습니다:

• Claude를 Chrome에서 실행 중인 모든 웹 애플리케이션에 연결
• 네트워크 요청 (Network requests), 콘솔 오류 (Console errors), 성능 문제 (Performance issues) 디버깅
• JavaScript 객체 검사 및 브라우저 컨텍스트 내 코드 실행
• Claude와의 자연스러운 대화를 통해 애플리케이션을 실시간으로 모니터링

참고: 이것은 Claude Desktop 내에서 실행되는 MCP 서버입니다. 별도의 서버나 프로세스를 실행할 필요가 없습니다.

네트워크 모니터링 (Network Monitoring): 필터링 옵션을 사용하여 HTTP 요청/응답을 캡처하고 분석
콘솔 통합 (Console Integration): 브라우저 콘솔 로그를 읽고, 오류를 분석하며, JavaScript를 실행
성능 지표 (Performance Metrics): 타이밍 데이터, 리소스 로딩 및 메모리 사용량
페이지 검사 (Page Inspection): DOM 정보, 페이지 메트릭 및 멀티 프레임 (Multi-frame) 지원
스토리지 액세스 (Storage Access): 쿠키 (Cookies), localStorage 및 sessionStorage 읽기
실시간 모니터링 (Real-time Monitoring): 라이브 콘솔 출력 추적
객체 검사 (Object Inspection): JavaScript 객체 및 변수 검사

빌드된 확장 프로그램 다운로드:

• Releases에서 최신 .dxt 파일을 다운로드합니다 - Claude Desktop을 엽니다
• Extensions로 이동하여 다운로드한 .dxt 파일을 설치합니다 - 필요한 경우 확장 프로그램 설정에서 Chrome 경로를 구성합니다

확장 프로그램에는 모든 종속성 (Dependencies)이 포함되어 있어 즉시 사용할 준비가 되어 있습니다!

빠른 설치 (가장 일반적인 방법):

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp
mcp install server.py -n "Chrome DevTools MCP" --with-editable .

참고: mcp 명령어는 Python MCP SDK의 일부입니다. 아직 사용할 수 없다면 pip install mcp로 설치하세요.

모든 설치 옵션:

# 저장소 클론 (Clone the repository)
git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp
...

Claude Code CLI 사용자용:

이 저장소를 클론하세요

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp

UV를 사용하여 종속성 설치 (가상 환경(venv) 생성)

uv sync # .venv를 생성하고 종속성을 설치합니다

절대 경로를 사용하여 Claude CLI로 MCP 서버 추가

중요: Claude Code가 올바르게 작동하려면 Python 인터프리터(interpreter)와 서버 스크립트(script) 모두에 대한 절대 경로(absolute paths)가 필요합니다.

절대 경로를 사용한 권장 설정:

# 절대 경로 가져오기
SERVER_PATH="$(pwd)/server.py"
PYTHON_PATH="$(pwd)/.venv/bin/python"
...

대안: 시스템 Python 사용 (종속성이 전역적으로 설치된 경우):

# 종속성을 전역적으로 설치한 경우에만 사용하세요
claude mcp add chrome-devtools python "$(pwd)/server.py" -e CHROME_DEBUG_PORT=9222

사용자 정의 범위(custom scope) 사용 시:

# 사용자 범위(user scope)에 추가 (모든 프로젝트에서 사용 가능)
claude mcp add chrome-devtools "$(pwd)/.venv/bin/python" "$(pwd)/server.py" -s user -e CHROME_DEBUG_PORT=9222
# 프로젝트 범위(project scope)에 추가 (이 프로젝트에만 적용)
...

설치 확인

# 구성된 MCP 서버 목록 표시
claude mcp list
# 서버에 대한 세부 정보 확인 (경로가 절대 경로인지 확인하세요)
...

일반적인 경로 문제 및 해결 방법:

문제: "python: command not found" 또는 "server.py not found"
해결: 위에서 설명한 대로 절대 경로를 사용하세요.

문제: 서버 시작 시 "ModuleNotFoundError" 발생
해결: 종속성이 설치된 venv Python 인터프리터를 사용하세요.

문제: 서버가 시작되지 않거나 연결 끊김(disconnected)으로 표시됨
해결: 명령어를 수동으로 테스트하세요: /path/to/.venv/bin/python /path/to/server.py

이 저장소를 클론하세요

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp

종속성 설치

uv 사용 시 (권장):

uv sync

pip 사용 시:

pip install -r requirements.txt

Claude Desktop 설정에 추가

Claude Desktop 설정 파일을 편집하세요:

macOS:~/Library/Application Support/Claude/claude_desktop_config.json

Windows:%APPDATA%/Claude/claude_desktop_config.json

{
"mcpServers": {
"chrome-devtools": {
...

Claude Desktop 재시작

설치(어떤 방식이든) 후, 서버를 사용할 수 있는지 확인하세요:

• Claude Desktop을 엽니다.
• 대화창에서 MCP 도구(tools)를 확인합니다.
• 간단한 명령어를 실행해 봅:
  get_connection_status()

다른 MCP 클라이언트의 경우, 서버를 직접 실행하세요:

python server.py

Claude Desktop에 설치되면, 다음과 같이 모든 웹 애플리케이션의 디버깅을 시작할 수 있습니다:

원스텝 설정 (권장):

start_chrome_and_connect("localhost:3000")

localhost:3000을 사용자의 애플리케이션 URL로 교체하세요

Chrome을 자동으로 찾지 못하는 경우:

start_chrome_and_connect("localhost:3000", chrome_path="/path/to/chrome")

chrome_path 파라미터를 사용하여 사용자 정의 Chrome 위치를 지정하세요

이 명령은 다음을 수행합니다:

• 디버깅이 활성화된 상태로 Chrome 실행
• 사용자의 애플리케이션으로 이동
• MCP 서버를 Chrome에 연결

수동 설정 (단계별 진행을 선호하는 경우):

start_chrome()
navigate_to_url("localhost:3000")
connect_to_browser()

연결되면 다음 명령어들을 사용하세요:

get_network_requests()

• HTTP 트래픽 확인

get_console_error_summary()

• JavaScript 에러 분석

inspect_console_object("window")

• 모든 JavaScript 객체 검사

start_chrome(port?, url?, headless?, chrome_path?, auto_connect?)

• 원격 디버깅 및 선택적 자동 연결 기능과 함께 Chrome 실행

start_chrome_and_connect(url, port?, headless?, chrome_path?)

• Chrome 실행, 연결 및 이동을 한 번에 수행

connect_to_browser(port?)

• 기존 Chrome 인스턴스에 연결

navigate_to_url(url)

• 특정 URL로 이동

disconnect_from_browser()

• 브라우저 연결 해제

get_connection_status()

• 연결 상태 확인

get_network_requests(filter_domain?, filter_status?, limit?)

• 필터링을 통한 네트워크 요청 가져오기
  get_network_response(request_id)

• 본문을 포함한 상세 응답 데이터 가져오기

get_console_logs(level?, limit?)

• 브라우저 콘솔 로그 가져오기
  get_console_error_summary()

• 에러 및 경고의 정리된 요약 가져오기
  execute_javascript(code)

• 브라우저 컨텍스트에서 JavaScript 실행
  clear_console()

• 브라우저 콘솔 비우기
  inspect_console_object(expression)

• 모든 JavaScript 객체 심층 조사 (Deep inspect)
  monitor_console_live(duration_seconds)

• 실시간으로 콘솔 출력 모니터링

get_page_info()

• 종합적인 페이지 메트릭 (Metrics) 및 성능 데이터 가져오기
  evaluate_in_all_frames(code)

• 모든 프레임/iframe에서 JavaScript 실행
  get_performance_metrics()

• 상세 성능 메트릭 (Performance metrics) 및 리소스 타이밍 (Resource timing) 가져오기

get_storage_usage_and_quota(origin)

• 스토리지 사용량 및 할당량 (Quota) 정보 가져오기
  clear_storage_for_origin(origin, storage_types?)

• 유형 및 오리진 (Origin)별로 스토리지 삭제
  get_all_cookies()

• 모든 브라우저 쿠키 가져오기
  clear_all_cookies()

• 모든 브라우저 쿠키 삭제
  set_cookie(name, value, domain, path?, expires?, http_only?, secure?, same_site?)

• 쿠키 설정
  get_cookies(domain?)

• 선택적 도메인 필터링을 통한 브라우저 쿠키 가져오기
  get_storage_key_for_frame(frame_id)

• 특정 프레임에 대한 스토리지 키 가져오기
  track_cache_storage(origin, enable?)

• 캐시 스토리지 (Cache storage) 추적 활성화/비활성화
  track_indexeddb(origin, enable?)

• IndexedDB 추적 활성화/비활성화
  override_storage_quota(origin, quota_size_mb?)

• 스토리지 할당량 (Storage quota) 재정의

웹 애플리케이션이 API 호출을 수행할 때 실패하거나 예상치 못한 데이터를 반환하는 경우:

간편한 설정: 한 단계 명령어를 사용하여 Chrome을 시작하고 앱으로 이동하세요:

예시 워크플로우:

사용자: "localhost:3000에서 실행 중인 내 React 앱을 디버깅해야 해"
Claude: 디버깅이 활성화된 상태로 Chrome을 시작하고 앱으로 이동하겠습니다.
start_chrome_and_connect("localhost:3000")
...

수동 설정 (선호하는 경우):

Chrome 시작: start_chrome()을 사용하세요

애플리케이션으로 이동: navigate_to_url("localhost:3000")를 사용하세요

연결: connect_to_browser()를 사용하세요

네트워크 트래픽 모니터링: get_network_requests()를 사용하여 모든 API 호출을 확인하세요

웹 애플리케이션에 JavaScript 에러가 발생하거나 예상치 못한 동작이 나타날 때:

애플리케이션으로 이동: 연결된 Chrome 인스턴스에서 애플리케이션으로 이동하세요
콘솔 에러 확인: get_console_error_summary()를 사용하여 모든 에러를 확인하세요
실시간 에러 모니터링: monitor_console_live(10)를 사용하여 상호작용 중에 발생하는 새로운 에러를 관찰하세요
변수 조사: inspect_console_object("myVariable")를 사용하여 애플리케이션 상태를 검토하세요

워크플로우 예시:

사용자: "내 React 컴포넌트가 제대로 업데이트되지 않아요"
Claude: JavaScript 콘솔에 에러가 있는지 확인해 보겠습니다.
get_console_error_summary()
...

웹 애플리케이션의 로딩이 느리거나 메모리를 너무 많이 사용할 때:

애플리케이션 로드: 연결된 브라우저에서 애플리케이션을 로드하세요
페이지 메트릭 확인: get_page_info()를 사용하여 로딩 시간과 리소스 개수를 확인하세요
성능 분석: get_performance_metrics()를 사용하여 상세한 타이밍 데이터를 확인하세요
메모리 사용량 모니터링: 성능 메트릭(performance metrics)에서 메모리 정보를 확인하세요

워크플로우 예시:

사용자: "내 애플리케이션의 로딩 시간이 너무 길어요"
Claude: 애플리케이션의 성능을 분석해 보겠습니다.
get_page_info()
...

로그인 또는 세션 관리가 작동하지 않을 때:

로그인 페이지로 이동: 로그인 페이지로 이동하세요
쿠키 확인: get_cookies()를 사용하여 인증 쿠키를 확인하세요
로그인 중 네트워크 모니터링: 로그인 프로세스 동안 monitor_console_live()와 get_network_requests()를 사용하세요
저장된 데이터 검토: JavaScript 실행을 사용하여 localStorage/sessionStorage를 확인하세요

워크플로우 예시:

사용자: "사용자들이 로그인 상태를 유지하지 못해요"
Claude: 인증 설정을 확인해 보겠습니다.
get_cookies()
...

get_document(depth?, pierce?)

• DOM 문서 구조(DOM document structure)를 가져옵니다.

query_selector(node_id, selector)

• CSS 선택자(CSS selector)로 단일 요소를 찾습니다.

query_selector_all(node_id, selector)

• CSS 선택자(CSS selector)로 여러 요소를 찾습니다.
  get_element_attributes(node_id)

• 요소의 모든 속성(attributes)을 가져옵니다.
  get_element_outer_html(node_id)

• 요소의 외부 HTML (outer HTML)을 가져옵니다.
  get_element_box_model(node_id)

• 레이아웃 정보(layout information)를 가져옵니다.
  describe_element(node_id, depth?)

• 상세한 요소 설명을 가져옵니다.
  get_element_at_position(x, y)

• 화면 위치(screen position)에 있는 요소를 가져옵니다.
  search_elements(query)

• 텍스트/속성(text/attributes)으로 DOM 요소를 검색합니다.
  focus_element(node_id)

• DOM 요소에 포커스(focus)를 맞춥니다.

get_computed_styles(node_id)

• 계산된 CSS 스타일(computed CSS styles)을 가져옵니다.
  get_inline_styles(node_id)

• 인라인 스타일(inline styles)을 가져옵니다.
  get_matched_styles(node_id)

• 요소와 일치하는 모든 CSS 규칙(CSS rules)을 가져옵니다.
  get_stylesheet_text(stylesheet_id)

• 스타일시트(stylesheet) 내용을 가져옵니다.
  get_background_colors(node_id)

• 배경색(background colors)과 글꼴(fonts)을 가져옵니다.
  get_platform_fonts(node_id)

• 플랫폼 글꼴(platform font) 정보를 가져옵니다.
  get_media_queries()

• 모든 미디어 쿼리(media queries)를 가져옵니다.
  collect_css_class_names(stylesheet_id)

• CSS 클래스 이름(CSS class names)을 수집합니다.
  start_css_coverage_tracking()

• CSS 커버리지 추적(CSS coverage tracking)을 시작합니다.
  stop_css_coverage_tracking()

• CSS 커버리지 추적을 중단하고 결과를 가져옵니다.

작업 (Task)	명령 (Command)
Chrome을 시작하고 앱에 연결	start_chrome_and_connect("localhost:3000")
...

CHROME_DEBUG_PORT

• Chrome 원격 디버깅 포트 (기본값: 9222)

MCP 프로토콜 버전 (MCP Protocol Version): 2024-11-05
최소 Python 버전 (Minimum Python Version): 3.10+
지원되는 MCP 클라이언트 (Supported MCP Clients): Claude Desktop, 모든 MCP 호환 클라이언트
패키지 매니저 (Package Manager): uv (권장) 또는 pip

• 웹 애플리케이션을 실행 중인 상태로 유지합니다 (예: npm run dev, python -m http.server 등)

• 애플리케이션에 접속 가능한 URL을 확인합니다.

• Claude Desktop을 통해 애플리케이션에 연결합니다: start_chrome_and_connect("localhost:3000") (애플리케이션의 URL로 교체하세요)

• MCP 도구를 사용하여 애플리케이션을 디버깅합니다:

  • 네트워크 요청(network requests) 모니터링
  • 콘솔 에러(console errors) 확인
  • JavaScript 객체(JavaScript objects) 검사
  • 성능(performance) 분석

• 에디터에서 코드 변경 (Make changes to your code)

• 애플리케이션과 새로고침 또는 상호작용 (Refresh or interact)

• 실시간 데이터로 디버깅 지속 (Continue debugging)

단계별 제어를 선호하는 경우:

start_chrome()

• 디버깅 모드로 Chrome 실행

• navigate_to_url("your-app-url")를 사용하여 애플리케이션으로 이동

• connect_to_browser()를 사용하여 MCP 서버에 연결

• 필요에 따라 디버깅 도구 사용

• 개발 환경 (development environments)에서만 사용하십시오.

• 프로덕션 (production) Chrome 인스턴스에는 절대 연결하지 마십시오.

• 이 서버는 localhost 디버깅 전용으로 설계되었습니다.

• 데이터는 영구적으로 저장되지 않으며 모든 데이터는 세션 기반 (session-based)입니다.

서버가 Claude에 나타나지만 "비활성화됨 (disabled)"으로 표시되는 경우, 다음 단계를 시도하십시오:

• Claude Desktop 로그 확인 (Check Claude Desktop logs):
  • macOS: ~/Library/Logs/Claude/mcp*.log
  • Windows: %APPDATA%/Claude/logs/mcp*.log