chrome-devtools-mcp 接入指南：实测安装 + 接入 Claude Code/Codex/Cursor/OpenCode（2026）

chrome-devtools-mcp 是 Google Chrome DevTools 团队官方出品的 MCP 服务器，能让 Claude Code、Codex、Cursor、OpenCode 等 AI 编码助手直接操控和检查一个真实的 Chrome 浏览器——截图、看网络请求、读控制台报错、分析性能，全程一条命令即可接入。它是 Apache-2.0 开源协议，完全免费，目前在 GitHub 已收获 50.7k star，npm 周下载量约 329 万（2026 年 8 月数据）。

本文基于 2026 年 9 月的 v1.8.0 版本实测整理：覆盖安装前置条件、四大客户端（Claude Code、Codex、Cursor、OpenCode）的完整配置步骤、常用参数速查，以及两个我自己踩过的坑（国内镜像报 notarget 错误、pageId 校验报错）。

本文目录

1. chrome-devtools-mcp 是什么？
2. 安装前的环境准备
3. chrome-devtools-mcp 安装教程
4. 接入 Claude Code
5. 接入 Codex
6. 接入 Cursor
7. 接入 OpenCode
8. 验证接入是否成功
9. 常用启动参数速查
10. chrome-devtools-mcp vs Playwright MCP 怎么选
11. 常见报错与踩坑
12. 常见问题 FAQ

---

chrome-devtools-mcp 是什么？

chrome-devtools-mcp 是 Google ChromeDevTools 团队在 2025 年 9 月发布的开源项目（GitHub 仓库），定位是 Chrome DevTools for coding agents——把 Chrome DevTools 的调试能力通过 MCP（Model Context Protocol）协议暴露给 AI 编码助手。

简单说：装上它之后，AI 不再是"凭空猜页面长什么样"，而是能真的打开一个 Chrome 窗口，自己看页面、点按钮、查报错、跑性能分析。

截至 2026 年 9 月 3 日的项目数据（均为实测时查询）：

它的能力集中在三块：

• 性能分析：录制 Chrome 性能轨迹（trace），提取可操作的优化建议，还能结合 CrUX 真实用户体验数据；
• 浏览器调试：分析网络请求、页面截图、读取控制台消息（带 source map 还原的报错堆栈）；
• 可靠自动化：基于 Puppeteer 驱动浏览器，自动等待操作结果，减少"点了没反应"的假动作。

默认模式下它提供 29 个工具（这是我在本机实测连接后统计的数字；官方完整文档列了 50+ 个，内存调试、扩展管理等工具需要额外开启参数才会加载，下文详述）。

安装前的环境准备

只需要两样东西，都是现成软件，无任何付费项：

• Node.js LTS 版本（官方要求 LTS；我实测环境是 v22.22.3）
• Google Chrome 稳定版（官方明确只支持 Chrome 和 Chrome for Testing，Edge 等 Chromium 系浏览器不保证可用）

先在终端确认 Node 环境：

node -v
npm -v

能看到版本号（如 v22.x.x 和 10.x.x）就可以继续。没有装 Node.js 的话，去 nodejs.org 下载 LTS 版本安装即可。

说明：chrome-devtools-mcp 不需要单独"安装"成全局包，它是通过 npx 按需拉起运行的，版本号用 @latest 锁定，每次启动都会用最新版。

chrome-devtools-mcp 安装教程

标准 MCP 配置（所有客户端通用）

绝大多数 MCP 客户端都能用下面这份通用配置接入：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

配置好之后，第一次调用工具时它会自动下载依赖并拉起一个 Chrome 实例。首次下载需要一些时间——我实测在官方 npm 源下首次运行花了 35.6 秒（含下载安装），之后命中缓存，二次启动只要 4.2 秒。

国内镜像用户必看：notarget 报错的解法

