AI 编程智能体能写网页,但大多数看不到这个页面在浏览器里运行后到底做了什么。Chrome DevTools MCP 解决了这个问题:这是 Chrome DevTools 团队推出的开源服务器,能让 Claude Code、Cursor、Copilot 或 Gemini CLI 这样的智能体打开 Chrome、读取控制台、检查网络请求、截图并录制性能跟踪。本指南会教你如何安装、完成第一次测试、连接到你已经打开的 Chrome 窗口,以及解决最常见的配置问题。
截至 2026 年 11 月 14 日,最新版本是 11 月 11 日发布的 1.13.0,本周该项目还登上了 GitHub 每日趋势榜。
Chrome DevTools MCP 能做什么
MCP(Model Context Protocol)是 AI 助手调用外部工具的一种标准方式。chrome-devtools-mcp 包就是一个 MCP 服务器:你的智能体向它发送“打开这个网址”或“列出控制台错误”之类的请求,它就借助 Chrome DevTools 和 Puppeteer 在真实的 Chrome 浏览器中执行。
这些工具按类别分组。输入自动化(点击、填写、输入、上传文件)、导航、模拟、性能跟踪、网络检查和调试(控制台消息、截图、页面快照、Lighthouse 审核)默认开启。网络模拟(mock)、扩展程序和渐进式 Web 应用等额外类别默认关闭,需要用参数开启。1.13.0 版本新增了日志点(logpoint)和限定在单个页面的网络模拟。
同一个包还附带一个命令行工具 chrome-devtools,你完全可以不用智能体,直接在终端里控制浏览器。
准备工作
- Node.js 的 LTS 版本。截至 2026 年 11 月 14 日,npm 包标注支持的 Node 版本为
^20.19.0 || ^22.12.0 || >=23。 - npm(随 Node 一起安装)。
- Google Chrome 当前稳定版或更新版本。该项目官方只支持 Google Chrome 和 Chrome for Testing;其他 Chromium 浏览器也许能用,但不保证。
- 一个支持 MCP 的智能体或编辑器,例如 Claude Code、Cursor、带 Copilot 的 VS Code、Gemini CLI 或 Codex。
先检查你的 Node 版本:
node --version
第 1 步:确认服务器能运行
在修改智能体设置之前,先确认这个包能在你的电脑上启动。官方故障排除指南推荐这个测试:
npx chrome-devtools-mcp@latest --help
你应该会看到一系列选项,例如 --headless、--isolated 和 --browser-url。如果这一步就报错,请先解决再继续(见下文的错误部分)。
第 2 步:添加到你的智能体
大多数 MCP 客户端都接受同样的 JSON 配置块。下面是项目 README 中的标准配置:
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp@latest"]
}
}
}
使用 @latest 意味着你的客户端会自动获取新版本。
有几款工具还支持一行命令安装,以下命令来自项目的客户端配置指南。
Claude Code:
claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
Gemini CLI:
gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest
OpenAI Codex:
codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
VS Code(macOS 和 Linux):
code --add-mcp '{"name":"io.github.ChromeDevTools/chrome-devtools-mcp","command":"npx","args":["-y","chrome-devtools-mcp"],"env":{}}'
在 Cursor 中,指南说要依次进入 Cursor Settings(Cursor 设置)、MCP、New MCP Server(新建 MCP 服务器),然后粘贴标准配置。菜单名称可能随版本变化,如果找不到这个路径,请查看 Cursor 自己的 MCP 文档。
可选:作为带技能的插件安装
该项目还提供“技能”(skills),也就是一些简短的说明文件,教你的智能体如何用好这些工具。在 Claude Code 中,你可以先运行 /plugin marketplace add ChromeDevTools/chrome-devtools-mcp,再运行 /plugin install chrome-devtools-mcp@chrome-devtools-plugins,然后重启 Claude Code,一次装好服务器和技能。如果你还不了解技能,可以看看我们的指南如何在 Claude Code 中安装和使用智能体技能,里面讲了它们的工作原理。
第 3 步:运行第一个提示词
重启智能体让它加载新服务器,然后输入项目建议的测试提示词:
Check the performance of https://developers.chrome.com
预期结果:一个 Chrome 窗口打开,页面加载完成,智能体向你汇报一份性能跟踪结果。只有当智能体第一次使用需要浏览器的工具时,浏览器才会启动,所以仅仅连接服务器并不会打开 Chrome。
成功之后,可以试试和你自己的工作相关的提示词:
Open http://localhost:3000, list any console errors, and tell me which network requests failed.
Take a screenshot of http://localhost:3000 at a mobile viewport and check the page for accessibility problems.
默认情况下,服务器会用它自己的配置文件启动 Chrome,在 macOS 和 Linux 上保存在 $HOME/.cache/chrome-devtools-mcp/chrome-profile。这个配置文件在多次运行之间会保留,所以你在里面的登录状态也会保留。
第 4 步:修改 Chrome 的启动方式(可选)
你可以在 args 数组中添加参数来控制行为。下面的示例让 Chrome 无窗口运行,使用一个用完即删的临时配置文件,并退出默认开启的 Google 使用情况统计:
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": [
"-y",
"chrome-devtools-mcp@latest",
"--headless=true",
"--isolated=true",
"--no-usage-statistics"
]
}
}
}
还有两个隐私设置值得了解。性能工具可能会把跟踪的网址发送到 Google 的 Chrome UX Report(CrUX)API,以获取真实用户数据;添加 --no-performance-crux 即可阻止。如果你只需要基本浏览功能,--slim 只提供精简的三个工具。
第 5 步:连接到你正在使用的 Chrome 窗口(可选)
有时你希望智能体在你自己的浏览器里工作,比如在一个你已经登录的网站上。截至 2026 年 11 月 14 日,这种“自动连接”模式需要 Chrome 144 或更高版本。
- 在 Chrome 中打开
chrome://inspect/#remote-debugging,按照对话框提示允许传入的调试连接。 - 在配置中添加
--autoConnect:
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["chrome-devtools-mcp@latest", "--autoConnect"]
}
}
}
- 保持 Chrome 运行并发送一个提示词。Chrome 会请求权限,点击 Allow(允许)。
服务器会连接到你默认的 Chrome 配置文件,并能看到其中打开的每个窗口。请先关闭网银、邮箱或其他含敏感数据的标签页。项目自己的免责声明也警告说,智能体可以查看和修改浏览器中的任何数据。
如果你的智能体在沙盒中运行,另一种方法是你自己用一个调试端口和单独的配置文件启动 Chrome(下面以 macOS 为例;文档中也列出了 Linux 和 Windows 的路径):
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
然后在 args 中使用 "--browser-url=http://127.0.0.1:9222"。只要这个端口开着,你电脑上的任何应用都能控制这个浏览器,所以不要在这个窗口里访问敏感网站。
常见错误及解决方法
Error [ERR_MODULE_NOT_FOUND]: Cannot find module ...:通常是 Node 版本不受支持或 npx 缓存损坏。先升级 Node,再用npm cache clean --force清理缓存并重新安装。文档还建议运行rm -rf ~/.npm/_npx,但它也会删除其他已缓存的 npx 工具。Target closed:Chrome 无法启动。请确认没有其他 Chrome 实例在运行(如果有就关掉),并且安装了最新的 Chrome 稳定版。- 智能体找不到服务器,但终端测试正常:确认你的编辑器使用的 Node 和 npm 与终端相同。
- Windows:
MCP error -32000: Connection closed:设置"command": "cmd",并在args中填入"/c", "npx", "-y", "chrome-devtools-mcp@latest"。 - macOS:
--autoConnect失败并提示EPERM: operation not permitted:在 System Settings > Privacy & Security > Files & Folders(系统设置 > 隐私与安全性 > 文件与文件夹)中,允许你的终端或编辑器访问 Google Chrome。 --autoConnect超时:检查 Chrome 144 或更高版本是否已在运行、是否已在chrome://inspect/#remote-debugging开启远程调试、你是否接受了提示,以及是否有其他程序占用了同一个调试端口。- Chrome 在容器或 CI 中无法启动:Chrome 不能以 root 身份运行。请用非 root 用户运行服务器。
- 在虚拟机中使用:Chrome 可能会拒绝来自虚拟机的连接。文档建议从虚拟机建立 SSH 隧道,例如
ssh -N -L 127.0.0.1:9222:127.0.0.1:9222 user@server。如果你从没用过 SSH,可以参考我们的 SSH 密钥指南完成设置。
遇到其他问题时,用日志文件运行服务器并查看报错:
NODE_DEBUG=* npx chrome-devtools-mcp@latest --log-file=/tmp/chrome-devtools-mcp.log
总结
有了 Chrome DevTools MCP,你的智能体可以自己检查前端成果,而不是靠猜:加载页面、读取错误、查看网络面板、测量性能。先从标准配置和测试提示词开始;想要一个干净、用完即弃的浏览器,就加上 --isolated 或 --headless;只在你不介意 AI 看到一切的配置文件里使用自动连接。也要记得让 Chrome 本身保持更新,我们的 Chrome 零日漏洞解读讲了为什么这很重要。
资料来源
链接最后检查于 2026 年 11 月 15 日。





写评论