chrome-devtools-mcp
命令行工具ChromeDevTools/chrome-devtools-mcp
让 AI 编码代理控制 Chrome DevTools 的 MCP 服务器。
项目简介
Chrome DevTools MCP 服务器，让 AI 代理调试、自动化并分析 Chrome 浏览器性能。与 Puppeteer 和 DevTools 前端集成，实现可靠自动化和性能洞察。
README 预览
# Chrome DevTools for Agents\n\n[](https://npmjs.org/package/chrome-devtools-mcp)\n\nChrome DevTools for Agents (`chrome-devtools-mcp`) lets your coding agent (such as Gemini, Claude, Cursor or Copilot)\ncontrol and inspect a live Chrome browser. It acts as a Model-Context-Protocol\n(MCP) server, giving your AI coding assistant access to the full power of\nChrome DevTools for reliable automation, in-depth debugging, and performance analysis.\nA [CLI](docs/cli.md) is also provided for use without MCP.\n\n## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)\n\n## Key features\n\n- **Get performance insights**: Uses [Chrome\n DevTools](https://github.com/ChromeDevTools/devtools-frontend) to record\n traces and extract actionable performance insights.\n- **Advanced browser debugging**: Analyze network requests, take screenshots and\n check browser console messages (with source-mapped stack traces).\n- **Reliable automation**. Uses\n [puppeteer](https://github.com/puppeteer/puppeteer) to automate actions in\n Chrome and automatically wait for action results.\n\n## Disclaimers\n\n`chrome-devtools-mcp` exposes content of the browser instance to the MCP clients\nallowing them to inspect, debug, and modify any data in the browser or DevTools.\nAvoid sharing sensitive or personal information that you don't want to share with\nMCP clients.\n\n`chrome-devtools-mcp` officially supports Google Chrome and [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing/) only.\nOther Chromium-based browsers may work, but this is not guaranteed, and you may encounter unexpected behavior. Use at your own discretion.\nWe are committed to providing fixes and support for the latest version of [Extended Stable Chrome](https://chromiumdash.appspot.com/schedule).\n\nPerformance tools may send trace URLs to the Google CrU
常见问题 (5)
故障排除如何解决在 chrome-devtools-mcp 中同时使用 emulate() 设置移动视口和网络节流时出现的“Navigation timeout”错误？
在 chrome-devtools-mcp v1.0.1 中，这是一个已知问题。网络节流会在导航超时乘数更新之前应用，导致在慢速网络条件（如 Slow 3G）下，视口更改触发页面重新加载时采用默认的 10 秒超时。解决方法：将 emulate 调用拆分为两次独立调用。例如，先使用仅包含 networkConditions 参数的 emulate 调用，然后使用仅包含 viewport 参数的第二次调用（或顺序相反）。这样可避免在未延长超时的情况下发生重新加载。PR #2134 中已提出永久性修复方案。
故障排除如何修复 chrome-devtools-mcp Claude Code 插件因 npm EOVERRIDE 错误（CONNECTION_CLOSED）而无法启动的问题？
该插件通过 npx chrome-devtools-mcp@<version> 启动服务器，npx 会根据你当前工作目录中的 package.json 进行解析。如果你的项目中存在与直接依赖冲突的 overrides 条目（常见于 Dependabot/Renovate 升级了依赖却未更新固定的安全 override 之后，例如 "dependencies": {"dompurify": "^3.4.16"} 与 "overrides": {"dompurify": "^3.4.14"} 不一致），npx 会在服务器启动前以 npm error code EOVERRIDE 退出，而 Claude Code 只会显示 Connection failed (CONNECTION_CLOSED)。
解决方法：
1. 修复项目的 package.json：使 overrides 的版本与直接依赖保持一致（将 override 更新为与依赖相同的版本范围），然后运行 npm install。
2. 从 package.json 中不存在冲突 overrides 的目录启动 Claude Code。
3. 通过绕过当前工作目录（cwd）的 package.json，验证服务器本身能否正常工作：
npx -y --prefix "$HOME" chrome-devtools-mcp@1.11.0 --version
或 sh -c 'cd ~ && npx -y chrome-devtools-mcp@1.11.0 --version'
插件级修复：在 .claude-plugin/plugin.json 中，为内联的 mcpServers args 添加 prefix，使 npx 忽略项目的 package.json："args": ["--prefix", "${CLAUDE_PLUGIN_DATA}", "chrome-devtools-mcp@<version>"]。请注意，Claude Code 会展开 ${CLAUDE_PLUGIN_DATA} 和 ${HOME}，但不会展开 ${PLUGIN_DATA}（后者出现在随附的 mcp.json 中，而 Claude Code 会忽略该文件）。
故障排除为什么在 take_heapsnapshot 覆盖同一个 .heapsnapshot 文件之后,堆快照工具仍显示旧数据?
堆快照在首次加载后会按文件路径进行缓存。使用 take_heapsnapshot 覆盖同一路径并不会使缓存中的快照失效，因此 get_heapsnapshot_details、query_heapsnapshot_objects 及类似工具会继续分析旧的捕获内容。要强制重新加载，请在再次分析之前对该路径调用 close_heapsnapshot：{"name":"close_heapsnapshot","arguments":{"filePath":"/path/to/same.heapsnapshot"}}，然后再调用 get_heapsnapshot_details 或 query_heapsnapshot_objects。或者，为每次捕获使用唯一的 filePath，例如 snapshot-<timestamp>.heapsnapshot，从而完全避开缓存。
故障排除当 --allowUnrestrictedPaths=false 不起作用时,如何将 Chrome DevTools MCP CLI 的文件访问限制在 temp 目录?
这是 chrome-devtools-mcp 1.10.1 以及 main 分支提交 b2f522c 中的一个 bug：在 CLI 模式下，显式指定的 --allowUnrestrictedPaths=false 会被忽略，并且在 1.10.1 中，该标志不会被转发给守护进程（daemon）。作为一种变通方案，可以使用 --workspace 将文件工具限制在操作系统的临时目录内：
chrome-devtools stop
chrome-devtools start --workspace="$(node -p "require('os').tmpdir()")" --no-usage-statistics --no-performance-crux重启之后，对该目录之外位置的写入操作应该会失败，并报出 Access denied: path ... is not within any of the configured workspace roots 错误。可以使用 chrome-devtools status 来验证正在运行的守护进程。或者，升级到包含该修复程序的版本，使显式指定的 --allowUnrestrictedPaths=false 得到正确生效；--workspace 仍然是替代该已弃用标志的推荐方案。
故障排除如何在使用 Chrome DevTools MCP 时绕过“允许远程调试”权限对话框？
使用启用了远程调试的专用Chrome配置文件。启动Chrome时添加：--remote-debugging-port=9222 --user-data-dir=/path/to/profile。然后将MCP服务器连接到http://127.0.0.1:9222。由于专用配置文件已预先授权调试，因此可以避免权限对话框。推荐用于开发和测试。由于安全考虑，未实现持久化权限批准功能。