Chromedevtools Chrome Devtools MCP

Chrome DevTools MCP（可能指“Chrome开发者工具中的某个特定功能或模块”，但具体含义需根据上下文确定，因为“MCP”在此处没有明确的通用翻译，它可能是一个特定术语或缩写）

chrome-devtools-mcp 让你的编码代理（如Gemini、Claude、Cursor或Copilot） 控制并检查正在运行的Chrome浏览器。它充当模型-上下文-协议的角色 (MCP)服务器，让您的AI编码助手能够充分利用其全部功能 Chrome DevTools，用于可靠的自动化、深入的调试和性能分析。

工具参考 | 更新日志 | 贡献；做出贡献 | 故障排除

主要特点

• 获取性能洞察用途 [Chrome

DevTools（开发者工具）](https://github.com/ChromeDevTools/devtools-frontend) 记录 追踪并提取可操作的性能洞察。

• 高级浏览器调试分析网络请求，截取屏幕截图，并

检查浏览器控制台。

• 可靠的自动化用途

Puppeteer（注：这是一个专有名词，通常指一个用于自动化控制浏览器的库或工具，直接音译为“皮普特”并不常见，但在此按照要求给出音译，实际使用时建议根据上下文或官方翻译来确定） 实现（某过程/系统中的）操作自动化 Chrome 会自动等待操作结果。

免责声明

chrome-devtools-mcp 将浏览器实例的内容暴露给MCP客户端 允许他们在浏览器或开发者工具（DevTools）中检查、调试和修改任何数据。 避免分享你不希望与他人共享的敏感或个人信息 MCP 客户端。

要求

• v20.19或更新版本 最新的长期支持（LTS）维护 版本。
• Chrome 当前稳定版本或更新版本。
• 。

开始入门

在你的MCP客户端中添加以下配置：

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

\[!NOTE\]（注：此标记通常用于指示以下内容为注意事项或重要提示）\ 使用 chrome-devtools-mcp@latest 确保您的MCP客户端始终使用最新版本的Chrome DevTools MCP服务器。

MCP 客户端配置

Amp Follow https://ampcode.com/manual#mcp and use the config provided above. You can also install the Chrome DevTools MCP server using the CLI:

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

Claude Code Use the Claude Code CLI to add the Chrome DevTools MCP server (guide):

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

Cline Follow https://docs.cline.bot/mcp/configuring-mcp-servers and use the config provided above.

Codex Follow the configure MCP guide using the standard config from above. You can also install the Chrome DevTools MCP server using the Codex CLI:

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

在Windows 11上

配置Chrome的安装位置，并通过更新来增加启动超时时间 .codex/config.toml 并添加以下内容 env 并且 startup_timeout_ms 参数：

[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 CLI

启动Copilot CLI：

copilot

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

/mcp add

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

• 服务器名称： chrome-devtools
• 服务器类型： [1] Local
• 命令： npx -y chrome-devtools-mcp@latest

Copilot / VS Code Follow the MCP install guide, with the standard config from above. You can also install the Chrome DevTools MCP server using the VS Code CLI:

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

Cursor

点击按钮进行安装：

[](https://cursor.com/en/install-mcp?name=chrome-devtools&config=eyJjb21tYW5kIjoibnB4IC15IGNocm9tZS1kZXZ0b29scy1tY3BAbGF0ZXN0In0%3D)

或者手动安装：

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

Gemini CLI Install the Chrome DevTools MCP server using the Gemini CLI.

项目范围：

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

全球范围内：

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

或者，按照以下步骤操作 MCP指南 并使用上述的标准配置。

Gemini Code Assist Follow the configure MCP guide using the standard config from above.

JetBrains AI Assistant & Junie

首选 Settings | Tools | AI Assistant | Model Context Protocol (MCP) -> Add使用上面提供的配置。 同样的方法也可以为 JetBrains Junie 配置 chrome-devtools-mcp Settings | Tools | Junie | MCP Settings -> Add使用上面提供的配置。

Kiro

在 Kiro 设置首选 Configure MCP > Open Workspace or User MCP Config > 使用上面提供的配置片段。

或者，从集成开发环境（IDE）中 活动栏 > Kiro > MCP Servers > Click Open MCP Config使用上面提供的配置片段。

Qoder

在 Qoder 设置首选 MCP Server > + Add > 使用上面提供的配置片段。

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

Visual Studio

点击按钮进行安装：

Warp

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

你的第一个提示

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

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

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

\[!NOTE\] （注：此为Markdown或类似标记语言中的一个注释标记，直译为“\[注意\]”，但在实际中文语境中，我们可能会根据上下文选择更合适的表达，如“\[提示\]”、“\[注意\]”或直接作为注释使用。）\ 一旦MCP客户端使用需要运行浏览器实例的工具，MCP服务器将自动启动浏览器。单独连接到Chrome DevTools 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

• 调试 （4种工具）

- evaluate_script - list_console_messages - take_screenshot - take_snapshot

配置

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

• --browserUrl， -u

使用端口转发连接到正在运行的 Chrome 实例。如需更多详细信息，请参阅：https://developer.chrome.com/docs/devtools/remote-debugging/local-server。

- 类型： 字符串

• --wsEndpoint， -w

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

- 类型： 字符串

• --wsHeaders

用于WebSocket连接的JSON格式自定义头部（例如，\{"Authorization":"Bearer token"}\）。仅与\--wsEndpoint\一起使用有效。

- 类型： 字符串

• --headless

是否以无头（无用户界面）模式运行。

- 类型： 布尔（类型） - 默认： false

• --executablePath， -e

自定义Chrome可执行文件的路径。

- 类型： 字符串

• --isolated

如果指定了，则创建一个临时的用户数据目录，浏览器关闭后会自动清理该目录。

- 类型： 布尔型（或布尔值） - 默认： false

• --channel

指定应使用的不同 Chrome 频道。默认使用稳定频道版本。

- 类型： 字符串 - 选项： stable， canary， beta， dev

• --logFile

用于写入调试日志的文件路径。设置环境变量 DEBUG 到；向；对于；在（某个时间或状态）；使；让；以；用；由；在...期间 * 启用详细日志。有助于提交错误报告。

- 类型： 字符串

• --viewport

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

- 类型： 字符串

• --proxyServer

在启动浏览器时，通过 --proxy-server 参数传递给 Chrome 的代理服务器配置。详情请参阅 https://www.chromium.org/developers/design-documents/network-settings/。

- 类型： 字符串

• --acceptInsecureCerts

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

- 类型： 布尔（逻辑）值

• --chromeArg

Chrome 的附加参数。仅在通过 chrome-devtools-mcp 启动 Chrome 时适用。

- 类型： 数组

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

{
  "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/",
        "--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实例： --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浏览器

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

启动Chrome浏览器时启用远程调试端口。在启用调试端口启动新实例之前，请确保关闭所有正在运行的Chrome实例。你选择的端口号必须与你在（相应配置或设置中）指定的端口号一致 --browser-url 在您的MCP客户端配置中的选项。

出于安全原因， Chrome 要求您使用非默认的用户数据目录 在启用远程调试端口时，您可以使用（该功能）指定一个自定义目录 --user-data-dir 标志。这确保您的常规浏览配置文件和数据不会暴露给调试会话。

macOS（发音类似“麦奥斯”，但正式名称通常直接称为“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"

第三步：测试您的设置

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

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

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

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

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

已知的限制

操作系统沙盒

一些MCP客户端允许使用macOS Seatbelt或Linux对MCP服务器进行沙盒化 容器。如果启用了沙箱， chrome-devtools-mcp 无法启动 Chrome 需要权限来创建其自己的沙盒。作为临时解决方案， 或者禁用沙盒功能以 chrome-devtools-mcp 在您的MCP客户端中使用或 --browser-url 连接到你手动在外启动的Chrome实例 MCP客户端沙盒的。