Chrome DevTools MCP

官方

用于从Gemini、Claude、Cursor和Copilot等编码代理控制和检查实时Chrome浏览器的官方Chrome DevTools MCP服务器。

你可以用 Chrome Dev Tools MCP 做什么?

  • 记录并分析性能追踪 — 使用 performance_start_trace 启动追踪,用 performance_stop_trace 停止,然后通过 performance_analyze_insight 获取可操作的洞察。
  • 检查网络活动 — 使用 list_network_requests 列出所有请求,并通过 get_network_request 获取单个请求的详细信息。
  • 调试控制台错误和运行时状态 — 通过 list_console_messagesget_console_message 检索控制台消息,或使用 evaluate_script 执行任意 JavaScript。
  • 自动化浏览器交互 — 使用 navigate_pageclickfillpress_key 等工具进行导航、点击、填写表单和模拟输入。
  • 捕获视觉状态 — 使用 take_screenshot 截取页面截图,或使用 take_snapshot 获取无障碍快照。
  • 诊断内存问题 — 使用 take_heapsnapshot 捕获堆快照,并检查对象保留器、支配者或比较快照。

文档

面向智能体的 Chrome DevTools

npm chrome-devtools-mcp package

面向智能体的 Chrome DevTools (chrome-devtools-mcp) 可让您的编码智能体(例如 Antigravity、Claude、Cursor 或 Copilot)控制和检查实时 Chrome 浏览器。它充当模型上下文协议 (MCP) 服务器,让您的 AI 编码助手能够使用 Chrome DevTools 的全部功能,进行可靠的自动化、深入调试和性能分析。还提供了一个 CLI,供在没有 MCP 的情况下使用。

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

主要功能

  • 获取性能洞察:使用 https://github.com/ChromeDevTools/devtools-frontend 记录跟踪并提取可操作的性能洞察。
  • 高级浏览器调试:分析网络请求、截取屏幕截图并检查浏览器控制台消息(包含源码映射的堆栈跟踪)。
  • 可靠的自动化。使用 puppeteer 自动化 Chrome 中的操作,并自动等待操作结果。

免责声明

chrome-devtools-mcp 会将浏览器实例的内容暴露给 MCP 客户端,允许它们检查、调试和修改浏览器或 DevTools 中的任何数据。避免共享您不希望与 MCP 客户端共享的敏感或个人信息。

chrome-devtools-mcp 官方仅支持 Google Chrome 和 Chrome for Testing。其他基于 Chromium 的浏览器可能也能工作,但这不作保证,您可能会遇到意外行为。请自行决定是否使用。我们致力于为最新版本的 扩展稳定版 Chrome 提供修复和支持。

性能工具可能会将跟踪 URL 发送到 Google CrUX API,以获取真实用户体验数据。这有助于通过将现场数据与实验室数据一起呈现,提供全面的性能图景。此数据由 https://developer.chrome.com/docs/crux 收集。要禁用此功能,请使用 --no-performance-crux 标志运行。

使用情况统计

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

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

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

Google 根据 Google 隐私权政策 处理这些数据。

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

如果设置了 CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICSCI 环境变量,则收集将被禁用。

更新检查

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

要求

入门指南

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

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

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

如果您只对执行基本的浏览器任务感兴趣,请使用 --slim 模式:

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

请参阅 Slim 工具参考

MCP 客户端配置

Amp 遵循 https://ampcode.com/manual#mcp 并使用上面提供的配置。您也可以使用 CLI 安装 Chrome DevTools MCP 服务器:
amp mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
Antigravity

要使用 Chrome DevTools MCP 服务器,请按照 Antigravity 的文档 中的说明安装自定义 MCP 服务器。将以下配置添加到 MCP 服务器配置中:

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

这将使 Chrome DevTools MCP 服务器自动连接到 Antigravity 正在使用的浏览器。如果您未使用端口 9222,请确保进行相应调整。

使用此方法时,Chrome DevTools MCP 不会自动启动浏览器实例,因为 Chrome DevTools MCP 服务器会连接到 Antigravity 的内置浏览器。如果浏览器尚未运行,您必须首先通过单击右上角的 Chrome 图标来启动它。

