chrome-debugger-mcp

English | 中文

English

브레이크포인트 기반 Chrome 디버깅을 위한 MCP 서버입니다.

chrome-debugger-mcp는 Chrome DevTools Protocol의 핵심 기능을 MCP 도구로 노출하여, AI 에이전트가 실제 Chrome 탭에 연결하고, 실행을 일시 중지하고, 스코프 값을 검사하고, 현재 호출 프레임 내에서 표현식을 평가하고, 정적 소스에서 추측하는 대신 런타임 사실을 바탕으로 코드를 단계별로 실행할 수 있게 해줍니다.

일반적인 브라우저 자동화 서버가 아닙니다. 초점은 런타임 디버깅에 있습니다.

핵심 기능

• 사용자의 명시적 확인 후 CDP를 통해 실제 Chrome 탭에 연결

• 브레이크포인트 또는 debugger; 문에서 일시 중지하고 기대하는 정확한 일시 중지를 대기

• 일시 중지된 프레임에서 local, closure, module 스코프 값 읽기

• 현재 호출 프레임에서 JavaScript를 평가하고 실행을 단계별로 진행

• 깔끔하게 재개하여 에이전트가 실제 런타임 값으로 계속 작업할 수 있게 함

데모

데모: 에이전트가 Chrome을 실행하고, 브레이크포인트를 기다리고, 실제 스코프 변수를 검사하고, 추측 대신 런타임 사실로 재개합니다.

MCP 클라이언트 구성

게시된 패키지 사용

{
  "mcpServers": {
    "chrome-debugger": {
      "command": "npx",
      "args": ["-y", "chrome-debugger-mcp"]
    }
  }
}

설치

npm에서

npx -y chrome-debugger-mcp

또는 전역으로 설치:

npm install -g chrome-debugger-mcp

소스에서

pnpm install
pnpm build
node dist/index.js

기타 주요 기능

• 원격 디버깅이 활성화된 전용 Chrome 인스턴스 실행

• 소스 코드를 수정하지 않고 DevTools 브레이크포인트 설정 및 제거

• CDP를 통해 페이지를 새로고침하여 탐색 후 브레이크포인트가 안정적으로 바인딩되도록 함

• MCP 클라이언트의 요청 타임아웃이 짧은 경우 디버거 상태 폴링

• 클라이언트가 사용자에게 표시할 수 있는 _ui 페이로드 및 로깅 메시지 출력

도움이 되는 이유

많은 브라우저 중심 MCP 도구는 DOM 상호작용과 네트워크 검사에 강하지만 런타임 디버깅에는 약합니다. 이 서버는 MCP 클라이언트에 Chrome DevTools에서 일반적으로 사용하는 누락된 루프를 제공합니다: 올바른 탭에 연결하고, 올바른 시점에 일시 중지하고, 실제 값을 검사하고, 필요시 단계별로 실행하고, 깔끔하게 재개합니다.

또한 에이전트의 일반적인 실수를 방지하는 안전장치를 추가합니다:

• 연결할 탭을 추측하는 것

• 런타임 값을 검사하지 않고 동작을 결론짓는 것

• reloadPage()와 waitForSpecificPause() 사이에 턴을 종료하는 것

요구 사항

• Google Chrome이 로컬에 설치되어 있어야 함

• stdio 서버와 도구 호출을 지원하는 MCP 클라이언트

• 디버깅하려는 애플리케이션에 대한 접근 권한

• 임시 debugger; 문을 삽입하려면 로컬 소스 접근 권한

도구 모델

서버는 stdio를 통해 실행되며 MCP 도구를 노출합니다. 가장 중요한 도구는 다음과 같습니다:

• startDebuggingSession: 권장 디버깅 워크플로우와 에이전트 동작에 대한 중요한 규칙을 반환

• launchChrome: 원격 디버깅이 활성화된 전용 Chrome 인스턴스 실행

