chrome-devtools-mcp让您的编码代理（例如 Gemini、Claude、Cursor 或 Copilot） 控制和检查实时 Chrome 浏览器。它充当模型-上下文-协议 （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"]
    }
  }
}

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

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

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

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

• 输入自动化（7 个工具）
  • click
  • drag
  • fill
  • fill_form
  • handle_dialog
  • hover
  • upload_file
• 导航自动化（7 个工具）
  • close_page
  • list_pages
  • navigate_page
  • navigate_page_history
  • new_page
  • select_page
  • wait_for
• 仿真（3 个工具）
  • emulate_cpu
  • emulate_network
  • 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 服务器支持以下配置选项：

• --浏览器网址， -u使用端口转发连接到正在运行的 Chrome 实例。有关更多详细信息，请参阅：https://developer.chrome.com/docs/devtools/remote-debugging/local-server。

  • 类型：字符串

• --ws端点， -wWebSocket 端点连接到正在运行的 Chrome 实例（例如 ws://127.0.0.1:9222/devtools/browser/）。–browserUrl 的替代方法。

  • 类型：字符串

• --ws标头JSON 格式的 WebSocket 连接的自定义标头（例如，'{“Authorization”：“Bearer token”}’）。仅适用于 –wsEndpoint。

  • 类型：字符串

• --无头的是否在无头（无 UI）模式下运行。

  • 类型：布尔值
  • 违约： false

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

  • 类型：字符串

• --孤立如果指定，则创建一个临时用户数据目录，该数据目录在浏览器关闭后自动清理。

  • 类型：布尔值
  • 违约： false

• --渠道指定应使用的其他 Chrome 频道。默认值为稳定通道版本。

  • 类型：字符串
  • 选项：、、、stablecanarybetadev

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

  • 类型：字符串

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

  • 类型：字符串

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

  • 类型：字符串

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

  • 类型：布尔值

• --chrome引数Chrome 的其他参数。仅当 chrome-devtools-mcp 启动 Chrome 时才适用。

  • 类型：数组

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

  • 类型：布尔值
  • 违约： true

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

  • 类型：布尔值
  • 违约： true

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

  • 类型：布尔值
  • 违约： true

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

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

您可以直接连接到 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/versionwebSocketDebuggerUrl

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

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

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

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

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

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

步骤 1：配置 MCP 客户端

将该选项添加到 MCP 客户端配置中。此选项的值应为正在运行的 Chrome 实例的 URL。 是常见的默认值。--browser-urlhttp://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 实例。您选择的端口号必须与您在 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

窗户

"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） 和主机之间的远程调试失败”部分。