chrome-devtools-mcp
CLI 도구ChromeDevTools/chrome-devtools-mcp
AI 코딩 에이전트가 Chrome DevTools를 제어할 수 있게 하는 MCP 서버.
개요
Chrome DevTools MCP 서버로, AI 에이전트가 Chrome 브라우저를 디버깅하고 자동화하며 성능을 분석할 수 있습니다. Puppeteer 및 DevTools 프런트엔드와 통합되어 안정적인 자동화와 성능 인사이트를 제공합니다.
README 미리보기
# Chrome DevTools for Agents\n\n[](https://npmjs.org/package/chrome-devtools-mcp)\n\nChrome DevTools for Agents (`chrome-devtools-mcp`) lets your coding agent (such as Gemini, Claude, Cursor or Copilot)\ncontrol and inspect a live Chrome browser. It acts as a Model-Context-Protocol\n(MCP) server, giving your AI coding assistant access to the full power of\nChrome DevTools for reliable automation, in-depth debugging, and performance analysis.\nA [CLI](docs/cli.md) is also provided for use without MCP.\n\n## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)\n\n## Key features\n\n- **Get performance insights**: Uses [Chrome\n DevTools](https://github.com/ChromeDevTools/devtools-frontend) to record\n traces and extract actionable performance insights.\n- **Advanced browser debugging**: Analyze network requests, take screenshots and\n check browser console messages (with source-mapped stack traces).\n- **Reliable automation**. Uses\n [puppeteer](https://github.com/puppeteer/puppeteer) to automate actions in\n Chrome and automatically wait for action results.\n\n## Disclaimers\n\n`chrome-devtools-mcp` exposes content of the browser instance to the MCP clients\nallowing them to inspect, debug, and modify any data in the browser or DevTools.\nAvoid sharing sensitive or personal information that you don't want to share with\nMCP clients.\n\n`chrome-devtools-mcp` officially supports Google Chrome and [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing/) only.\nOther Chromium-based browsers may work, but this is not guaranteed, and you may encounter unexpected behavior. Use at your own discretion.\nWe are committed to providing fixes and support for the latest version of [Extended Stable Chrome](https://chromiumdash.appspot.com/schedule).\n\nPerformance tools may send trace URLs to the Google CrU
FAQ (5)
문제 해결chrome-devtools-mcp에서 emulate()을 사용하여 mobile viewport와 network throttle을 동시에 설정할 때 'Navigation timeout' 오류를 수정하는 방법은?
이는 chrome-devtools-mcp v1.0.1의 알려진 문제입니다. 네트워크 스로틀이 탐색 타임아웃 곱셈기가 업데이트되기 전에 적용되어, 뷰포트 변경 시 Slow 3G와 같은 느린 네트워크 조건에서 페이지 리로드가 발생할 때 기본 10초 타임아웃이 적용됩니다. 해결 방법: emulate 호출을 두 개의 별도 호출로 분할합니다. 예를 들어, 먼저 networkConditions만으로 emulate을 호출한 다음, 두 번째 호출에서 viewport로 호출합니다(또는 그 반대). 이렇게 하면 확장된 타임아웃 없이 리로드가 발생하는 것을 피할 수 있습니다. 영구적인 수정은 PR #2134에서 제안되었습니다.
문제 해결npm EOVERRIDE 오류(CONNECTION_CLOSED)로 인해 chrome-devtools-mcp Claude Code 플러그인이 시작되지 않는 문제를 해결하는 방법
플러그인은 npx chrome-devtools-mcp@<version>으로 서버를 실행하며, npx는 현재 작업 디렉터리의 package.json을 기준으로 해석합니다. 프로젝트에 직접 종속성과 충돌하는 overrides 항목이 있는 경우(Dependabot/Renovate가 고정된 보안 오버라이드를 업데이트하지 않고 종속성을 올린 후 흔히 발생합니다. 예: "dependencies": {"dompurify": "^3.4.16"} 대 "overrides": {"dompurify": "^3.4.14"}), 서버가 시작되기 전에 npx가 npm error code EOVERRIDE와 함께 종료되고, Claude Code에는 Connection failed (CONNECTION_CLOSED)만 표시됩니다.
해결 방법:
1. 프로젝트의 package.json을 수정합니다: overrides 버전을 직접 종속성과 맞춥니다(오버라이드를 종속성과 동일한 범위로 업데이트). 그런 다음 npm install을 실행합니다.
2. package.json에 충돌하는 overrides가 없는 디렉터리에서 Claude Code를 시작합니다.
3. cwd의 package.json을 우회하여 서버 자체가 작동하는지 확인합니다:
npx -y --prefix "$HOME" chrome-devtools-mcp@1.11.0 --version
또는 sh -c 'cd ~ && npx -y chrome-devtools-mcp@1.11.0 --version'
플러그인 수준 수정: .claude-plugin/plugin.json에서 인라인 mcpServers args에 prefix를 추가하여 npx가 프로젝트의 package.json을 무시하도록 합니다: "args": ["--prefix", "${CLAUDE_PLUGIN_DATA}", "chrome-devtools-mcp@<version>"]. 참고로 Claude Code는 ${CLAUDE_PLUGIN_DATA}와 ${HOME}을 확장하지만 ${PLUGIN_DATA}는 확장하지 않습니다(이는 Claude Code가 무시하는 함께 제공되는 mcp.json에 나타납니다).
문제 해결take_heapsnapshot가 동일한 .heapsnapshot 파일을 덮어쓴 후에도 힙 스냅샷 도구에 이전 데이터가 표시되는 이유는 무엇인가요?
힙 스냅샷은 처음 로드된 후 파일 경로를 기준으로 캐시됩니다. take_heapsnapshot로 같은 경로를 덮어써도 캐시된 스냅샷이 무효화되지 않으므로, get_heapsnapshot_details, query_heapsnapshot_objects 및 유사한 도구들은 계속 이전 캡처를 분석합니다. 강제로 다시 로드하려면 다시 분석하기 전에 해당 경로에 대해 close_heapsnapshot을 호출하세요: {"name":"close_heapsnapshot","arguments":{"filePath":"/path/to/same.heapsnapshot"}} 그런 다음 get_heapsnapshot_details 또는 query_heapsnapshot_objects를 호출합니다. 또는 snapshot-<timestamp>.heapsnapshot처럼 캡처마다 고유한 filePath를 사용하여 캐시를 완전히 피할 수 있습니다.
문제 해결--allowUnrestrictedPaths=false가 작동하지 않을 때 Chrome DevTools MCP CLI의 파일 접근을 임시 디렉터리로 제한하려면 어떻게 해야 하나요?
이것은 chrome-devtools-mcp 1.10.1 및 main 커밋 b2f522c의 버그입니다: 명시적으로 지정한 --allowUnrestrictedPaths=false가 CLI 모드에서 무시되며, 1.10.1에서는 해당 플래그가 데몬으로 전달되지 않습니다. 해결 방법으로 --workspace를 사용하여 파일 도구를 OS 임시 디렉터리로 제한하세요:
chrome-devtools stop
chrome-devtools start --workspace="$(node -p "require('os').tmpdir()")" --no-usage-statistics --no-performance-crux재시작 후에는 해당 디렉터리 외부에 대한 쓰기가 Access denied: path ... is not within any of the configured workspace roots 오류와 함께 실패해야 합니다. chrome-devtools status로 실행 중인 데몬을 확인하세요. 또는 명시적인 --allowUnrestrictedPaths=false를 적용하는 수정 사항이 포함된 릴리스로 업그레이드하세요. --workspace는 더 이상 사용되지 않는(deprecated) 해당 플래그의 권장 대체재로 계속 유지됩니다.
문제 해결Chrome DevTools MCP를 사용할 때 'Allow remote debugging' 권한 대화상자를 우회하는 방법은 무엇인가요?
전용 Chrome 프로필을 사용하여 원격 디버깅을 활성화하세요. Chrome을 --remote-debugging-port=9222 --user-data-dir=/path/to/profile로 실행합니다. 그런 다음 MCP 서버를 http://127.0.0.1:9222에 연결합니다. 이렇게 하면 전용 프로필이 디버깅을 위해 사전 승인되어 있으므로 권한 대화상자가 표시되지 않습니다. 개발 및 테스트에 권장됩니다. 보안 문제로 인해 권한 승인을 유지하는 기능은 구현되지 않았습니다.