这是我实测踩的第一个坑。如果你的 npm 配置了公司内网源或国内镜像（我用 npm config get registry 查到本机是 npm.sankuai.com），镜像还没同步这个包时，npx chrome-devtools-mcp@latest 会直接报错：

npm error notarget No matching version found for undefined@latest.

解法是临时指定官方源运行：

npx -y --registry=https://registry.npmjs.org/ chrome-devtools-mcp@latest --help

用淘宝镜像的用户如果遇到同步延迟，同样可以用这个方式绕过，或在客户端配置的 args 里带上 --registry 参数。

下面这张图是我实测时通过 MCP 让 AI 助手控制 Chrome 打开 Chrome 开发者官网的截图——页面、标签页都由 chrome-devtools-mcp 驱动，截图即工具返回结果：

接入 Claude Code

Claude Code 有两种接入方式，按需选一种即可。

方式一：CLI 一条命令接入（只装 MCP）

claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest

--scope user 表示对当前用户的所有项目生效；去掉这个参数则只对当前项目生效。

方式二：以插件方式接入（MCP + 官方 Skills，推荐）

插件方式除了 MCP 服务器，还会带上官方配套的技能（Skills），让 Claude 更懂怎么用这套工具：

# 1. 添加插件市场
/plugin marketplace add ChromeDevTools/chrome-devtools-mcp

# 2. 安装插件
/plugin install chrome-devtools-mcp@chrome-devtools-plugins

装完重启 Claude Code，用 /skills 命令确认技能已加载。

注意：如果你之前用方式一装过，官方建议先移除旧配置再装插件，避免两份配置打架。另外在公司防火墙内插件安装可能报 Failed to clone repository，此时退回方式一即可。

接入 Codex

macOS / Linux

一条命令接入：

codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

执行后用 codex mcp list 确认列表里出现 chrome-devtools 即接入成功。

Windows 11 专属配置（官方要求）

Windows 用户注意：直接套用上面的命令经常启动超时，官方文档给出的做法是在 .codex/config.toml 里手动加配置，指定 Chrome 安装路径环境变量并把启动超时放宽到 20 秒：

[mcp_servers.chrome-devtools]
command = "cmd"
args = [
  "/c",
  "npx",
  "-y",
  "chrome-devtools-mcp@latest",
]
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 20_000

如果执行 codex 时报"无法将 codex 项识别为 cmdlet"，说明 Codex CLI 本身没装好或 PATH 缺失，先 npm install -g @openai/codex 并把 npm 全局目录（C:\Users\你的用户名\AppData\Roaming pm）加进 PATH。

接入 Cursor

Cursor 走图形界面配置，两步完成：

1. 打开 Cursor Settings → MCP → New MCP Server；
2. 粘贴下面的标准配置：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

保存后回到 MCP 列表，看到 chrome-devtools 显示绿色可用状态即可。官方还提供了一键安装链接（见客户端配置文档），点一下自动填好配置。

接入 OpenCode

OpenCode 通过 opencode.json 配置文件接入。没有这个文件的话，在 ~/.config/opencode/opencode.json 新建一个：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "chrome-devtools": {
      "type": "local",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest"]
    }
  }
}

注意 OpenCode 的配置结构和其他客户端不同：外层是 "mcp"，type 固定填 "local"，命令是数组形式。保存后重启 OpenCode 生效。

验证接入是否成功

官方推荐的验证方式是在接入的 AI 客户端里直接发这句提示词：

Check the performance of https://developers.chrome.com

如果 AI 开始打开浏览器、录制性能轨迹并输出分析结果，说明整条链路通了。下面是我验证时用 take_screenshot 工具实拍的返回图（AI 通过 chrome-devtools-mcp 打开 example.com 后的页面状态）：

我自己则用 MCP SDK 写了个最小脚本验证（等同 AI 客户端内部的调用流程），全流程 2.9 秒完成连接 + 导航 + 截图 + 控制台读取。验证时有个细节值得知道：chrome-devtools-mcp 默认开启 pageId 路由，take_screenshot 这类页面级工具需要传一个数字类型的 pageId（编号来自 list_pages 返回的页面列表，如 2: Example Domain）。成熟的 MCP 客户端（Claude Code、Cursor 等）会自动处理这个编号，自己写脚本调用时才需要手动传。

