用 Chrome DevTools MCP 给你的 AI 编程智能体一个真正的浏览器

让 AI 编程智能体打开 Chrome、读取控制台错误并录制性能跟踪。Chrome DevTools MCP 的安装步骤、配置和常见问题解决方法。

Graphic of a browser window connected to a terminal prompt reading mcp, for a guide to Chrome DevTools MCP

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 或更高版本。

  1. 在 Chrome 中打开 chrome://inspect/#remote-debugging,按照对话框提示允许传入的调试连接。
  2. 在配置中添加 --autoConnect:
代码
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--autoConnect"]
    }
  }
}
  1. 保持 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 日。

作者:Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

关于 Mindloop Experience

评论

写评论

更多来自 Mindloop Experience

查看 Mindloop Experience 的全部文章

最多可以鼓掌 50 次。