chrome-devtools-mcp — 코딩 에이전트에게
크롬 개발자도구를 통째로 쥐여주는 MCP 서버

Google이 직접 만든 Apache-2.0 오픈소스. Claude·Gemini·Cursor·Copilot이 살아있는 크롬 탭을 클릭하고, 네트워크를 들여다보고, 성능 트레이스를 뜨고, Lighthouse 감사를 돌릴 수 있게 해주는 MCP 서버 1.0.

1한 줄 요약

코딩 에이전트가 실제 크롬 탭을 운전하게 만드는 표준 통로

2왜 지금 주목받는가

TrendShift 3위 · "에이전트가 실제 브라우저를 다룬다"는 흐름의 정점

TrendShift 일간 3위(2026-05-22 기준, 543점). 한 줄로 말하면 "AI 코딩 비서가 더 이상 코드만 읽지 않고 실제 화면을 본다"는 흐름의 결정판이다. 2026년 들어 등장한 비슷한 결의 도구들 — browser-use, claude-in-chrome, playwright-mcp — 중에서도 이 레포가 가장 빠르게 성장하는 데에는 이유가 있다.

경쟁 제품 대비 장점

3기술 스택 전체 지도

package.json·rollup·CDP까지 — "Google이 직접 쓰는 도구"의 풀스택

런타임 · 코어

빌드 · 배포

에이전트 통합 · 평가

4아키텍처 심화 분석

stdio JSON-RPC · CDP · Puppeteer가 만나는 4-layer 구조

전체 시스템 구조도

핵심 설계 패턴 1 · MCP 서버 = "LLM-callable 함수의 카탈로그"

MCP 서버는 본질적으로 JSON-RPC over stdin/stdout이다. 클라이언트(에이전트)가 tools/list를 부르면 서버가 등록된 도구의 JSON 스키마를 응답한다. 에이전트는 그 스키마를 LLM 프롬프트에 함수 선언으로 넣고, LLM이 도구를 부르겠다고 하면 tools/call로 다시 서버에 요청한다.

// MCP 한 사이클 (개념)
client → { jsonrpc:"2.0", method:"tools/list", id:1 }
server ← { tools:[ {name:"click", inputSchema:{...}}, ... 48개 ] }

client → { method:"tools/call", params:{
            name:"performance_start_trace",
            arguments:{ url:"https://example.com" } }, id:2 }
server ← { content:[{ type:"text", text:"Trace recording..." }] }

핵심 설계 패턴 2 · Token-Optimized — "요약을 돌려준다"

이 프로젝트의 design-principles.md에 적혀 있는 한 줄: "LCP was 3.2s"가 "50k lines of JSON"보다 낫다.

퍼포먼스 트레이스 원본은 수십 MB짜리 JSON인데, LLM 컨텍스트에 그걸 통째로 던지면 가격 폭탄 + 의미 추출 실패다. 그래서 devtools-frontend의 분석 로직을 가져다가 "LCP는 X.Xs · 원인은 Y 리소스 · 개선책 Z" 같은 의미 단위 요약을 만들어서 돌려준다. 트레이스 원본은 파일로 저장하고 경로만 알려준다.

핵심 설계 패턴 3 · Small, Deterministic Blocks

"한 번에 사이트 분석 다 해줘" 같은 매직 버튼은 의도적으로 안 만든다. 대신 click·screenshot·evaluate_script 같은 작은 결정적 블록을 늘어놓고, LLM이 그걸 조립하게 한다. 그래야 LLM이 중간 결과를 보고 다음 수를 결정할 수 있다(추론 가능성).

핵심 설계 패턴 4 · 카테고리 토글로 도구 풀 축소

--categoryEmulation=false, --categoryPerformance=false, --categoryNetwork=false, --slim 같은 플래그로 노출 도구 수를 줄일 수 있다. LLM은 도구가 많을수록 잘못 선택할 확률이 커지기 때문에 "이번 작업엔 안 쓸 도구는 아예 숨긴다"는 게 정석.

핵심 설계 패턴 5 · 두 가지 브라우저 연결 모드

5디렉토리 구조 해부

npm 패키지로 배포되는 단일 서버 레포

특이한 점들