启动的浏览器实例由 MCP 服务器按需拉起：只有当客户端调用需要浏览器的工具时 Chrome 才会启动，仅连接服务器不会弹窗。

常用启动参数速查

以下参数都可以加在 args 数组末尾（如 ["-y", "chrome-devtools-mcp@latest", "--headless"]）：

两种模式加载的工具数量对比如下（默认模式 29 个为实测统计，slim 模式 3 个来自官方帮助文本，完整清单 50+ 来自官方工具文档）：

chrome-devtools-mcp vs Playwright MCP 怎么选

两者是当前最常用的浏览器类 MCP，但定位不同：

一句话结论：调网页用 chrome-devtools-mcp，跑跨浏览器自动化测试用 Playwright MCP，两者也可以同时接入互补。

npm 下载量是观察它热度的一个直观窗口。下面是 chrome-devtools-mcp 最近 15 天的 npm 日下载量趋势（官方 npm registry 数据，2026-08-15 至 08-29，选取统计完整的连续区间）：

常见报错与踩坑

结合我的实测和 GitHub Issues 区的高频反馈，这几个问题最常见：

1. notarget No matching version found for undefined@latest npm 镜像源没同步包导致（详见上文安装一节），指定官方源运行即可。这是国内用户最常见的接入失败原因。

2. Invalid arguments for tool take_screenshot: Required at pageId 默认 pageId 路由开启，页面级工具必须带数字 pageId。AI 客户端会自动处理；自己写脚本时先调 list_pages，从输出里取页面编号，以数字类型传入。

3. Windows 下 codex/npx 命令找不到 PATH 没配好。把 npm 全局目录加入用户 PATH，重启终端再试。

4. 接了已运行的 Chrome（--browserUrl）但连不上 Chrome 需要先开启远程调试端口。auto-connect 相关问题也是 Issues 区的高频反馈（19 条讨论），如果自动连接失败，改用手动指定 --browserUrl 更稳。

5. 多标签页时浏览器卡死 连接到打开了几十个标签的 Chrome 时可能出现（Issues 区 16 条讨论的已知问题），建议配合 --isolated 让它拉起干净的独立实例。

另外要提醒：它不支持反爬绕过（Stealth 模式），官方 Issues 明确拒绝了这个请求；也不要把敏感账号的浏览器会话随便交给 AI 操控——MCP 客户端能读到浏览器里的内容，隐私边界自己把好关。

总结

chrome-devtools-mcp 是目前 AI 编码助手接入 Chrome 调试能力的第一选择：Google 官方出品、迭代活跃（最近提交就在昨天）、生态验证充分（周下载 329 万）。接入成本极低——装好 Node.js 和 Chrome 后，一条 claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest 就能让 Claude Code 用上全套 DevTools 能力，Codex、Cursor、OpenCode 也都只需要改一段配置。

对前端开发者，它把"复制报错贴给 AI"的循环变成 AI 自己看页面、自己定位问题；对非专业用户，它让 AI 能替你完成网页上的实际操作——这类"AI 替你动手"的场景，OpenClaw 实战教程里有更系统的玩法。想进一步了解 AI 工具的日常用法，可以看看如何将 Claude 整合到日常工作流中，或者了解让 AI 一起干活有哪几种玩法。

最后更新于 2026 年 9 月 3 日，基于 chrome-devtools-mcp v1.8.0 实测。官方迭代很快，接入配置如有变化，以官方客户端配置文档为准。

作者：AI345 编辑部。我们长期实测 AI 工具并产出中文教程，本文所有安装步骤、报错和截图均来自 2026 年 9 月在 macOS（Node v22.22.3）环境下的实际测试。