适用于代理的 Chrome 开发者工具

Chrome DevTools for Agents (chrome-devtools-mcp) 让您的编码代理（例如 Gemini、Claude、Cursor 或 Copilot） 控制和检查实时 Chrome 浏览器。 它充当模型-上下文-协议 (MCP) 服务器，让您的 AI 编码助手能够充分利用 Chrome DevTools 可实现可靠的自动化、深入调试和性能分析。 还提供 CLI 以便在没有 MCP 的情况下使用。

Tool reference | Changelog | Contributing | Troubleshooting | Design Principles

主要特点

• 获取性能洞察：使用 Chrome DevTools 进行记录 跟踪并提取可操作的性能见解。
• 高级浏览器调试：分析网络请求、截屏和 检查浏览器控制台消息（带有源映射的堆栈跟踪）。
• 可靠的自动化。 用途 puppeteer 自动执行以下操作 Chrome 并自动等待操作结果。

免责声明

chrome-devtools-mcp 将浏览器实例的内容公开给 MCP 客户端 允许他们检查、调试和修改浏览器或开发工具中的任何数据。 避免分享您不想分享的敏感或个人信息 MCP 客户。

chrome-devtools-mcp 仅正式支持 Google Chrome 和 Chrome for Testing。 其他基于 Chromium 的浏览器可能会工作，但这不能保证，并且您可能会遇到意外的行为。 请自行决定使用。 我们致力于为最新版本的 Extended Stable Chrome 提供修复和支持。

性能工具可能会将跟踪 URL 发送到 Google CrUX API 以获取真实用户 经验数据。 这有助于提供整体性能图 与实验室数据一起呈现现场数据。 该数据由 Chrome User Experience Report (CrUX) 收集。 禁用 这个，使用 --no-performance-crux 标志运行。

使用统计

Google 收集使用情况统计信息（例如工具调用成功率、延迟和环境信息）以提高 Chrome DevTools MCP 的可靠性和性能。

数据收集默认启用。 您可以在启动服务器时通过传递 --no-usage-statistics 标志来选择退出：

"args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"]

Google 根据 Google Privacy Policy 处理这些数据。

Google 收集的 Chrome DevTools MCP 使用情况统计信息独立于 Chrome 浏览器的使用情况统计信息。 选择退出 Chrome 指标并不会自动选择您退出此工具，反之亦然。

如果设置了 CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS 或 CI env 变量，则会禁用收集。

更新检查

默认情况下，服务器会定期检查 npm 注册表是否有更新，并在有新版本可用时记录通知。 您可以通过设置 CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS 环境变量来禁用这些更新检查。

要求

• Node.js v20.19 或更新的 latest maintenance LTS 版本。
• Chrome 当前稳定版本或更高版本。
• npm

开始使用

将以下配置添加到您的 MCP 客户端：

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

[!注意] 使用 chrome-devtools-mcp@latest 可确保您的 MCP 客户端始终使用最新版本的 Chrome DevTools MCP 服务器。

如果您只想执行基本的浏览器任务，请使用 --slim 模式：

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

请参阅Slim tool reference。

MCP 客户端配置

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--browser-url=http://127.0.0.1:9222",
        "-y"
      ]
    }
  }
}

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

/plugin marketplace add ChromeDevTools/chrome-devtools-mcp

/plugin install chrome-devtools-mcp

