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 检索单个请求详情。
  • 浏览器调试 — 使用 take_screenshottake_snapshot 捕获当前页面状态,并通过 list_console_messages 检查控制台输出。
  • 可靠自动化 — 使用 navigate_pageclickfillpress_key 等工具进行导航、点击、填写表单和按键操作。
  • 内存分析 — 使用 take_heapsnapshot 获取堆快照,并进行比较或检查保留器和支配者以诊断内存泄漏。
  • Lighthouse 审计 — 使用 lighthouse_audit 对页面运行 Lighthouse 审计,以评估性能、可访问性和最佳实践。

文档

面向智能体的 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 的浏览器可能也能工作,但这不作保证,您可能会遇到意外行为。请自行决定是否使用。我们致力于为最新版本的 Extended Stable 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。使用上面提供的配置。同样,可以在 Settings | Tools | Junie | MCP Settings -> Add 中为 JetBrains Junie 配置 chrome-devtools-mcp。使用上面提供的配置。

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 如果指定,将自动连接到从由 channel 参数标识的用户数据目录本地运行的浏览器(Chrome 144+)。需要通过 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 Chrome 的代理服务器配置,在启动浏览器时作为 --proxy-server 传递。详情请参阅 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 仅暴露一组包含导航、脚本执行和截图的“精简”工具集(共 3 个)。适用于基本的浏览器任务。

    • 类型: 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 浏览器代理文档