配置

Matthias Rohmer
José Luis Zapata

您可以为代理配置 Chrome DevTools，以自定义其与浏览器的互动方式、启用的工具以及处理数据的方式。

通过在 Model Context Protocol (MCP) 客户端配置文件的 args 数组中传递命令行标志来配置服务器。这通常是 config.json 文件。

例如，如需在无头模式下运行 Chrome 并使用 Canary 渠道，请使用以下配置：

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

常见配置场景

以下场景介绍了为代理配置 Chrome 开发者工具的常见方式。

在无头模式下运行

如需在没有可见浏览器窗口的情况下执行后台任务，请在无头（无界面）模式下运行 Chrome。将 --headless 标志添加到服务器实参中。

连接到现有浏览器会话

默认情况下，面向智能体的开发者工具会启动新的 Chrome 实例。不过，您可以将智能体连接到现有的浏览器会话。如果您已开始会话，但客服人员需要调查其中的问题（例如，您已登录），此功能会非常有用。

您可以通过以下两种方式连接到现有会话：

自动连接（Chrome 144 及更高版本）

如果您使用 --autoConnect 标志，MCP 服务器会自动连接到活跃的 Chrome 实例。

  1. 在正在运行的 Chrome 浏览器中，前往 chrome://inspect/#remote-debugging 并启用远程调试。
  2. 将 --autoConnect 添加到您的 MCP 配置中： json "args": ["chrome-devtools-mcp@latest", "--autoConnect"]
  3. 当代理尝试连接时，Chrome 会显示一个对话框，询问是否授予权限。点击允许。

手动连接