• listTargets: 사용 가능한 Chrome 탭을 나열하고 사용자가 하나를 선택하도록 요구

• connect: 확인된 탭에 연결

• setBreakpoint: 소스 파일을 수정하지 않고 CDP 브레이크포인트 생성

• removeBreakpoint: setBreakpoint로 생성된 브레이크포인트 제거

• reloadPage: CDP를 통해 현재 페이지 새로고침

• waitForSpecificPause: 다음 일시 중지를 기다리고 대상 파일 및 줄과 일치하는지 확인

• waitForPause: 위치 일치 없이 임의의 일시 중지 대기

• getScopeVariables: 일시 중지된 프레임에서 local, closure, module 스코프 값 읽기

• evaluate: 일시 중지된 호출 프레임에서 JavaScript 실행

• stepInto, stepOver, stepOut: 표준 실행 제어

• resume: 검사 후 실행 재개

• getStatus: 연결 또는 일시 중지 상태에 대한 비차단 폴링

• forcePause: 다음 JavaScript 문에서 일시 중지 요청

권장 워크플로우

AI 클라이언트를 위한 의도된 흐름은 다음과 같습니다:

1. startDebuggingSession()을 호출합니다.

2. launchChrome()을 호출하거나 CDP 포트가 있는 이미 실행 중인 Chrome 인스턴스를 사용합니다.

3. listTargets()를 호출하고 전체 탭 목록을 사용자에게 표시합니다.

4. 사용자가 정확한 페이지 URL을 확인할 때까지 기다립니다.

5. connect({ targetUrl })을 호출합니다.

6. 로컬 소스 코드에 임시 debugger; 문을 삽입하거나 setBreakpoint()를 호출합니다.

7. reloadPage()를 호출합니다.

8. 같은 턴에서 즉시 waitForSpecificPause()를 호출합니다.

9. getScopeVariables()와 evaluate()를 호출하여 런타임 값을 검사합니다.

10. 필요한 경우 stepInto(), stepOver(), stepOut()으로 단계별로 실행합니다.

11. resume()을 호출합니다.

12. 소스 코드에서 임시 debugger; 문을 제거합니다.

에이전트 작성자를 위한 중요한 규칙

이 서버는 사람뿐만 아니라 도구를 사용하는 에이전트를 위해 설계되었습니다. MCP 클라이언트에 통합하는 경우 다음 규칙을 지키세요:

• listTargets()를 절대 건너뛰지 마세요.

• 탭이 하나만 열려 있어도 대상 URL을 추측하지 마세요.

• connect() 전에 항상 사용자의 명시적 확인을 기다리세요.

• reloadPage() 후에는 같은 턴에서 즉시 waitForSpecificPause() 또는 waitForPause()를 호출하세요.

• 런타임 값을 직접 검사할 수 있을 때 정적 코드로 동작을 설명하지 마세요.

• 검사 후 항상 resume()을 호출하세요.

• 소스 코드에 임시 debugger; 문을 추가했다면 완료 전에 제거하세요.

waitForSpecificPause 일치 방식

waitForSpecificPause는 임의의 일시 중지를 기다리는 것보다 더 안정적이므로 선호되는 대기 기본 요소입니다.

두 가지 전략으로 일시 중지를 일치시킵니다:

1. URL 조각 + 줄 허용 오차

2. URL 조각 + debugger-statement 일시 중지 이유

두 번째 경로는 소스 맵, 트랜스파일링 또는 번들링으로 인해 컴파일된 줄 번호가 편집기 줄 번호와 달라질 때 중요합니다.

예제 도구 시퀀스

로컬 Vite 앱을 디버깅하는 에이전트는 다음과 같이 할 수 있습니다:

1. launchChrome({ dryRun: true })

2. launchChrome()

3. listTargets()

4. 사용자가 http://127.0.0.1:5173을 확인할 때까지 대기

5. connect({ targetUrl: "127.0.0.1:5173" })

6. App.jsx에 debugger; 삽입