• scripts/eval_gemini.ts — Google 답게 Gemini로 자체 회귀 테스트를 돌린다. 도구 시그니처를 바꿨을 때 LLM이 여전히 잘 부르는지를 자동 검증.
• scripts/count_tokens.ts — 도구 설명·스키마가 컨텍스트에서 차지하는 토큰을 측정. "도구 늘리면 비용이 얼마나 늘어나나"를 항상 추적.
• scripts/generate-docs.ts — tool-reference.md와 README의 도구 목록을 코드에서 자동 생성. 문서가 코드보다 늦지 않는다.
• .claude-plugin/plugin.json — Claude Code Plugin marketplace에 등록되는 매니페스트. MCP 서버 정의가 들어있다.

6학습 포인트 (기술별)

이 한 레포에서 뽑아 쓸 수 있는 6가지 학습 갈래

① MCP — Model Context Protocol 표준

이 레포는 "MCP 서버 잘 만든 모범 사례"로 그 자체가 교과서다. @modelcontextprotocol/sdk 사용법, JSON-RPC 흐름, 도구 등록·카테고리·옵션 노출 패턴이 다 들어있다.

② Puppeteer + CDP — "헤드리스가 아닌 진짜 브라우저 자동화"

Puppeteer를 단순 페이지 자동화가 아니라 "DevTools Protocol을 직접 부르는 도구"로 쓰는 법을 본다. page.evaluate(), page.tracing.start(), cdpSession.send('Network.enable') 같은 저수준 API가 어떻게 LLM-callable 도구로 매핑되는지.

③ Lighthouse 자동 감사

lighthouse_audit 도구는 Lighthouse 13.3을 내부 모듈로 호출한다. CLI 없이 Node 안에서 audit을 돌리고 JSON 결과를 받는 방법, 그리고 그 JSON에서 LLM이 쓸 만한 요약을 추출하는 방법을 익힐 수 있다.

④ TypeScript + tsc + Rollup 빌드 파이프라인

실제 빌드 워크플로: tsc로 src/**/*.ts를 build/에 컴파일한 뒤 rollup으로 단일 파일로 번들링해 npm 배포한다 (npm run build = tsc && node scripts/post-build.ts). Node 22.6+의 --experimental-strip-types는 이 프로젝트가 채택한 패턴이 아니다. "컴파일 → 번들링 → 배포"의 표준적인 npm 패키지 파이프라인을 잘 따르고 있다.

⑤ Rollup으로 단일 파일 npm 패키지 만들기

rollup-plugin-license로 라이선스 자동 수집, plugin-node-resolve로 의존성 인라이닝. npx chrome-devtools-mcp@latest 한 줄로 모든 게 돌아가는 이유가 여기 있다.

⑥ Token-Optimized API 설계 철학

이건 코드보다도 docs/design-principles.md 한 페이지가 본체다. "Reference over Value", "Self-Healing Errors", "Progressive Complexity" 같은 원칙들은 MCP 서버뿐 아니라 모든 LLM-facing API 설계에 그대로 적용된다.

7하드웨어/시스템 요구사항

로컬 머신에서 돌리는 가벼운 도구 — 단, Chrome이 떠야 한다

샌드박스/원격 환경 주의

샌드박스(Docker, devcontainer, 원격 SSH 머신, VM) 안에서 돌릴 때는 크롬 자체를 띄울 수 없는 경우가 많다. 이때는 --browserUrl로 호스트의 크롬에 붙이는 방식을 써야 한다. README의 "VM ↔ host 포트 포워딩" 트러블슈팅을 미리 읽어두자.

8직접 해볼 수 있는 실습 과제

난이도 ★~★★★★★ · 손이 더러워질수록 배우는 게 많다

9관련 기술 심화 학습 로드맵

8주 코스 — "에이전트가 브라우저를 다루게 만드는 사람"이 되는 길

10핵심 키워드 사전

이 레포를 읽다 만나는 모든 약자·전문용어를 한 번에

11참고 링크

시작하기·깊게 가기·이슈 트래킹

• 레포 본체: github.com/ChromeDevTools/chrome-devtools-mcp
• 도구 레퍼런스 (전체): docs/tool-reference.md
• 설계 원칙 7개조: docs/design-principles.md
• 트러블슈팅: docs/troubleshooting.md
• npm 패키지: npmjs.com/package/chrome-devtools-mcp
• MCP 스펙: modelcontextprotocol.io
• Puppeteer 문서: pptr.dev
• Lighthouse: developer.chrome.com/docs/lighthouse
• CrUX API: developer.chrome.com/docs/crux
• Core Web Vitals 가이드: web.dev/articles/vitals
• TrendShift 페이지: trendshift.io/repositories/15541