Chrome DevTools MCP

Chrome DevTools MCP

chrome-devtools-mcp 让你的编码 Agent（例如 Gemini、Claude、Cursor 或 Copilot） 能够控制和检查正在运行的 Chrome 浏览器。它作为 Model-Context-Protocol （MCP）服务，为你的 AI 编码助手提供 Chrome DevTools 的全部强大功能，用于可靠的自动化、深入调试和性能分析。

工具参考 | 更新日志 | 贡献指南 | 故障排除

主要功能

• 获取性能洞察：使用 Chrome DevTools 记录 跟踪信息并提取可操作的性能洞察。
• 高级浏览器调试：分析网络请求、截取屏幕截图并 检查浏览器控制台。
• 可靠的自动化。使用 puppeteer 自动执行 Chrome 中的操作， 并自动等待操作结果。

免责声明

chrome-devtools-mcp 会向 MCP 客户端公开浏览器实例中的内容， 使其能够检查、调试和修改浏览器或 DevTools 中的任何数据。 请避免分享你不希望 MCP 客户端获知的敏感信息或个人信息。

要求

• Node.js v20.19 或更新的最新维护版 LTS。
• Chrome 当前稳定版或更新版本。
• npm。

开始使用

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

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

说明

使用 chrome-devtools-mcp@latest 可确保你的 MCP 客户端始终使用最新版本的 Chrome DevTools MCP 服务。

MCP 客户端配置

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

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

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

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

[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

copilot

/mcp add

code --add-mcp '{"name":"chrome-devtools","command":"npx","args":["chrome-devtools-mcp@latest"]}'

droid mcp add chrome-devtools "npx -y chrome-devtools-mcp@latest"

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

gemini 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 服务不会自动启动浏览器。

工具

如果遇到问题，请查看我们的故障排除指南。

• 输入自动化（8 个工具）
  • click
  • drag
  • fill
  • fill_form
  • handle_dialog
  • hover
  • press_key
  • upload_file
• 导航自动化（6 个工具）
  • close_page
  • list_pages
  • navigate_page
  • new_page
  • select_page
  • wait_for
• 模拟（2 个工具）
  • emulate
  • resize_page
• 性能（3 个工具）
  • performance_analyze_insight
  • performance_start_trace
  • performance_stop_trace
• 网络（2 个工具）
  • get_network_request
  • list_network_requests
• 调试（5 个工具）
  • evaluate_script
  • get_console_message
  • list_console_messages
  • take_screenshot
  • take_snapshot

配置

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

• --browserUrl, -u 使用端口转发连接到正在运行的 Chrome 实例。详情请参阅：https://developer.chrome.com/docs/devtools/remote-debugging/local-server。

  • 类型： string

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

  • 类型： string

• --wsHeaders WebSocket 连接的自定义标头，采用 JSON 格式（例如，'{"Authorization":"Bearer token"}'）。仅在使用 --wsEndpoint 时有效。

  • 类型： string

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

  • 类型： boolean
  • 默认值： false

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

  • 类型： string

• --isolated 如果指定此选项，则会创建一个临时 user-data-dir，并在浏览器关闭后自动清理。

  • 类型： boolean
  • 默认值： false

• --channel 指定要使用的其他 Chrome 通道。默认使用 stable 通道版本。

  • 类型： string
  • 可选值： stable, canary, beta, dev

• --logFile 用于写入调试日志的文件路径。将环境变量 DEBUG 设为 * 可启用详细日志。适用于提交错误报告。

  • 类型： string

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

  • 类型： string

• --proxyServer Chrome 的代理服务配置，启动浏览器时会将其作为 --proxy-server 传入。详情请参阅 https://www.chromium.org/developers/design-documents/network-settings/。

  • 类型： string

• --acceptInsecureCerts 如果启用，则忽略与自签名和过期证书相关的错误。请谨慎使用。

  • 类型： boolean

• --chromeArg Chrome 的其他参数。仅当 chrome-devtools-mcp 启动 Chrome 时有效。

  • 类型： array

• --categoryEmulation 设为 false 可排除与模拟相关的工具。

  • 类型： boolean
  • 默认值： true

• --categoryPerformance 设为 false 可排除与性能相关的工具。

  • 类型： boolean
  • 默认值： true

• --categoryNetwork 设为 false 可排除与网络相关的工具。

  • 类型： boolean
  • 默认值： true

通过 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 stable 通道实例：

• 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 实例

你可以使用 --browser-url 选项连接到正在运行的 Chrome 实例。如果你想使用现有的 Chrome 配置文件，或者在不允许启动新 Chrome 实例的沙盒环境中运行 MCP 服务，这会很有用。

以下是连接到正在运行的 Chrome Stable 实例的分步指南：

步骤 1：配置 MCP 客户端

在 MCP 客户端配置中添加 --browser-url 选项。该选项的值应为正在运行的 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 要求启用远程调试端口时使用非默认的用户数据目录。你可以使用 --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

Windows

"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 实例并接收性能报告。

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

有关远程调试的更多详情，请参阅 Chrome DevTools 文档。

已知限制

操作系统沙盒

某些 MCP 客户端允许使用 macOS Seatbelt 或 Linux 容器对 MCP 服务进行沙盒隔离。启用沙盒后，chrome-devtools-mcp 无法启动需要权限来创建自身沙盒的 Chrome。解决方法是：在 MCP 客户端中为 chrome-devtools-mcp 禁用沙盒隔离，或者使用 --browser-url 连接到你在 MCP 客户端沙盒之外手动启动的 Chrome 实例。