7. reloadPage()

8. waitForSpecificPause({ urlFragment: "App.jsx", line: 62, actionHint: "click the Refetch payloads button" })

9. getScopeVariables()

10. evaluate({ expression: "payload.modules" })

11. resume()

Chrome 실행 동작

launchChrome()은 전용 프로필을 사용하므로 사용자의 일반 브라우저 세션을 방해하지 않습니다.

기본값:

• 원격 디버깅 포트: 9222

• 프로필 디렉터리: ~/.chrome-debug-profile

예상 Chrome 바이너리 위치:

• macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

• Linux: google-chrome

• Windows: C:\Program Files\Google\Chrome\Application\chrome.exe

자동 실행이 실패하면 도구는 사용자가 수동으로 실행할 수 있는 명령을 반환합니다.

로컬 플레이그라운드

이 저장소에는 test/ 아래에 일회용 테스트 앱이 포함되어 있어 실제 브라우저 워크플로우에 대해 디버거 서버를 테스트할 수 있습니다.

목 서비스 시작

cd test/service
node src/server.js

서비스는 http://127.0.0.1:3030에서 수신합니다.

웹 앱 시작

cd test/web
pnpm install
pnpm dev

웹 앱은 http://127.0.0.1:5173에서 실행됩니다.

일시 중지하기 좋은 위치:

• test/web/src/App.jsx의 loadWorkbench 내부

• test/web/src/App.jsx의 loadModuleDetail 내부

• test/web/src/App.jsx의 미완성 세부 섹션 주변

검사할 가치가 있는 런타임 페이로드 영역:

• summaryCards

• modules

• apiContracts

• nextActions

• responseShape

문제 해결

대상이 없음

Chrome이 --remote-debugging-port=9222로 실행 중이고 대상 페이지가 열려 있는지 확인하세요.

둘 이상의 탭이 targetUrl과 일치

더 구체적인 하위 문자열을 전달하여 일치가 고유해지도록 하세요.

waitForPause 또는 waitForSpecificPause 시간 초과

다음과 같은 경우 발생할 수 있습니다:

• 페이지 작업이 트리거되지 않음

• 잘못된 브레이크포인트가 설정됨

• MCP 클라이언트 자체의 요청 타임아웃이 도구 호출보다 짧음

클라이언트가 빠르게 시간 초과되면 getStatus()로 폴링하거나 클라이언트 타임아웃을 늘리세요.

일시 중지된 줄 번호가 편집기 줄과 일치하지 않음

번들러와 트랜스파일러는 컴파일된 줄 번호를 이동시킬 수 있습니다. waitForSpecificPause()를 사용하고 URL 조각 일치와 debugger-statement 의미론에 의존하세요.

Chrome이 자동으로 실행되지 않음

머신이 기본이 아닌 Chrome 설치 경로를 사용할 수 있습니다. 반환된 실행 명령을 수동으로 실행하거나 환경에 맞게 구현을 조정하세요.

개발

pnpm install
pnpm build
node dist/index.js

구현 위치:

• src/index.ts: MCP 도구 정의 및 사용자 대상 워크플로우 힌트

• src/chrome-manager.ts: Chrome DevTools Protocol 통합 및 디버거 상태 관리

라이선스

MIT

Related MCP server: Chrome DevTools MCP

中文

一个面向 Chrome 断点调试的 MCP Server。

chrome-debugger-mcp 把 Chrome DevTools Protocol 的核心调试能力暴露为 MCP 工具，让 AI agent 可以连接真实的 Chrome 标签页，在运行时暂停执行、读取作用域变量、在当前调用帧中执行表达式、单步跟踪代码，并基于真实值继续任务，而不是只靠静态源码猜测行为。

它不是通用浏览器自动化工具。它的重点是运行时调试。

核心能力

• 在用户明确确认后，通过 CDP 连接真实的 Chrome 标签页

• 在断点或 debugger; 命中时暂停，并等待指定文件和行附近的 pause