[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

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

copilot

/mcp add

code --add-mcp '{"name":"io.github.ChromeDevTools/chrome-devtools-mcp","command":"npx","args":["-y","chrome-devtools-mcp"],"env":{}}'

code --add-mcp '{"""name""":"""io.github.ChromeDevTools/chrome-devtools-mcp""","""command""":"""npx""","""args""":["""-y""","""chrome-devtools-mcp"""]}'

# Either MCP only:
gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest
# Or as a Gemini extension (MCP+Skills):
gemini extensions install --auto-update https://github.com/ChromeDevTools/chrome-devtools-mcp

gemini mcp add -s user chrome-devtools npx chrome-devtools-mcp@latest

mcp-proxy --transport streamablehttp --port 8080 -- npx -y chrome-devtools-mcp@latest

[[mcp_servers]]
name = "chrome-devtools"
transport = "stdio"
command = "npx"
args = ["chrome-devtools-mcp@latest"]

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

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

qodercli mcp add -s user chrome-devtools -- npx chrome-devtools-mcp@latest

你的第一个提示

在 MCP 客户端中输入以下提示以检查一切是否正常：

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

您的 MCP 客户端应打开浏览器并记录性能跟踪。

[!注意] 一旦 MCP 客户端使用需要运行浏览器实例的工具，MCP 服务器将自动启动浏览器。 单独连接到 Chrome DevTools MCP 服务器不会自动启动浏览器。

工具

如果您遇到任何问题，请查看我们的 troubleshooting guide。

• 输入自动化（9 种工具）
• click
• drag
• fill
• fill_form
• handle_dialog
• hover
• press_key
• type_text
• upload_file
• 导航自动化（6 个工具）
• close_page
• list_pages
• navigate_page
• new_page
• select_page
• wait_for
• 仿真（2 个工具）
• emulate
• resize_page
• 性能（4 个工具）
• performance_analyze_insight
• performance_start_trace
• performance_stop_trace
• take_memory_snapshot
• 网络（2 个工具）
• get_network_request
• list_network_requests
• 调试（6 个工具）
• evaluate_script
• get_console_message
• lighthouse_audit
• list_console_messages
• take_screenshot
• take_snapshot

配置

Chrome DevTools MCP 服务器支持以下配置选项：

• --autoConnect/ --auto-connect 如果指定，则自动连接到从通道参数标识的用户数据目录本地运行的浏览器（Chrome 144+）（默认通道是稳定的）。 需要通过 chrome://inspect/#remote-debugging 在 Chrome 实例中启动远程调试服务器。

• **类型：**布尔值

• 默认： false

• --browserUrl/--browser-url，-u 连接到正在运行的、可调试的 Chrome 实例（例如 http://127.0.0.1:9222）。 有关更多详细信息，请参阅：https://github.com/ChromeDevTools/chrome-devtools-mcp#connecting-to-a-running-chrome-instance.

• 类型： 字符串

• --wsEndpoint/ --ws-endpoint, -w 用于连接到正在运行的 Chrome 实例的 WebSocket 端点（例如 ws://127.0.0.1:9222/devtools/browser/）。 --browserUrl 的替代方案。

• 类型： 字符串

• --wsHeaders/ --ws-headers JSON 格式的 WebSocket 连接的自定义标头（例如“{"Authorization":"Bearer token"}'）。 仅适用于 --wsEndpoint。

• 类型： 字符串

• --headless 是否以无头（无 UI）模式运行。

• **类型：**布尔值

• 默认： false

• --executablePath/ --executable-path, -e 自定义 Chrome 可执行文件的路径。

• 类型： 字符串

• --isolated 如果指定，将创建一个临时用户数据目录，该目录会在浏览器关闭后自动清除。 默认为 false。

• **类型：**布尔值

• --userDataDir/ --user-data-dir Chrome 用户数据目录的路径。 默认为 $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE

• 类型： 字符串

• --channel 指定应使用的不同 Chrome 通道。 默认为稳定通道版本。

• 类型： 字符串

• 选项： canary、dev、beta、stable

• --logFile/ --log-file 用于写入调试日志的文件的路径。 将环境变量 DEBUG 设置为 * 以启用详细日志。 对于提交错误报告很有用。

• 类型： 字符串

• --viewport 服务器启动的 Chrome 实例的初始视口大小。 例如，1280x720。 在无头模式下，最大尺寸为 3840x2160px。

• 类型： 字符串

• --proxyServer/ --proxy-server Chrome 的代理服务器配置在启动浏览器时作为 --proxy-server 传递。 有关详细信息，请参阅 https://www.chromium.org/developers/design-documents/network-settings/。

• 类型： 字符串- --acceptInsecureCerts/ --accept-insecure-certs 如果启用，则忽略与自签名和过期证书相关的错误。 谨慎使用。

• **类型：**布尔值

• --experimentalVision/ --experimental-vision 是否启用基于坐标的工具，例如 click_at(x,y)。 通常需要一个能够通过查看屏幕截图来生成准确坐标的计算机使用模型。

• **类型：**布尔值

• --experimentalScreencast/ --experimental-screencast 公开实验性截屏工具（需要 ffmpeg）。 安装 ffmpeg https://www.ffmpeg.org/download.html 并确保它在 MCP 服务器路径中可用。

• **类型：**布尔值

• --experimentalWebmcp/ --experimental-webmcp 设置为 true 以启用调试 WebMCP 工具。 需要 Chrome 149+ 并具有以下标志：--enable-features=WebMCPTesting,DevToolsWebMCPSupport

• **类型：**布尔值

• --chromeArg/ --chrome-arg Chrome 的其他参数。 仅当 Chrome 由 chrome-devtools-mcp 启动时适用。

• **类型：**数组

• --ignoreDefaultChromeArg/ --ignore-default-chrome-arg 显式禁用 Chrome 的默认参数。 仅当 Chrome 由 chrome-devtools-mcp 启动时适用。

• **类型：**数组

• --categoryEmulation/ --category-emulation 设置为 false 以排除与仿真相关的工具。

• **类型：**布尔值

• 默认： true

• --categoryPerformance/ --category-performance 设置为 false 以排除与性能相关的工具。

• **类型：**布尔值

• 默认： true

• --categoryNetwork/ --category-network 设置为 false 以排除与网络相关的工具。

• **类型：**布尔值

• 默认： true

• --performanceCrux/ --performance-crux 设置为 false 可禁用从性能跟踪向 CrUX API 发送 URL 以获取现场性能数据。

• **类型：**布尔值

• 默认： true

• --usageStatistics/ --usage-statistics 设置为 false 以选择退出使用情况统计信息收集。 Google 收集使用数据以改进该工具，并根据 Google 隐私政策 (https://policies.google.com/privacy) 处理。 这与 Chrome 浏览器指标无关。 如果设置了 CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS 或 CI env 变量，则禁用。

• **类型：**布尔值

• 默认： true

• --slim 公开了一组“精简”的 3 个工具，仅涵盖导航、脚本执行和屏幕截图。 对于基本的浏览器任务很有用。

• **类型：**布尔值

• --redactNetworkHeaders/ --redact-network-headers 如果为 true，则在返回客户端之前编辑一些被视为敏感的网络标头。

• **类型：**布尔值

• 默认： false

通过 JSON 配置中的 args 属性传递它们。 例如：

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

通过带有自定义标头的 WebSocket 连接

您可以直接连接到 Chrome WebSocket 端点并包含自定义标头（例如，用于身份验证）：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/<id>",
        "--wsHeaders={\"Authorization\":\"Bearer YOUR_TOKEN\"}"
      ]
    }
  }
}

