chrome-devtools-mcp 是一个 Model-Context-Protocol 服务器，让 Gemini、Claude、Cursor 等 AI 编码助手能控制 Chrome 浏览器进行自动化操作、性能分析和网络调试。本文详解项目定位、安装步骤、MCP 配置、工具集使用及设计原则。
chrome-devtools-mcp 是一个 Model-Context-Protocol 服务器，将 Chrome DevTools 和 Puppeteer 能力封装为标准化工具，使 AI 编码助手能够自动化控制浏览器、调试网页、分析性能指标。
chrome-devtools-mcp 是一个 Model-Context-Protocol (MCP) 服务器实现，其核心定位是作为 AI 编码助手与 Chrome 浏览器之间的标准化接口。它允许 Gemini、Claude、Cursor 等编码代理通过 MCP 协议调用工具，直接控制、检查和调试一个实时的 Chrome 浏览器实例。项目将 Chrome DevTools 的丰富能力（如性能分析、网络监控）与 Puppeteer 的浏览器自动化能力封装为 MCP 工具，使 AI 能够执行网页交互、问题诊断和性能优化等任务，从而扩展 AI 在 Web 开发领域的能力边界。
该项目主要解决 AI 编码助手缺乏对实时浏览器环境直接访问和控制能力的问题。传统 AI 助手只能基于静态代码或有限上下文提供建议，而无法观察实际运行时的网页行为。chrome-devtools-mcp 通过 MCP 协议提供了一套标准化的浏览器交互工具，使 AI 能够：自动化执行浏览器操作并可靠等待结果；深入调试网络请求、控制台日志（支持源码映射）；记录和分析性能 trace 获取可操作的洞察。这解决了 AI 在 Web 开发中‘看得见但摸不着’的困境，使其能基于真实浏览器行为给出更准确、可执行的建议。
基于提供的工具集，主要适用场景包括： 1. 性能分析：AI 使用 performance_start_trace 记录 trace，结合 performance_get_insights 提取性能洞察，并可关联 CrUX 真实用户数据。 2. 网络调试：AI 调用 list_network_requests、get_network_request_details 等工具分析请求/响应头、体和时间线，用于排查加载问题或 API 错误。 3. 浏览器自动化：通过 click、type、scroll 等输入工具，以及 navigate、reload 等导航工具，让 AI 执行端到端测试或演示操作。 4. 页面检查与调试：使用 screenshot 截图、console_get_messages 查看控制台、dom_snapshot 获取 DOM 结构，辅助 AI 诊断渲染或脚本问题。 5. 设备模拟：通过 emulate_viewport、emulate_user_agent 等工具，让 AI 测试不同设备或网络条件下的网页表现。 6. 辅助功能检查：通过 a11y-debugging 技能包，AI 可分析页面的可访问性问题。
根据 README 和 package.json，安装前置条件为：Node.js v20.19 或更高 LTS 版本、Chrome 浏览器（当前稳定版或 newer）、npm。 推荐通过 npx 直接运行（无需全局安装）：在 MCP 客户端配置中指定命令为 `npx -y chrome-devtools-mcp@latest`。若需全局安装，可使用 `npm install -g chrome-devtools-mcp`，随后通过 `chrome-devtools` 命令使用 CLI。 注意：项目官方仅支持 Google Chrome 和 Chrome for Testing，其他 Chromium 系浏览器可能工作但不保证。 安装后，必须在 MCP 客户端（如 Claude Desktop、Cursor）的配置文件中添加 mcpServers 条目，指向上述命令，才能被 AI 助手发现和调用。
使用分为 MCP 集成和 CLI 直接操作两种方式： MCP 集成：在客户端配置文件中添加服务器配置，例如： { "mcpServers": { "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] } } } 启动时可附加参数：`--slim` 启用精简工具集（仅 navigate、evaluate、screenshot），`--headless` 无头运行，`--no-usage-statistics` 禁用遥测。 CLI 直接操作：通过 `chrome-devtools` 命令与浏览器交互，如 `chrome-devtools list_pages` 列出可操控页面，`chrome-devtools navigate_page <url>` 导航。详见 docs/cli.md。 AI 助手通过 MCP 协议调用具体工具，如 `screenshot`、`performance_start_trace`、`list_network_requests` 等，完整工具列表及参数见 docs/tool-reference.md 和 docs/slim-tool-reference.md。
项目包含多项补充特性： 1. Slim 模式：为 token 敏感场景设计，仅暴露 3 个核心工具，大型资产（截图、trace）返回文件路径而非原始数据。 2. 遥测与更新：默认收集使用统计（可 `--no-usage-statistics` 或设置环境变量禁用），并定期检查 npm 更新（可通过 `CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS` 禁用）。 3. 设计原则：遵循 Agent-Agnostic API、Token-Optimized、Small Deterministic Blocks、Self-Healing Errors、Human-Agent Collaboration、Progressive Complexity 六条原则，确保工具对各类 AI 友好、高效且可靠。 4. 技能包：skills/ 目录包含 a11y-debugging、debug-optimize-lcp、memory-leak-debugging 等预定义技能，提供领域特定的工具组合和参考文档。 5. 安全免责：工具会暴露浏览器内容给 MCP 客户端，建议避免在敏感页面使用；性能工具可能向 CrUX API 发送 trace URL（可 `--no-performance-crux` 禁用）。
需先安装 Node.js v20.19+、Chrome 浏览器和 npm。推荐在 MCP 客户端配置中添加：{"mcpServers":{"chrome-devtools":{"command":"npx","args":["-y","chrome-devtools-mcp@latest"]}}}。也可全局安装：npm install -g chrome-devtools-mcp，然后使用 chrome-devtools 命令。详见 README Getting started 部分。
官方仅支持 Google Chrome 和 Chrome for Testing。其他基于 Chromium 的浏览器可能工作，但不保证，使用需自担风险。项目承诺为最新 Extended Stable Chrome 版本提供修复和支持。
slim 模式通过 --slim 参数启用，仅暴露 navigate、evaluate、screenshot 三个核心工具，大幅降低 token 消耗。适用于只需基础浏览器操作的场景，或上下文窗口受限的 AI 助手。完整工具集见 docs/tool-reference.md，slim 工具见 docs/slim-tool-reference.md。
禁用使用统计：启动时添加 --no-usage-statistics 参数，或设置环境变量 CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1（CI 环境自动禁用）。禁用更新检查：设置环境变量 CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS=1。详见 README 中 Usage statistics 和 Update checks 部分。
有。项目提供实验性 CLI：通过 chrome-devtools 命令直接与浏览器交互，例如 chrome-devtools list_pages 列出页面，chrome-devtools navigate_page <url> 导航。CLI 会自动启动后台 MCP 服务器并保持状态。详见 docs/cli.md。