• 读取当前暂停帧中的 local、closure、module 作用域变量

• 在当前调用帧里执行 JavaScript，并继续单步跟踪

• 检查完成后恢复执行，让 agent 基于真实运行时值继续工作

功能演示

演示流程：agent 拉起 Chrome，等待断点命中，读取真实作用域变量，再基于运行时事实继续执行，而不是靠猜测推进。

MCP 客户端配置

使用已发布包

{
  "mcpServers": {
    "chrome-debugger": {
      "command": "npx",
      "args": ["-y", "chrome-debugger-mcp"]
    }
  }
}

安装方式

从 npm 使用

npx -y chrome-debugger-mcp

也可以全局安装：

npm install -g chrome-debugger-mcp

从源码运行

pnpm install
pnpm build
node dist/index.js

其他特点

• 启动带远程调试端口的独立 Chrome 实例

• 无需修改源码即可设置和移除断点

• 通过 CDP 重载页面，确保跳转后断点可靠绑定

• 当 MCP 客户端请求超时较短时，可轮询调试器状态

• 输出 _ui 结果和 logging 消息，方便客户端展示给用户

为什么适合这个场景

很多浏览器方向的 MCP 工具更擅长 DOM 操作和网络请求观察，但不擅长回答运行时调试问题。这个服务补上的是 Chrome DevTools 里最关键的那条链路：连接正确标签页、在正确时机暂停、读取真实值、必要时单步跟踪、最后恢复执行。

它也内置了几条 guardrails，避免 agent 出现这些常见错误：

• 猜测应该连接哪个标签页

• 没看运行时值就直接下结论

• 在 reloadPage() 和 waitForSpecificPause() 之间错误地结束当前轮次

运行要求

• 本机安装了 Google Chrome

• 使用支持 stdio MCP server 和工具调用的 MCP 客户端

• 可以访问你要调试的应用

• 如果要插入临时 debugger;，需要能访问本地源码

工具模型

这个服务通过 stdio 运行，并暴露一组 MCP tools。最核心的工具有：

• startDebuggingSession：返回推荐调试流程和 agent 行为约束

• launchChrome：启动带远程调试能力的独立 Chrome 实例

• listTargets：列出可调试标签页，并要求用户做选择

• connect：连接到已确认的目标标签页

• setBreakpoint：在不改源码的情况下通过 CDP 设置断点

• removeBreakpoint：移除通过 setBreakpoint 创建的断点

• reloadPage：通过 CDP 重载当前页面

• waitForSpecificPause：等待下一次暂停，并判断是否命中目标文件和行

• waitForPause：不做位置匹配，等待任意暂停

• getScopeVariables：读取当前暂停帧中的局部、闭包、模块作用域变量

• evaluate：在暂停调用帧中执行 JavaScript

• stepInto、stepOver、stepOut：标准单步控制

• resume：检查完毕后恢复执行

• getStatus：非阻塞方式查询是否已连接、是否已暂停

• forcePause：请求在下一条 JavaScript 语句处暂停

推荐工作流

对于 AI 客户端，建议流程是：

1. 调用 startDebuggingSession()。

2. 调用 launchChrome()，或直接复用已经开启 CDP 端口的 Chrome。

3. 调用 listTargets()，并把完整标签页列表展示给用户。

4. 等待用户明确确认要调试的页面 URL。

5. 调用 connect({ targetUrl })。

6. 在本地源码插入临时 debugger;，或者调用 setBreakpoint()。

7. 调用 reloadPage()。

8. 在同一轮里立刻调用 waitForSpecificPause()。

9. 调用 getScopeVariables() 和 evaluate() 检查运行时值。

10. 必要时使用 stepInto()、stepOver()、stepOut() 继续跟踪。

11. 调用 resume()。

12. 删除源码里临时加入的 debugger;。

给 Agent 作者的重要规则