要从正在运行的 Chrome 实例获取 WebSocket 端点，请访问 http://127.0.0.1:9222/json/version 并查找 webSocketDebuggerUrl 字段。

您还可以运行 npx chrome-devtools-mcp@latest --help 查看所有可用的配置选项。

概念

用户数据目录

chrome-devtools-mcp 使用以下用户启动 Chrome 的稳定通道实例 数据目录：

• Linux / macOS：$HOME/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL
• Windows：%HOMEPATH%/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL

用户数据目录在运行之间不会被清除，并且会被共享 chrome-devtools-mcp 的所有实例。 将 isolated 选项设置为 true 使用临时用户数据目录，该目录将在之后自动清除 浏览器已关闭。

连接到正在运行的 Chrome 实例

默认情况下，Chrome DevTools MCP 服务器将启动一个具有专用配置文件的新 Chrome 实例。 这可能并不适合所有情况：

• 如果您希望在手动站点测试和代理驱动测试之间交替时保持相同的应用程序状态。
• 当 MCP 需要登录网站时。 当通过 WebDriver（Chrome DevTools MCP 服务器的默认启动机制）控制浏览器时，某些帐户可能会阻止登录。
• 如果您在沙盒环境中运行 LLM，但您希望连接到在沙盒外部运行的 Chrome 实例。