Claude Code

通过 CLI 安装(仅 MCP)

使用 Claude Code CLI 添加 Chrome DevTools MCP 服务器(指南):

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

作为插件安装(MCP + 技能)

[!NOTE] 如果您之前已为 Claude Code 安装了 Chrome DevTools MCP,请确保首先从您的安装和配置文件中将其移除。

要安装带有技能的 Chrome DevTools MCP,请在 Claude Code 中添加市场注册表:

/plugin marketplace add ChromeDevTools/chrome-devtools-mcp

然后,安装插件:

/plugin install chrome-devtools-mcp@chrome-devtools-plugins

重启 Claude Code 以加载 MCP 服务器和技能(使用 /skills 检查)。

[!TIP] 如果插件安装失败并出现 Failed to clone repository 错误(例如,公司防火墙后的 HTTPS 连接问题),请参阅 故障排除指南 以获取解决方法,或改用上面的 CLI 安装方法。

Cline 遵循 https://docs.cline.bot/mcp/configuring-mcp-servers 并使用上面提供的配置。
Codex 遵循 配置 MCP 指南,使用上面的标准配置。您也可以使用 Codex CLI 安装 Chrome DevTools MCP 服务器:
codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

在 Windows 11 上

通过更新 .codex/config.toml 并添加以下 envstartup_timeout_ms 参数来配置 Chrome 安装位置并增加启动超时时间:

[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
Command Code

使用 Command Code CLI 添加 Chrome DevTools MCP 服务器(MCP 指南):

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

启动 Copilot CLI:

copilot

通过运行以下命令启动添加新 MCP 服务器的对话框:

/mcp add

配置以下字段并按 CTRL+S 保存配置:

  • 服务器名称: chrome-devtools
  • 服务器类型: [1] Local
  • 命令: npx -y chrome-devtools-mcp@latest
Copilot / VS Code

作为插件安装(推荐)

最简单的入门方法是安装 chrome-devtools-mcp 作为智能体插件。这将 MCP 服务器 和所有 技能 捆绑在一起,因此您的智能体既能获得工具,也能获得有效使用它们所需的专家指导。

  1. 打开 命令面板(在 macOS 上为 Cmd+Shift+P,在 Windows/Linux 上为 Ctrl+Shift+P)。
  2. 搜索并运行 Chat: Install Plugin From Source 命令。
  3. 粘贴我们的仓库名称:ChromeDevTools/chrome-devtools-mcp

就是这样!您的智能体现在已通过 Chrome DevTools 功能得到增强。


作为 MCP 服务器安装(仅 MCP)

点击按钮安装:

Install in VS Code

Install in VS Code Insiders

或手动安装:

遵循 VS Code MCP 配置指南,使用上面的标准配置,或使用 CLI:

对于 macOS 和 Linux:

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

对于 Windows (PowerShell):

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

点击按钮安装:

Install in Cursor

或手动安装:

转到 Cursor Settings -> MCP -> New MCP Server。使用上面提供的配置。

Factory CLI 使用 Factory CLI 添加 Chrome DevTools MCP 服务器(指南):
droid mcp add chrome-devtools "npx -y chrome-devtools-mcp@latest"
Gemini CLI 使用 Gemini CLI 安装 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 指南 并使用上面的标准配置。

Gemini Code Assist 遵循 配置 MCP 指南,使用上面的标准配置。
Grok Build CLI
grok mcp add chrome-devtools npx chrome-devtools-mcp@latest

有关更多选项,请参阅 文档

JetBrains AI Assistant 和 Junie

转到 Settings | Tools | AI Assistant | Model Context Protocol (MCP) -> Add。使用上面提供的配置。同样,chrome-devtools-mcp 可以在 Settings | Tools | Junie | MCP Settings -> Add 中为 JetBrains Junie 进行配置。使用上面提供的配置。

Kiro

Kiro 设置 中,转到 Configure MCP > Open Workspace or User MCP Config > 使用上面提供的配置片段。

或者,从 IDE 活动栏 > Kiro > MCP Servers > Click Open MCP Config。使用上面提供的配置片段。

Katalon Studio

Chrome DevTools MCP 服务器可以通过 MCP 代理与 Katalon StudioAssist 一起使用。

第 1 步: 按照 MCP 代理设置指南 安装 MCP 代理。

第 2 步: 使用代理启动 Chrome DevTools MCP 服务器:

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

注意: 如果 8080 端口已被占用,您可能需要选择其他端口。

第 3 步: 在 Katalon Studio 中,使用以下设置将服务器添加到 StudioAssist:

  • 连接 URL: http://127.0.0.1:8080/mcp
  • 传输类型: HTTP

连接后,Chrome DevTools MCP 工具将在 StudioAssist 中可用。

Mistral Vibe

在 ~/.vibe/config.toml 中添加:

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

将以下配置添加到您的 opencode.json 文件中。如果您没有,请在 ~/.config/opencode/opencode.json 处创建它(指南):

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

Qoder 设置 中,转到 MCP Server > + Add > 使用上面提供的配置片段。

或者,遵循 MCP 指南 并使用上面的标准配置。

Qoder CLI

使用 Qoder CLI 安装 Chrome DevTools MCP 服务器(指南):

项目范围:

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

全局:

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

点击按钮安装:

Install in Visual Studio

Warp

转到 Settings | AI | Manage MCP Servers -> + Add添加 MCP 服务器。使用上面提供的配置。

Windsurf 遵循 配置 MCP 指南,使用上面的标准配置。
### 您的第一个提示词

在您的 MCP 客户端中输入以下提示词,检查一切是否正常运行:

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

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

[!NOTE] 当 MCP 客户端使用需要运行浏览器实例的工具时,MCP 服务器将自动启动浏览器。仅连接到 Chrome DevTools MCP 服务器本身不会自动启动浏览器。

工具

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

配置

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

  • --autoConnect/ --auto-connect 如果指定,将自动连接到在本地运行的浏览器(Chrome 144+),该浏览器使用由 channel 参数标识的用户数据目录(默认 channel 为 stable)。需要通过 chrome://inspect/#remote-debugging 在 Chrome 实例中启动远程调试服务器。

    • 类型: boolean
    • 默认值: 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.

    • 类型: string
    • 默认值: false
  • --wsEndpoint/ --ws-endpoint, -w 用于连接到正在运行的 Chrome 实例的 WebSocket 端点(例如,ws://127.0.0.1:9222/devtools/browser/)。--browserUrl 的替代选项。

    • 类型: string
    • 默认值: false
  • --wsHeaders/ --ws-headers WebSocket 连接的自定义标头,采用 JSON 格式(例如,'{"Authorization":"Bearer token"}')。仅适用于 --wsEndpoint。

    • 类型: string
    • 默认值: false
  • --headless 是否以无头模式(无 UI)运行。

    • 类型: boolean
    • 默认值: false
  • --executablePath/ --executable-path, -e 自定义 Chrome 可执行文件的路径。

    • 类型: string
    • 默认值: false
  • --isolated 如果指定,将创建一个临时用户数据目录,并在浏览器关闭后自动清理。默认为 false。

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

    • 类型: string
    • 默认值: false
  • --channel 指定应使用的其他 Chrome 渠道。默认为稳定版渠道。

    • 类型: string
    • 可选值: canary, dev, beta, stable
    • 默认值: false
  • --logFile/ --log-file 用于写入调试日志的文件路径。将环境变量 DEBUG 设置为 * 以启用详细日志。有助于提交错误报告。

    • 类型: string
    • 默认值: false
  • --viewport 服务器启动的 Chrome 实例的初始视口大小。例如,1280x720。在无头模式下,最大尺寸为 3840x2160px。

    • 类型: string
    • 默认值: false
  • --proxyServer/ --proxy-server 启动浏览器时作为 --proxy-server 传递的 Chrome 代理服务器配置。详情请参阅 https://www.chromium.org/developers/design-documents/network-settings/。

    • 类型: string
    • 默认值: false
  • --acceptInsecureCerts/ --accept-insecure-certs 如果启用,将忽略与自签名证书和过期证书相关的错误。请谨慎使用。

    • 类型: boolean
    • 默认值: false
  • --experimentalPageIdRouting/ --experimental-page-id-routing 是否在页面作用域工具上公开 pageId,并按页面 ID 路由请求(对并发代理会话很有用)。

    • 类型: boolean
    • 默认值: false
  • --experimentalDevtools/ --experimental-devtools 是否启用对 DevTools 目标的自动化

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

    • 类型: boolean
    • 默认值: false
  • --memoryDebugging/ --memory-debugging, -experimentalMemory 是否启用内存调试工具。

    • 类型: boolean
    • 默认值: false
  • --experimentalStructuredContent/ --experimental-structured-content 是否输出结构化格式化内容。

    • 类型: boolean
    • 默认值: false
  • --experimentalIncludeAllPages/ --experimental-include-all-pages 是否将所有类型的页面(如 webview 或后台页面)都包含为页面。

    • 类型: boolean
    • 默认值: false
  • --experimentalScreencast/ --experimental-screencast 公开实验性屏幕录制工具(需要 ffmpeg)。安装 ffmpeg https://www.ffmpeg.org/download.html 并确保其在 MCP 服务器的 PATH 中可用。

    • 类型: boolean
    • 默认值: false
  • --experimentalFfmpegPath/ --experimental-ffmpeg-path 用于屏幕录制的 ffmpeg 可执行文件路径。

    • 类型: string
    • 默认值: false
  • --categoryExperimentalWebmcp/ --category-experimental-webmcp 设置为 true 以启用调试 WebMCP 工具。需要 Chrome 149+ 并带有以下标志:--enable-features=WebMCP,DevToolsWebMCPSupport

    • 类型: boolean
    • 默认值: false
  • --chromeArg/ --chrome-arg Chrome 的附加参数。仅在 chrome-devtools-mcp 启动 Chrome 时适用。

    • 类型: array
    • 默认值: false
  • --blockedUrlPattern/ --blocked-url-pattern 通过阻止指定的 URL 模式来限制浏览器的网络访问(使用 https://urlpattern.spec.whatwg.org/)。连接时静默断开与具有被阻止 URL 的目标的连接,并阻止运行时请求(包括导航和子资源)。接受一个模式数组。

    • 类型: array
    • 默认值: false
  • --allowedUrlPattern/ --allowed-url-pattern 通过仅允许指定的 URL 模式来限制浏览器的网络访问(使用 https://urlpattern.spec.whatwg.org/)。需要 Chrome 149+。连接时静默断开与具有未允许 URL 的目标的连接,并阻止运行时请求(包括导航和子资源)。接受一个模式数组。

    • 类型: array
    • 默认值: false
  • --ignoreDefaultChromeArg/ --ignore-default-chrome-arg 显式禁用 Chrome 的默认参数。仅在 chrome-devtools-mcp 启动 Chrome 时适用。

    • 类型: array
    • 默认值: false
  • --categoryEmulation/ --category-emulation 设置为 false 以排除与模拟相关的工具。

    • 类型: boolean
    • 默认值: true
  • --categoryPerformance/ --category-performance 设置为 false 以排除与性能相关的工具。

    • 类型: boolean
    • 默认值: true
  • --categoryNetwork/ --category-network 设置为 false 以排除与网络相关的工具。

    • 类型: boolean
    • 默认值: true
  • --categoryExtensions/ --category-extensions 设置为 true 以包含与扩展程序相关的工具。注意:此功能目前仅支持管道连接。在 149 版本发布之前,autoConnect、browserUrl 和 wsEndpoint 不支持此功能。

    • 类型: boolean
    • 默认值: false
  • --categoryExperimentalThirdParty/ --category-experimental-third-party 设置为 true 以启用被检查页面本身公开的第三方开发者工具

    • 类型: boolean
    • 默认值: false
  • --performanceCrux/ --performance-crux 设置为 false 以禁止将性能跟踪中的 URL 发送到 CrUX API 以获取字段性能数据。

    • 类型: boolean
    • 默认值: true
  • --usageStatistics/ --usage-statistics 设置为 false 以退出使用情况统计数据的收集。Google 收集使用数据以改进工具,并根据 Google 隐私权政策 (https://policies.google.com/privacy) 进行处理。这独立于 Chrome 浏览器指标。如果设置了 CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICSCI 环境变量,则禁用。

    • 类型: boolean
    • 默认值: true
  • --screenshotFormat/ --screenshot-format 当调用者未指定输出格式时,覆盖 take_screenshot 使用的默认输出格式。JPEG 和 WebP 比 PNG 小约 3-5 倍,有助于减少 AI 对话中的上下文大小。未设置则保留现有默认值 ("png")。

    • 类型: string
    • 可选值: jpeg, png, webp
    • 默认值: false
  • --screenshotQuality/ --screenshot-quality 当调用者未指定时,覆盖 take_screenshot 用于 JPEG 和 WebP 的默认压缩质量 (0-100)。值越低,文件越小。对 PNG 无效。未设置则保留 Puppeteer 默认值。

    • 类型: number
    • 默认值: false
  • --screenshotMaxWidth/ --screenshot-max-width 屏幕截图的最大宽度(以像素为单位)。如果捕获的图像更宽,则在返回之前将其缩小(保持纵横比)。减少 AI 对话中的上下文大小。未设置表示不调整大小。

    • 类型: number
    • 默认值: false
  • --screenshotMaxHeight/ --screenshot-max-height 截图的最高像素高度。如果捕获的图像更高,则在返回前会按比例缩小(保持宽高比)。可与 --screenshot-max-width 结合使用;采用较小的缩放比例。未设置表示不调整大小。

    • 类型: number
    • 默认值: false
  • --slim 仅公开一组包含导航、脚本执行和截图的“精简”工具集。适用于基本的浏览器任务。

    • 类型: boolean
    • 默认值: false
  • --redactNetworkHeaders/ --redact-network-headers 如果为 true,则在返回给客户端之前,会编辑掉一些被认为敏感的网络标头。

    • 类型: boolean
    • 默认值: false
  • --allowUnrestrictedPaths/ --allow-unrestricted-paths 如果设置,将禁用当 MCP 客户端未协商 roots 能力时应用的默认路径限制。默认情况下,当未配置 roots 时,文件写入工具仅限于操作系统临时目录。仅在连接未实现 MCP roots 且需要访问临时目录之外路径的受信任本地客户端时使用此选项。

    • 类型: boolean
    • 默认值: 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 来查看所有可用的配置选项。

概念

并发会话

大多数 MCP 客户端为每个对话启动一个 Chrome DevTools MCP 服务器。如果你的客户端在并发代理或子代理之间共享单个服务器实例,请使用 --experimentalPageIdRouting 启动服务器。这会在页面作用域工具上公开 pageId,以便每个代理可以将工具调用路由到其正在使用的标签页。

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

如果你运行多个独立的 MCP 客户端会话,并希望每个会话启动自己的临时 Chrome 配置文件,也请传递 --isolated。这可以避免在这些服务器实例之间共享默认的 Chrome DevTools MCP 用户数据目录。

用户数据目录

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

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

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

点击 允许 后,Chrome DevTools MCP 服务器将打开 developers.chrome.com 并进行性能跟踪。

使用端口转发手动连接

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

以下是关于如何连接到正在运行的 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 浏览器

[!WARNING] 启用远程调试端口会在正在运行的浏览器实例上打开一个调试端口。你机器上的任何应用程序都可以连接到此端口并控制浏览器。确保在调试端口打开时不要浏览任何敏感网站。

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

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

有关远程调试的更多详细信息,请参阅 Chrome DevTools 文档

在 Android 上调试 Chrome

请查阅 这些说明

已知限制

请参阅 故障排除

集成为浏览器子代理

如果你正在开发代理工具,并希望作为产品的一部分提供一个集成的浏览器子代理,我们建议在 Chrome DevTools for agents 的基础上进行构建。

有关参考实现,请参阅 Gemini CLI 浏览器代理文档