这个服务首先是为会调用工具的 agent 设计的，而不仅仅是给人手动点工具用。如果你要把它接入自己的 MCP 客户端，建议遵守这些规则：

• 不要跳过 listTargets()。

• 即使只看到一个标签页，也不要猜测目标 URL。

• 一定要等用户明确确认后再调用 connect()。

• 调用 reloadPage() 后，必须在同一轮里立刻调用 waitForSpecificPause() 或 waitForPause()。

• 能读取运行时值时，不要只根据静态代码解释行为。

• 检查完之后一定要 resume()。

• 如果向源码里插入了临时 debugger;，结束前要清理掉。

waitForSpecificPause 如何匹配

waitForSpecificPause 是首选的等待工具，因为它比“等待任意暂停”更可靠。

它有两层匹配策略：

1. URL 片段加行号容差

2. URL 片段加 debugger-statement 暂停原因

第二层匹配对经过 source map、转译、打包后的代码尤其重要，因为编译后的行号可能和编辑器行号不完全一致。

调用序列示例

一个 agent 调试本地 Vite 应用时，调用顺序大致会像这样：

1. launchChrome({ dryRun: true })

2. launchChrome()

3. listTargets()

4. 等用户确认 http://127.0.0.1:5173

5. connect({ targetUrl: "127.0.0.1:5173" })

6. 在 App.jsx 插入 debugger;

7. reloadPage()

8. waitForSpecificPause({ urlFragment: "App.jsx", line: 62, actionHint: "click the Refetch payloads button" })

9. getScopeVariables()

10. evaluate({ expression: "payload.modules" })

11. resume()

Chrome 启动行为

launchChrome() 会使用独立 profile，不会影响用户平时正在用的浏览器会话。

默认值：

• 远程调试端口：9222

• profile 目录：~/.chrome-debug-profile

默认 Chrome 可执行文件路径：

• macOS：/Applications/Google Chrome.app/Contents/MacOS/Google Chrome

• Linux：google-chrome

• Windows：C:\Program Files\Google\Chrome\Application\chrome.exe

如果自动启动失败，工具会返回一条可供用户手动执行的启动命令。

本地 Playground

仓库里带了一个可丢弃的测试应用，目录在 test/。你可以直接用它验证这个调试 MCP 的完整链路。

启动 mock service

cd test/service
node src/server.js

服务监听在 http://127.0.0.1:3030。

启动 web app

cd test/web
pnpm install
pnpm dev

Web 应用运行在 http://127.0.0.1:5173。

建议下断点的位置：

• test/web/src/App.jsx 里的 loadWorkbench

• test/web/src/App.jsx 里的 loadModuleDetail

• test/web/src/App.jsx 里尚未完成的 detail 区域附近

值得在运行时查看的 payload 字段：

• summaryCards

• modules

• apiContracts

• nextActions

• responseShape

故障排查

找不到 targets

确认 Chrome 是用 --remote-debugging-port=9222 启动的，并且目标页面已经打开。

targetUrl 匹配到多个标签页

传入更具体的 URL 子串，保证匹配结果唯一。

waitForPause 或 waitForSpecificPause 超时

常见原因包括：

• 页面操作没有真正触发

• 断点位置不对

• MCP 客户端自身的请求超时时间比工具调用更短

如果客户端超时比较短，可以改用 getStatus() 轮询，或者调大客户端超时。

暂停时的行号和编辑器对不上

打包和转译会导致编译后的行号偏移。优先使用 waitForSpecificPause()，并依赖 URL 片段匹配加 debugger-statement 语义匹配。

Chrome 无法自动启动

机器上的 Chrome 安装路径可能不是默认值。可以直接运行工具返回的启动命令，或者按你的环境调整实现。

开发

pnpm install
pnpm build
node dist/index.js

主要实现文件：

• src/index.ts：MCP 工具定义和面向用户的工作流提示

• src/chrome-manager.ts：Chrome DevTools Protocol 集成和调试状态管理

许可证

MIT