Skip to main content
Glama
chrome-devtools-mcp
by Himangguo

chrome-devtools-mcp

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

前置条件

  • Node.js 18+

  • Chrome 浏览器

Related MCP server: Chrome DevTools MCP

安装

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

  • 仅供开发环境使用,勿集成到生产流程

Available Tools

11 tools
evaluate_jsA

在页面上下文中执行 JavaScript 表达式,返回执行结果。禁止访问 cookie/localStorage/fetch 等敏感 API。

Inputs: expression (required).

get_ancestorsA

获取元素的完整祖先链,每个祖先节点包含指定样式属性值。专为 sticky/overflow/z-index 层叠问题根因定位设计。

Inputs: selector (required), maxDepth, styleProperties.

get_box_modelC

获取元素盒模型尺寸(width/height/margin/padding/border/content)

Inputs: selector (required).

get_computed_stylesA

获取元素所有计算样式(浏览器最终计算值),返回完整的 property: value 键值对

Inputs: selector (required).

get_console_logsC

获取页面控制台日志(MCP 连接后产生的日志)

Inputs: level, limit.

get_dom_treeA

获取 DOM 子树结构,可按选择器定位根节点,depth 控制层级深度(最大 10)

Inputs: depth, selector.

get_layout_metricsA

获取页面视口尺寸和内容尺寸(viewportWidth/viewportHeight/contentWidth/contentHeight)

Inputs: no named parameters.

get_matched_stylesA

获取元素匹配的 CSS 规则列表,包含选择器、来源文件、行号和所有属性

Inputs: selector (required).

get_network_requestsA

获取页面网络请求记录(MCP 连接后发生的请求),可按 URL 关键词过滤

Inputs: limit, url_filter.

list_tabsA

列出当前浏览器所有可调试的 Tab(仅显示 page 类型)

Inputs: no named parameters.

query_selectorA

在 DOM 中查找匹配选择器的所有元素,返回元素基本信息(tagName/id/classList)

Inputs: selector (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of browser inspection: layout, tabs, DOM query, DOM tree, ancestors, styles, box model, JS execution, console, and network. Even the two style-related tools (computed vs. matched) are clearly differentiated.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (get_, list_, query_, evaluate_), making the API predictable and easy to reason about. No mixed conventions or vague verbs.

    Tool Count5/5

    11 tools is well-scoped for a browser debugging server. Each tool covers a distinct capability without unnecessary overlap, and the count feels appropriate for the intended breadth.

    Completeness4/5

    The surface covers DOM, CSS, layout, JS evaluation, console, and network inspection, which are core for debugging. Missing interaction features (e.g., click, navigate, modify styles) suggest a read-only inspector, but that's consistent with the tool descriptions; minor gaps like screenshots or performance tracking could be added.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI coding assistants to control and inspect a live Chrome browser for automated debugging, performance analysis, and web interaction. It leverages Puppeteer and Chrome DevTools to provide capabilities like network monitoring, console logging, and automated browser actions.
      -