GitHub 52k Starchrome-devtools-mcp从零部署完整教程 · 新手照着做就能跑起来 · 效率工具指南 · 原创教程摘要Chrome DevTools MCP 安装配置教程本文从零讲解如何把 Chrome 官方 MCP 服务器接入 Claude Code、Cursor、VS Code让 AI 编程助手自动打开浏览器、截图、抓包、跑 Lighthouse 性能审计。附 Windows 环境 7 个高频坑的完整解决方案与命令速查。AI 写的网页出了 bug还要自己开 F12 一点点查Chrome 官方出品的 chrome-devtools-mcp 能让你的 AI 编程助手直接操作一个真实运行的 Chrome打开页面、点击、填表、读控制台报错、抓网络请求、录性能 trace、跑 Lighthouse 审计全程一句话搞定。本文完整走通三种部署方式并整理了 7 个 Windows 高频坑的排查方案新手照着做就能跑起来。本文要点项目基于 TypeScript / Node.js发布包零运行时依赖当前版本 1.9.0要求 Node 20.19 或 22.1223 以上均可 Chrome 稳定版三种部署方式全部讲透npx 一行命令、npm 全局安装、源码构建走不通随时换路7 个 Windows 高频坑的完整解决方案包括「npm 全局安装后命令找不到」「客户端连接报 -32000」这类新手必踩的坑5 个真实使用场景AI 自动查报错、截图确认、性能分析、网络检查、终端直用接入 VS Code、Cursor、Claude Code、Codex 四款主流客户端的完整配置一、项目简介chrome-devtools-mcp全称 Chrome DevTools for agents是 Chrome 官方出品的 MCP 服务器。把它接入你的 AI 编程助手后AI 就能通过 Chrome DevTools 协议控制一个真实运行的 Chrome 浏览器打开网页、点击按钮、填写表单、读取页面结构、抓取网络请求、查看控制台报错还能录制性能 trace 和跑 Lighthouse 审计。它解决了 AI 编程助手最尴尬的问题——看不见页面。以前 AI 改完前端代码只能靠猜现在它能自己打开浏览器看真实渲染结果、读报错、截图确认甚至帮你分析页面为什么加载慢。二、GitHub 项目数据项目主页https://github.com/ChromeDevTools/chrome-devtools-mcp项目数据Star52k维护方ChromeDevToolsGoogle Chrome 官方团队主要语言TypeScript技术栈Node.js MCP 协议 Puppeteer驱动 Chrome许可证Apache-2.0当前版本1.9.0npm持续活跃更新三、环境准备从零开始整个项目只需要两样东西Node.js和Chrome 浏览器。环境要求验证命令Node.js含 npm20.19 / 22.12 / 23装最新 LTS 最省心node -v、npm -vChrome当前稳定版或更新本教程使用 153.0.8010.36见下方 PowerShell 命令Git仅源码路径需要任意近期版本git --version3.1 安装 Node.js下载官网 https://nodejs.org/zh-cn 下载 LTS 版本的 Windows Installer.msi 文件。安装双击 .msi 一路「下一步」。安装向导里Add to PATH与 npm 选项默认已勾选保持勾选不要取消否则后面命令会找不到。验证新开 PowerShell 窗口运行node-vnpm-v两个命令都输出版本号即成功。若提示「不是内部或外部命令」注销重登或重启终端再试。3.2 安装 Chrome下载官网 https://www.google.com/chrome/ 加载慢可用 https://www.google.cn/chrome/ 。双击安装包默认路径安装即可。验证PowerShell(Get-ItemC:\Program Files\Google\Chrome\Application\chrome.exe).VersionInfo.ProductVersion⚠️ 官方只支持 Google Chrome 和 Chrome for TestingEdge、360 等 Chromium 内核浏览器不保证兼容。四、详细部署步骤三条路径走不通就换路径一npx 直跑官方推荐最省事npx 是 npm 自带的命令执行工具自动下载并运行指定包不占全局环境。在 PowerShell 执行npx-ychrome-devtools-mcplatest--help输出一长串参数说明–headless、–isolated、–slim、–channel 等即部署成功。版本验证npx-ychrome-devtools-mcplatest--version# 输出1.9.0-y自动确认 npx 的下载询问latest表示始终用最新版。路径二npm 全局安装命令更短npminstall-gchrome-devtools-mcp这个包没有运行时依赖安装只要几秒。验证chrome-devtools-mcp--version# 输出1.9.0❗ 如果提示「不是内部或外部命令」是 npm 的全局命令目录不在 PATH 里解决办法见「坑 1」。路径三源码构建兜底 / 二次开发需要先装 Githttps://git-scm.com/download/win 下载安装一路默认验证git --version。gitclone https://github.com/ChromeDevTools/chrome-devtools-mcp.gitcdchrome-devtools-mcpnpmci# 按锁文件精确安装依赖约 496 个包npmrun build# TypeScript 编译产物在 build/ 目录运行验证nodebuild/src/bin/chrome-devtools-mcp.js--version# 输出1.9.0 国内网络npm ci慢可换镜像源npm ci --registryhttps://registry.npmmirror.com。git clone 失败可改用 gitcode 镜像 gh_mirrors/ 或 Gitee 同步仓库。部署的最后一步接入你的 AI 客户端通用的配置 JSON{mcpServers:{chrome-devtools:{command:npx,args:[-y,chrome-devtools-mcplatest]}}}客户端接入方式VS Code / Copilot命令面板CtrlShiftP运行Chat: Install Plugin From Source粘贴ChromeDevTools/chrome-devtools-mcp回车推荐含 MCP 和配套技能或点项目 README 里的「Install Server」一键按钮Cursor点项目 README 里的「Install in Cursor」按钮或 Cursor Settings → MCP → New MCP Server粘贴上面的通用 JSONClaude Code终端执行claude mcp add chrome-devtools --scope user npx chrome-devtools-mcplatestCodex终端执行codex mcp add chrome-devtools -- npx chrome-devtools-mcplatestWindows 11 建议按「坑 3」用 cmd /c 方式配置接入后的第一次测试在客户端对话里输入Check the performance of https://developers.chrome.comAI 会自动启动 Chrome 并录制性能 trace。 服务器不会在连接时就打开浏览器只有 AI 调用需要浏览器的工具时 Chrome 才会自动启动平时不影响你正常使用浏览器。五、使用详解按场景学接入成功后共有 29 个工具能力。按五个最常见场景演示用法。场景 1让 AI 打开网页、截图给你看直接说「打开 https://example.com 并截图给我」。AI 会调用 new_page 自动拉起 Chrome默认独立无痕实例不影响你正在用的浏览器导航并截图返回。场景 2AI 改完前端让它自己验证页面结构让 AI 读取页面结构take_snapshot它会返回完整元素树每个标题、按钮、链接的位置和层级。改完代码说一句「检查首页的标题和链接结构」它就能告诉你元素是否按预期渲染、有没有遗漏。场景 3页面加载慢让 AI 跑性能分析# 对当前页面说分析这个页面的性能# AI 会自动录制 performance trace → 输出性能洞察# 或者说跑一次 Lighthouse 审计# AI 会输出各项得分与失败项清单Lighthouse 审计输出示例对 example.com 的一次审计Accessibility 96 分、Best Practices 96 分、SEO 80 分33 项通过、4 项需处理每一项都能继续追问原因和改法。场景 4排查接口问题让 AI 读网络请求和控制台页面数据不对、接口报错时直接问「列出这个页面最近发出的网络请求」或「控制台有什么报错」。AI 返回请求列表URL、方法、状态码和控制台消息含 source map 还原后的堆栈。场景 5不开 AI 客户端终端里直接玩CLI 模式全局安装后附带命令行工具chrome-devtools后台自动拉起服务chrome-devtools status# 查看后台服务状态chrome-devtools new_page https://example.com# 打开页面自动启动浏览器默认无头chrome-devtools take_screenshot2--filePathshot.png# 给第 2 个页面截图chrome-devtools stop# 用完停止后台服务六、踩坑记录与解决方案坑 1npm 全局安装后命令找不到Windows 高发现象npm install -g显示成功但chrome-devtools-mcp --version提示「不是内部或外部命令」。原因npm 全局命令装在C:\Users\你的用户名\AppData\Roaming\npm该目录不在 PATH 环境变量里。解决把C:\Users\你的用户名\AppData\Roaming\npm加进用户环境变量 PathWin 键搜「环境变量」→ 编辑用户变量 Path → 新建 → 粘贴路径重开终端验证或者干脆用 npx 方式不依赖全局 PATH。坑 2Git Bash 里运行全局命令报 MODULE_NOT_FOUND现象在 Git Bash 中运行chrome-devtools-mcp报错错误路径被拼上C:\Program Files\Git\前缀找不到模块文件。原因Git Bash 的 MSYS 路径转换机制把 Windows 路径解析错了.cmd 启动脚本定位不到实际文件。解决改用 PowerShell 或 cmd 运行全局命令或继续用 npx。此问题只出现在 Git Bash。坑 3VS Code / Codex 里连接报 MCP error -32000Windows现象Windows 上某些客户端直接以command: npx启动时报MCP error -32000: Connection closed服务起不来。原因客户端进程调用 npx 时缺少正确的 shell 环境。解决官方排错文档任选其一方案一用 cmd 包装Windows 推荐{mcpServers:{chrome-devtools:{command:cmd,args:[/c,npx,-y,chrome-devtools-mcplatest]}}}方案二command 直接写 npx 的绝对路径按本机实际调整JSON 用双反斜杠{mcpServers:{chrome-devtools:{command:C:\\nvm4w\\nodejs\\npx.ps1,args:[-y,chrome-devtools-mcplatest]}}}坑 4导航超时访问境外站点现象打开或跳转 GitHub、developers.chrome.com 等站点时报Navigation timeout of 10000 ms exceeded。原因默认导航等待 10 秒网络受限时境外站点首屏资源加载慢就超时。解决先拿国内可达站点如 https://cn.bing.com、https://example.com验证工具链本身正常调试境外站点时让 AI 重试或给服务加代理参数--proxy-server...。坑 5API 直连时提示缺少 pageId现象直接调用 take_screenshot、navigate_page 等接口时返回Input validation error: Required at pageId。原因1.9.0 版本默认开启 pageId 路由所有页面级工具要求传 pageId从 list_pages / new_page 返回的列表里取页码。解决先 list_pages 拿页码再带 pageId 调用。普通用户在 AI 客户端里用不会遇到客户端自动处理参数只有脚本/API 直连时才需要留意。坑 6Target closed浏览器起不来现象调用需要浏览器的工具时直接报Target closed。原因Chrome 启动失败——版本过旧、系统不支持、或已有 Chrome 实例占用。解决升级到最新稳定版 Chrome关闭已打开的 Chrome 实例后重试。坑 7Node 版本过低启动即退出现象一启动就报ERROR: chrome-devtools-mcp does not support Node x.x.x并退出。原因项目内置版本门槛——20.19 以下、22.12 以下、20 以下均不支持。解决到 Node 官网升级到最新 LTS见 3.1。七、部署验证部署完成后下面这些能力开箱即用Windows 11 Node 24 Chrome 153 环境下的运行结果能力运行结果工具枚举tools/list 返回 29 个工具click/fill/navigate_page/take_screenshot/take_snapshot/list_network_requests/evaluate_script/lighthouse_audit/performance_start_trace 等浏览器自动启动new_page 打开 example.comheadless Chrome 自动拉起并返回页面列表页面结构读取take_snapshot 返回完整元素树标题、链接、层级与页面实际内容一致截图take_screenshot 保存 PNG 成功见上文两张演示图网络检查list_network_requests 返回请求列表如 GET https://example.com/ [200]页面导航navigate_page 跳转到 cn.bing.com 成功页面标题「搜索 - Microsoft 必应」执行 JSevaluate_script 执行 document.title 返回「搜索 - Microsoft 必应」性能分析performance_start_trace 录制成功并输出摘要与洞察列表Lighthouse对 example.com 审计Accessibility 96 / Best Practices 96 / SEO 8033 项通过两种运行模式无头模式–headless不弹窗与有窗口模式均可正常启动浏览器轻量模式–slim 模式仅暴露 3 个基础工具evaluate/navigate/screenshot八、常见问题Q1需要 Docker 或者 GPU 吗都不需要。只依赖 Node.js 和 Chrome普通笔记本就能跑。Q2它会接管我日常用的 Chrome 吗不会。默认启动的是独立的浏览器实例独立用户数据目录与你的日常浏览器互不影响加--isolated参数还会在关闭后自动清理临时数据。Q3安全吗浏览器里的内容会不会泄露工具会把浏览器内容暴露给你接入的 AI 客户端所以不要在 AI 控制的浏览器里登录敏感账号或打开私密页面。另外默认会匿名收集使用统计介意的话启动时加--no-usage-statistics关闭。Q4能用 Edge 或国产浏览器吗官方只支持 Google Chrome 和 Chrome for Testing其他 Chromium 内核浏览器不保证兼容建议就用 Chrome。Q5工具太多用不上能只开基础功能吗能。启动加--slim参数就只剩导航、截图、执行脚本三个工具轻量稳定。九、总结chrome-devtools-mcp 是 AI 编程时代「让 AI 看得见网页」的关键拼图52k Star、Chrome 官方维护、Apache-2.0 协议部署只要 Node Chrome 两条前置。npx 一行命令就能装好接进 VS Code / Cursor / Claude Code 后调试、截图、抓包、性能分析都可以交给 AI 一句话完成。部署路径建议普通用户用 npx 客户端配置VS Code 直接装插件最省心喜欢终端用 npm 全局 CLI二次开发走源码构建。Windows 上重点留意坑 1PATH和坑 3-32000其余坑都附了排查方向。如果你也在用 AI 写前端建议现在就接上——「改完代码 → AI 自己打开浏览器验证」的闭环会让返工率明显下降。遇到问题欢迎评论区交流。完整命令速查# 环境检查node-v# 要求 20.19 / 22.12 / 23npm-v(Get-ItemC:\Program Files\Google\Chrome\Application\chrome.exe).VersionInfo.ProductVersion# 路径一npx 直跑官方推荐npx-ychrome-devtools-mcplatest--helpnpx-ychrome-devtools-mcplatest--version# 路径二npm 全局安装npminstall-gchrome-devtools-mcp chrome-devtools-mcp--version# 命令找不到时把 C:\Users\你的用户名\AppData\Roaming\npm 加入 PATH# 路径三源码构建gitclone https://github.com/ChromeDevTools/chrome-devtools-mcp.gitcdchrome-devtools-mcpnpmci# 国内慢加 --registryhttps://registry.npmmirror.comnpmrun buildnodebuild/src/bin/chrome-devtools-mcp.js--version# 接入客户端通用 JSON# {mcpServers:{chrome-devtools:{command:npx,args:[-y,chrome-devtools-mcplatest]}}}# VS Code命令面板 → Chat: Install Plugin From Source → ChromeDevTools/chrome-devtools-mcp# Claude Codeclaude mcp add chrome-devtools --scope user npx chrome-devtools-mcplatest# Codexcodex mcp add chrome-devtools -- npx chrome-devtools-mcplatest# CLI 模式chrome-devtools status chrome-devtools new_page https://example.com chrome-devtools take_screenshot2--filePathshot.png chrome-devtools stop# 常用启动参数# --headless 不弹浏览器窗口# --isolated 临时用户目录关闭后自动清理# --slim 仅基础三工具导航/截图/脚本# --no-usage-statistics 关闭使用统计项目地址[chrome-devtools-mcp] (https://github.com/ChromeDevTools/chrome-devtools-mcp)标签MCP | Chrome DevTools | AI 编程 | 前端调试 | 浏览器自动化 | Claude Code | Cursor | 性能优化