如果您无法使用 --autoConnect（例如，在沙盒环境中），可以手动启动带有调试端口的 Chrome，并使用 --browser-url 进行连接。

  1. 从终端启动 Chrome，并启用远程调试和自定义用户数据目录。
    • macOS： shell /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
    • Windows： shell start chrome --remote-debugging-port=9222 --user-data-dir=%TEMP%\chrome-profile-stable
    • Linux： shell google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
  2. 配置代理以连接到此端口： json "args": ["chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]

配置选项参考

以下各部分列出了可用的配置标志。如需了解最新的选项和更新，请参阅 Chrome 开发者工具 MCP GitHub 代码库。

连接选项

使用这些选项可配置服务器与 Chrome 的连接方式。

标志 类型 默认值 说明
--autoConnect 或 --auto-connect 布尔值 false 自动连接到本地运行的 Chrome（144 及更高版本）实例。需要使用 chrome://inspect/#remote-debugging 启用远程调试。
--browserUrl 或 --browser-url
-u		 字符串 false 连接到正在运行的可调试 Chrome 实例（例如 http://127.0.0.1:9222）。
--wsEndpoint 或 --ws-endpoint
-w		 字符串 false 用于连接到正在运行的 Chrome 实例的 WebSocket 端点（例如 ws://127.0.0.1:9222/devtools/browser/<id>）。--browserUrl 的替代方案。
--wsHeaders 或 --ws-headers 字符串 false JSON 格式的 WebSocket 连接自定义标头（例如 '{"Authorization":"Bearer token"}'）。仅适用于 --wsEndpoint。

浏览器启动选项

这些选项适用于 MCP 服务器启动 Chrome 的情况。

标志 类型 默认值 说明
--headless 布尔值 false 以无头（无界面）模式运行 Chrome。
--channel 字符串 stable 指定要使用的 Chrome 渠道。选项：canary、dev、beta 和 stable。
--executablePath 或 --executable-path
-e		 字符串 false 自定义 Chrome 可执行文件的路径。
--userDataDir 或 --user-data-dir 字符串 请参阅说明 用户数据目录的路径。默认值为 $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE。
--isolated 布尔值 false 创建在浏览器关闭时自动清理的临时用户数据目录。
--viewport 字符串 false 初始视口大小（例如 1280x720）。在无头模式下，最大尺寸为 3840x2160。
--proxyServer 或 --proxy-server 字符串 false 传递给 Chrome 的代理服务器配置。
--chromeArg 或 --chrome-arg 数组 false 要传递给 Chrome 的其他实参。
--ignoreDefaultChromeArg 或 --ignore-default-chrome-arg 数组 false 明确停用 Chrome 的默认实参。

安全和隐私权选项

您可以使用这些选项来管理安全设置和数据隐私权。

标志 类型 默认值 说明
--acceptInsecureCerts 或 --accept-insecure-certs 布尔值 false 忽略与自签名证书和过期证书相关的错误。请小心使用。
--blockedUrlPattern 或 --blocked-url-pattern 数组 false 通过屏蔽指定的网址格式（使用 URLPattern）来限制网络访问权限。屏蔽导航和子资源。
--allowedUrlPattern 或 --allowed-url-pattern 数组 false 仅允许指定的网址格式，以限制网络访问权限。需要 Chrome 149 或更高版本。
--redactNetworkHeaders 或 --redact-network-headers 布尔值 false 在将敏感的网络标头返回给客户端之前对其进行密文处理。
--usageStatistics 或 --usage-statistics 布尔值 true 启用使用情况统计信息收集功能，以改进该工具。也可以使用 CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS 或 CI 环境变量停用。
--performanceCrux 或 --performance-crux 布尔值 true 将性能跟踪记录中的网址发送到 Google CrUX API，以提取真实用户体验数据。

功能类别

您可以使用这些标志启用或停用工具组。

标志 类型 默认值 说明
--categoryEmulation 或 --category-emulation 布尔值 true 启用与模拟相关的工具。
--categoryNetwork 或 --category-network 布尔值 true 启用与网络相关的工具。
--categoryPerformance 或 --category-performance 布尔值 true 启用与性能相关的工具。
--categoryExtensions 或 --category-extensions 布尔值 false 启用与扩展程序相关的工具。仅支持管道连接。
--categoryExperimentalThirdParty 或 --category-experimental-third-party 布尔值 false 启用被检查网页公开的第三方开发者工具。
--categoryExperimentalWebmcp 或 --category-experimental-webmcp 布尔值 false 启用 WebMCP 工具调试。需要 Chrome 149 及更高版本，并启用 WebMCP 功能。
--memoryDebugging 或 --memory-debugging 布尔值 false 启用内存调试工具。

屏幕截图选项

使用这些选项可自定义代理截取屏幕截图的方式。

标志 类型 默认值 说明
--screenshotFormat 或 --screenshot-format 字符串 false 替换默认输出格式 (png)。选项：jpeg、png 和 webp。jpeg 和 webp 格式更小，有助于减小 AI 对话中的上下文大小。
--screenshotQuality 或 --screenshot-quality 数值 false 替换 jpeg 和 webp 的压缩质量 (0-100)。
--screenshotMaxWidth 或 --screenshot-max-width 数值 false 最大宽度（以像素为单位）。较大的屏幕截图会被缩小。
--screenshotMaxHeight 或 --screenshot-max-height 数值 false 最大高度（以像素为单位）。较大的屏幕截图会被缩小。

实验性选项

使用这些选项可启用正在开发的实验性功能。

标志 类型 默认值 说明
--experimentalPageIdRouting 或 --experimental-page-id-routing 布尔值 false 在页面级工具上公开 pageId，以在并发代理会话中路由请求。
--experimentalDevtools 或 --experimental-devtools 布尔值 false 实现对 DevTools 目标的自动化操作。
--experimentalVision 或 --experimental-vision 布尔值 false 启用基于坐标的工具（例如 click_at）。通常需要一种计算机使用模型，该模型可以通过查看屏幕截图生成准确的坐标。
--experimentalStructuredContent 或 --experimental-structured-content 布尔值 false 输出结构化格式的内容。
--experimentalIncludeAllPages 或 --experimental-include-all-pages 布尔值 false 包括所有类型的网页（例如 WebView 和后台网页）。
--experimentalScreencast 或 --experimental-screencast 布尔值 false 公开屏幕录制工具（需要 PATH 中的 ffmpeg）。
--experimentalFfmpegPath 或 --experimental-ffmpeg-path 字符串 false ffmpeg 可执行文件的路径。

其他选项

您可以使用这些选项来配置日志记录或启用一组简化的工具。

标志 类型 默认值 说明
--slim 布尔值 false 公开了一组精简的三个工具（导航、脚本执行和屏幕截图）。适用于基本的浏览器任务。
--logFile 或 --log-file 字符串 false 用于写入调试日志的文件的路径。

环境变量

您还可以使用以下环境变量来配置服务器：

  • CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS：如果设置，则停用使用情况统计信息收集功能（相当于 --no-usage-statistics）。
  • CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS：如果设置，则会停用定期检查更新。
  • CI：如果设置，则停用使用情况统计信息收集。
  • DEBUG：设置为 * 可启用详细调试日志记录（与 --logFile 结合使用）。