在这些情况下，请先启动 Chrome 并让 Chrome DevTools MCP 服务器连接到它。 有两种方法可以做到这一点：

• 自动连接（在 Chrome 144 中提供）：最适合在手动和代理驱动测试之间共享状态。
• 通过远程调试端口手动连接：在沙盒环境中运行时效果最佳。

自动连接到正在运行的 Chrome 实例

第 1 步： 在 Chrome 中设置远程调试

在 Chrome (>= M144) 中，执行以下操作来设置远程调试：

1. 导航至 chrome://inspect/#remote-debugging 以启用远程调试。
2. 按照对话框 UI 允许或禁止传入的调试连接。

步骤 2： 配置 Chrome DevTools MCP 服务器以自动连接到正在运行的 Chrome 实例

要将 chrome-devtools-mcp 服务器连接到正在运行的 Chrome 实例，请使用 MCP 服务器的 --autoConnect 命令行参数。

以下代码片段是 gemini-cli 的示例配置：

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

第 3 步： 测试您的设置

确保您的浏览器正在运行。 打开 gemini-cli 并运行以下提示：

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

[!注意] autoConnect 选项要求用户启动 Chrome。 如果用户有多个活动配置文件，MCP 服务器将连接到默认配置文件（由 Chrome 确定）。 MCP 服务器可以访问所选配置文件的所有打开的窗口。

Chrome DevTools MCP 服务器将尝试连接到您正在运行的 Chrome 实例。 它显示一个请求用户许可的对话框。

单击 允许 会导致 Chrome DevTools MCP 服务器打开 developers.chrome.com 并进行表演 踪迹。

使用端口转发手动连接

您可以使用 --browser-url 选项连接到正在运行的 Chrome 实例。 如果您在不允许启动新 Chrome 实例的沙盒环境中运行 MCP 服务器，这非常有用。

以下是有关如何连接到正在运行的 Chrome 实例的分步指南：

步骤 1：配置 MCP 客户端

将 --browser-url 选项添加到您的 MCP 客户端配置中。 此选项的值应该是正在运行的 Chrome 实例的 URL。 http://127.0.0.1:9222 是常见的默认值。

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--browser-url=http://127.0.0.1:9222"
      ]
    }
  }
}

步骤 2：启动 Chrome 浏览器

[!警告] 启用远程调试端口会在正在运行的浏览器实例上打开调试端口。 您计算机上的任何应用程序都可以连接到此端口并控制浏览器。 确保调试端口打开时您没有浏览任何敏感网站。

启动Chrome浏览器并启用远程调试端口。 确保在启用调试端口的情况下启动新的 Chrome 实例之前关闭所有正在运行的 Chrome 实例。 您选择的端口号必须与您在 MCP 客户端配置的 --browser-url 选项中指定的端口号相同。

出于安全原因，启用远程调试端口时，Chrome requires you to use a non-default user data directory。 您可以使用 --user-data-dir 标志指定自定义目录。 这可确保您的常规浏览配置文件和数据不会暴露给调试会话。

macOS

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable

Linux

/usr/bin/google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable

视窗

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%TEMP%\chrome-profile-stable"

第 3 步：测试您的设置

配置 MCP 客户端并启动 Chrome 浏览器后，您可以通过在 MCP 客户端中运行简单的提示来测试您的设置：

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

您的 MCP 客户端应连接到正在运行的 Chrome 实例并接收性能报告。

如果遇到虚拟机到主机的端口转发问题，请参阅 docs/troubleshooting.md 中的“虚拟机 (VM) 和主机之间的远程调试失败”部分。

有关远程调试的更多详细信息，请参阅 Chrome DevTools documentation。

在 Android 上调试 Chrome

请咨询these instructions。

已知限制

请参阅Troubleshooting。