chrome-devtools-mcp

让 AI 通过 MCP 协议直接调用 Chrome DevTools Protocol（CDP），获取浏览器运行时 DOM 结构、计算样式、控制台日志、网络请求等信息，彻底解决 AI 只能读源码、无法获取真实运行时上下文的问题。

前置条件

• Node.js 18+
• Chrome 浏览器

安装

npm install
npm run build

启动 Chrome（调试模式）

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug-profile

推荐添加 alias 到 ~/.zshrc，之后直接用 chrome-debug 启动：

alias chrome-debug='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug-profile'

OpenCode 集成

在 ~/.config/opencode/opencode.json 中添加：

{
  "mcp": {
    "chrome-devtools": {
      "type": "local",
      "command": ["node", "/path/to/chrome-devtools-mcp/dist/index.js"],
      "env": {
        "CHROME_DEBUGGING_PORT": "9222"
      },
      "enabled": true
    }
  }
}

注意：command 必须是数组格式，不能是字符串。

查看实时日志

MCP server 的所有 CDP 调用日志写入 ~/chrome-devtools-mcp.log，在任意终端运行以下命令实时查看：

tail -f ~/chrome-devtools-mcp.log

工具清单（11 个）

DOM 工具

工具	说明
list_tabs	列出所有可调试的 Tab（type=page）
query_selector	按 CSS 选择器查找元素，返回 tagName/id/classList
get_dom_tree	获取 DOM 子树，selector 可选，depth 最大 10
get_ancestors	获取元素完整祖先链（含指定样式 + 自动诊断），sticky/overflow/z-index 问题根因定位专用

CSS 工具

工具	说明
get_computed_styles	获取元素计算样式，返回 summary（布局关键属性）+ all（完整属性）
get_matched_styles	获取元素匹配的 CSS 规则列表（含来源文件、行号）
get_box_model	获取元素盒模型尺寸（width/height/margin/padding/border/content）

Runtime 工具

工具	说明
get_layout_metrics	获取页面视口/内容尺寸（viewportWidth/viewportHeight/contentWidth/contentHeight）
evaluate_js	在页面上下文执行 JS 表达式，自动拦截 cookie/localStorage/fetch 等敏感 API
get_console_logs	获取控制台日志，支持按 level 过滤（log/info/warn/error/debug）

Network 工具

工具	说明
get_network_requests	获取网络请求记录，支持 url_filter 关键词过滤，返回 method/status/duration/headers

注意：get_console_logs 和 get_network_requests 只收集 MCP 连接后的事件，连接前的记录无法追溯。

智能诊断（Phase 3）

get_ancestors 会自动在返回结果里附带 diagnosis 字段，无需 AI 额外推理即可定位根因：

{
  "ancestors": [...],
  "diagnosis": {
    "hints": [
      {
        "depth": 2,
        "tagName": "section",
        "classList": ["arco-layout"],
        "issue": "position:sticky 失效 — 祖先节点 overflow 非 visible/unset 会阻断 sticky",
        "property": "overflow",
        "value": "hidden",
        "impact": "blocking"
      }
    ],
    "summary": "发现 1 个阻断性问题。第2层 <section> overflow:hidden"
  }
}

impact 三级：blocking（直接阻断）/ likely（大概率影响）/ possible（可能有影响）

检测覆盖：

• overflow: hidden/scroll/auto/clip → sticky 失效
• transform 非 none → fixed/sticky 失效
• will-change: transform/opacity/filter → 层叠上下文异常
• contain: layout/paint/strict/content → fixed 失效
• filter / backdrop-filter → 层叠上下文异常

典型用法

诊断 sticky 失效

1. 调用 get_computed_styles(".sticky-header")
   → summary.position: sticky（确认已设置）

2. 调用 get_ancestors(".sticky-header")
   → diagnosis.summary: "发现 1 个阻断性问题。第3层 <div.el-scrollbar__wrap> overflow:hidden"
   → 根因定位完成，无需进一步推理

排查 JS 错误

1. 调用 get_console_logs(level="error")
   → 获取页面 error 级别日志

2. 调用 evaluate_js("document.querySelector('.btn').disabled")
   → 获取按钮当前的 disabled 状态

排查接口问题

1. 调用 get_network_requests(url_filter="/api/cooperation")
   → 查看合作相关接口的请求状态和响应时间

安全说明

• 调试端口绑定 127.0.0.1，禁止公网暴露
• evaluate_js 自动拦截 document.cookie、localStorage、sessionStorage、fetch、XMLHttpRequest
• MCP Server 仅本地运行，数据不出 localhost
• 仅供开发环境使用，勿集成到生产流程