Matthias Rohmer
José Luis Zapata
您可以为智能体配置 Chrome 开发者工具，以自定义其与浏览器的互动方式、启用的工具以及处理数据的方式。
如需配置服务器，请在 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 实例。
- 在运行的 Chrome 浏览器中，前往
chrome://inspect/#remote-debugging并启用远程调试 。 - 将
--autoConnect添加到 MCP 配置：json "args": ["chrome-devtools-mcp@latest", "--autoConnect"] - 当智能体尝试连接时，Chrome 会显示一个对话框，询问是否授予权限。点击允许 。
手动连接
如果您无法使用 --autoConnect（例如，在沙盒环境中），您可以手动启动 Chrome 并使用调试端口，然后使用 --browser-url 进行连接。
- 从终端启动 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
- macOS：
- 将智能体配置为连接到此端口：
json "args": ["chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]
允许在临时目录之外访问文件
读取或写入文件的工具（例如，保存屏幕截图、跟踪记录或加载扩展程序）只能访问配置的工作区根目录中的路径。服务器使用 MCP 客户端通过 MCP 根目录功能提供的根目录，以及您使用 --filesystemRoot（别名 --workspace）传递的任何目录。如果您的客户端未提供根目录，并且您未设置 --filesystemRoot，则文件访问权限仅限于操作系统临时目录。
对其他路径的请求会失败，并显示 Access denied: ... is not within any of
the configured workspace roots 错误。
如需允许访问项目目录，请将 --filesystemRoot 添加到服务器实参。您可以重复使用该标志以允许访问多个目录：
"args": ["chrome-devtools-mcp@latest", "--filesystemRoot=/path/to/project"]
配置选项参考文档
以下部分列出了可用的配置标志。如需了解最新 选项和更新，请参阅 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 |
WebSocket 连接的自定义标头，采用 JSON 格式（例如，'{"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，以提取真实用户体验数据。 |
--javascriptEvaluation 或 --javascript-evaluation |
布尔值 | true |
设置为 false 可停用 JavaScript 执行。停用后，脚本评估工具将被停用，navigate_page 的 initScript 参数将被关闭，并且不允许导航到 javascript:、data: 或 vbscript: 网址。 |
--filesystemRoot 或 --filesystem-root--workspace |
数组 | 操作系统临时目录 | 除了 MCP 客户端提供的根目录之外，允许文件访问工具使用的目录。可以指定多次。请参阅允许在临时目录之外访问文件。 |
--allowUnrestrictedPaths 或 --allow-unrestricted-paths |
布尔值 | false |
已废弃：请改用 --workspace=/。停用在 MCP 客户端未提供根目录时适用的路径限制。 |
功能类别
您可以使用这些标志启用或停用工具组。
| 标志 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--categoryInput 或 --category-input |
布尔值 | true |
启用与输入相关的工具。 |
--categoryNavigation 或 --category-navigation |
布尔值 | true |
启用与导航相关的工具。 |
--categoryEmulation 或 --category-emulation |
布尔值 | true |
启用与模拟相关的工具。 |
--categoryNetwork 或 --category-network |
布尔值 | true |
启用与网络相关的工具。 |
--categoryPerformance 或 --category-performance |
布尔值 | true |
启用与性能相关的工具。 |
--categoryDebugging 或 --category-debugging |
布尔值 | true |
启用与调试相关的工具。 |
--categoryMemory 或 --category-memory |
布尔值 | true |
启用与内存相关的工具。 |
--categoryExtensions 或 --category-extensions |
布尔值 | false |
启用与扩展程序相关的工具。仅支持管道连接。 |
--categoryPwa 或 --category-pwa |
布尔值 | false |
启用用于自动执行渐进式 Web 应用（安装、启动、卸载和操作系统状态）的工具。仅支持管道连接。 |
--categoryExperimentalThirdParty 或 --category-experimental-third-party |
布尔值 | false |
启用被检查网页公开的第三方开发者工具。 |
--categoryExperimentalWebmcp 或 --category-experimental-webmcp |
布尔值 | false |
启用调试 WebMCP 工具。需要启用 WebMCP 功能的 Chrome 149+。 |
--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 |
最大高度（以像素为单位）。较大的屏幕截图会缩小。 |
实验性选项
使用这些选项启用正在开发的实验性功能。
| 标志 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--experimentalDevtools 或 --experimental-devtools |
布尔值 | false |
启用对开发者工具目标的自动化。 |
--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 可执行文件的路径。 |
--experimentalScreencastFps 或 --experimental-screencast-fps |
数值 | false |
屏幕录制记录的每秒帧数。较低的值可以减少在生成帧的速度快于 ffmpeg 对其进行编码的速度的网页上的内存压力。 |
其他选项
使用这些选项配置日志记录、网页路由和源映射，或启用一组简化的工具。
| 标志 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--slim |
布尔值 | false |
公开一组精简的三个工具（导航、脚本执行和屏幕截图）。适用于基本的浏览器任务。 |
--pageIdRouting 或 --page-id-routing |
布尔值 | true |
需要在网页范围的工具上使用 pageId，并按网页 ID 路由请求，这对于并发智能体会话非常有用。使用 --no-page-id-routing 可停用此功能。 |
--sourceMaps 或 --source-maps |
布尔值 | true |
在开发者工具中启用源映射。使用 --no-source-maps 可停用此功能。 |
--logFile 或 --log-file |
字符串 | false |
用于写入调试日志的文件的路径。将 NODE_DEBUG 环境变量设置为 * 可启用详细日志。 |
--config |
字符串 | false |
JSON 配置文件的路径。 |
环境变量
您还可以使用以下环境变量来配置服务器：
CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS：如果设置，则停用使用情况统计信息收集功能（等同于--no-usage-statistics）。CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS：如果设置，则停用定期检查更新。CI：如果设置，则停用使用情况统计信息收集功能。NODE_DEBUG：设置为*可启用详细调试日志记录（与--logFile结合使用）。