<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/ChromeDevTools/chrome-devtools-mcp) · [上游 README](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# 面向智能体的 Chrome DevTools

[![npm chrome-devtools-mcp package](https://img.shields.io/npm/v/chrome-devtools-mcp.svg)](https://npmjs.org/package/chrome-devtools-mcp)

面向智能体的 Chrome DevTools（`chrome-devtools-mcp`）让你的编程智能体（例如 Antigravity、Claude、Cursor 或 Copilot）
能够控制并检查实时 Chrome 浏览器。它作为模型上下文协议
（Model-Context-Protocol，MCP）服务器运行，为你的 AI 编程助手提供
Chrome DevTools 的全部能力，以实现可靠的自动化、深入调试和性能分析。
同时还提供了[CLI](docs/cli.md)，可在不使用 MCP 的情况下使用。

## [工具参考](./docs/tool-reference.md) | [更新日志](./CHANGELOG.md) | [贡献指南](./CONTRIBUTING.md) | [故障排除](./docs/troubleshooting.md) | [设计原则](./docs/design-principles.md)

## 主要特性

- **获取性能洞察**：使用 [Chrome
  DevTools](https://github.com/ChromeDevTools/devtools-frontend) 录制
  跟踪并提取可操作的性能洞察。
- **高级浏览器调试**：分析网络请求、截取屏幕截图，并
  检查浏览器控制台消息（含 source-mapped 堆栈跟踪）。
- **可靠的自动化**：使用
  [puppeteer](https://github.com/puppeteer/puppeteer) 在 Chrome 中自动化操作，
  并自动等待操作结果。

## 免责声明

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

`chrome-devtools-mcp` 官方支持 Google Chrome 和 [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing/)。
其他基于 Chromium 的浏览器可能可用，但不保证兼容，你可能会遇到意外行为。请自行斟酌使用。
我们致力于为最新版本的 [Extended Stable Chrome](https://chromiumdash.appspot.com/schedule). 提供修复和支持。

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

## **使用统计**

Google 会收集使用统计信息（例如工具调用成功率、延迟和环境信息），以提升 Chrome DevTools MCP 的可靠性和性能。

默认**启用**数据收集。你可以在启动服务器时传入 `--no-usage-statistics` 标志以选择退出：

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

Google 会根据 [Google 隐私政策](https://policies.google.com/privacy). 处理这些数据。

Google 对 Chrome DevTools MCP 使用统计信息的收集，独立于 Chrome 浏览器的使用统计。退出 Chrome 指标并不会自动使你退出本工具，反之亦然。

如果设置了 `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` 或 `CI` 环境变量，则禁用收集。

## 更新检查

默认情况下，服务器会定期检查 npm registry 是否有更新，并在有更新版本可用时记录通知。
你可以通过设置 `CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS` 环境变量来禁用这些更新检查。

## 环境要求

- [Node.js](https://nodejs.org/) [LTS](https://github.com/nodejs/Release#release-schedule) 版本。
- [Chrome](https://www.google.com/chrome/) 当前稳定版或更高版本。
- [npm](https://www.npmjs.com/)

## 快速开始

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

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

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

如果你只想执行基本的浏览器任务，请使用 `--slim` 模式：

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

请参阅 [Slim 工具参考](./docs/slim-tool-reference.md)。

### MCP 客户端配置

<details>
  <summary>Amp</summary>
  遵循 https://ampcode.com/manual#mcp 并使用上面提供的配置。你也可以使用 CLI 安装 Chrome DevTools MCP 服务器：

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

</details>

<details>
  <summary>Antigravity</summary>

要使用 Chrome DevTools MCP 服务器，请按照 <a href="https://antigravity.google/docs/mcp">Antigravity 文档</a> 中的说明安装自定义 MCP 服务器。将以下配置添加到 MCP 服务器配置中：

```bash
{
  "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 图标来启动它。

</details>

<details>
  <summary>Claude Code</summary>

**通过 CLI 安装（仅 MCP）**

使用 Claude Code CLI 添加 Chrome DevTools MCP 服务器（<a href="https://code.claude.com/docs/en/mcp">指南</a>）：

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

**作为插件安装（MCP + Skills）**

> [!NOTE]
> 如果你之前已为 Claude Code 安装过 Chrome DevTools MCP，请确保先从安装和配置文件中将其移除。

要安装带 skills 的 Chrome DevTools MCP，请在 Claude Code 中添加 marketplace registry：

```sh
/plugin marketplace add ChromeDevTools/chrome-devtools-mcp
```

然后安装插件：

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

重启 Claude Code 以加载 MCP 服务器和 skills（使用 `/skills` 检查）。

> [!TIP]
> 如果插件安装失败并出现 `Failed to clone repository` 错误（例如，企业防火墙后的 HTTPS 连接问题），请参阅[故障排除指南](./docs/troubleshooting.md#claude-code-plugin-installation-fails-with-failed-to-clone-repository) 了解变通方法，或改用上面的 CLI 安装方式。

</details>

<details>
  <summary>Cline</summary>
  遵循 https://docs.cline.bot/mcp/configuring-mcp-servers 并使用上面提供的配置。
</details>

<details>
  <summary>Codex</summary>
  按照 <a href="https://developers.openai.com/codex/mcp/#configure-with-the-cli">配置 MCP 指南</a>
  使用上面的标准配置。你也可以使用 Codex CLI 安装 Chrome DevTools MCP 服务器：

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

**在 Windows 11 上**

通过更新 `.codex/config.toml` 并添加以下 `env` 和 `startup_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
```

</details>

<details>
  <summary>Command Code</summary>

使用 Command Code CLI 添加 Chrome DevTools MCP 服务器（<a href="https://commandcode.ai/docs/mcp">MCP 指南</a>）：

```bash
cmd mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
```

</details>

<details>
  <summary>Copilot CLI</summary>

启动 Copilot CLI：

```
copilot
```

运行以下命令以打开添加新 MCP 服务器的对话框：

```
/mcp add
```

配置以下字段，然后按 `CTRL+S` 保存配置：

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

</details>

<details>
  <summary>Copilot / VS Code</summary>

**以插件方式安装（推荐）**

最简便的入门方式是将 `chrome-devtools-mcp` 安装为 agent 插件。
它将 **MCP 服务器** 和所有 **skills** 打包在一起，让你的 agent 同时获得工具以及有效使用它们所需的专业指导。

1.  打开 **命令面板（Command Palette）**（macOS 上为 `Cmd+Shift+P`，Windows/Linux 上为 `Ctrl+Shift+P`）。
2.  搜索并运行 **Chat: Install Plugin From Source** 命令。
3.  粘贴我们的仓库名称：`ChromeDevTools/chrome-devtools-mcp`。

就这么简单！你的 agent 现已具备 Chrome DevTools 能力。

---

**以 MCP 服务器方式安装（仅 MCP）**

**点击按钮安装：**

[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="在 VS Code 中安装">](https://vscode.dev/redirect/mcp/install?name=io.github.ChromeDevTools%2Fchrome-devtools-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22chrome-devtools-mcp%22%5D%2C%22env%22%3A%7B%7D%7D)

[<img src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5" alt="在 VS Code Insiders 中安装">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522io.github.ChromeDevTools%252Fchrome-devtools-mcp%2522%252C%2522config%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522chrome-devtools-mcp%2522%255D%252C%2522env%2522%253A%257B%257D%257D%257D)

**或手动安装：**

按照 VS Code 的 [MCP 配置指南](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server)，使用上文的标准配置，或使用 CLI：

适用于 macOS 和 Linux：

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

适用于 Windows（PowerShell）：

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

</details>

<details>
  <summary>Cursor</summary>

**点击按钮安装：**

[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="在 Cursor 中安装">](https://cursor.com/en/install-mcp?name=chrome-devtools&config=eyJjb21tYW5kIjoibnB4IC15IGNocm9tZS1kZXZ0b29scy1tY3BAbGF0ZXN0In0%3D)

**或手动安装：**

前往 `Cursor Settings` -> `MCP` -> `New MCP Server`。使用上文提供的配置。

</details>

<details>
  <summary>Factory CLI</summary>
使用 Factory CLI 添加 Chrome DevTools MCP 服务器（<a href="https://docs.factory.ai/cli/configuration/mcp">指南</a>）：

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

</details>

<details>
  <summary>Gemini CLI</summary>
使用 Gemini CLI 安装 Chrome DevTools MCP 服务器。

**项目级：**

```bash
# 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
```

**全局：**

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

或者，按照 <a href="https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#how-to-set-up-your-mcp-server">MCP 指南</a>，并使用上文的标准配置。

</details>

<details>
  <summary>Gemini Code Assist</summary>
  按照 <a href="https://cloud.google.com/gemini/docs/codeassist/use-agentic-chat-pair-programmer#configure-mcp-servers">MCP 配置指南</a>，并使用上文的标准配置。
</details>

<details>
  <summary>Grok Build CLI</summary>

```bash
grok mcp add chrome-devtools npx chrome-devtools-mcp@latest
```

更多选项请参阅 <a href="https://docs.x.ai/build/features/skills-plugins-marketplaces">文档</a>
</details>

<details>
  <summary>JetBrains AI Assistant & Junie</summary>

前往 `Settings | Tools | AI Assistant | Model Context Protocol (MCP)` -> `Add`。使用上文提供的配置。
同样地，可在 `Settings | Tools | Junie | MCP Settings` -> `Add` 中为 JetBrains Junie 配置 chrome-devtools-mcp。使用上文提供的配置。

</details>

<details>
  <summary>Kiro</summary>

在 **Kiro Settings** 中，前往 `Configure MCP` > `Open Workspace or User MCP Config` > 使用上文提供的配置片段。

或者，在 IDE **Activity Bar** 中，依次进入 `Kiro` > `MCP Servers` > `Click Open MCP Config`。使用上文提供的配置片段。

</details>

<details>
  <summary>Katalon Studio</summary>

Chrome DevTools MCP 服务器可通过 MCP 代理与 <a href="https://docs.katalon.com/katalon-studio/studioassist/mcp-servers/setting-up-chrome-devtools-mcp-server-for-studioassist">Katalon StudioAssist</a> 配合使用。

**步骤 1：** 按照 <a href="https://docs.katalon.com/katalon-studio/studioassist/mcp-servers/setting-up-mcp-proxy-for-stdio-mcp-servers">MCP 代理设置指南</a> 安装 MCP 代理。

**步骤 2：** 通过代理启动 Chrome DevTools MCP 服务器：

```bash
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 中使用。

</details>

<details>
  <summary>Mistral Vibe</summary>

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

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

</details>

<details>
  <summary>OpenCode</summary>

将以下配置添加到你的 `opencode.json` 文件中。如果尚未创建，请在 `~/.config/opencode/opencode.json` 创建（<a href="https://opencode.ai/docs/mcp-servers">指南</a>）：

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

</details>

<details>
  <summary>Qoder</summary>

在 **Qoder Settings** 中，前往 `MCP Server` > `+ Add` > 使用上文提供的配置片段。

或者，按照 <a href="https://docs.qoder.com/user-guide/chat/model-context-protocol">MCP 指南</a>，并使用上文的标准配置。

</details>

<details>
  <summary>Qoder CLI</summary>

使用 Qoder CLI 安装 Chrome DevTools MCP 服务器（<a href="https://docs.qoder.com/cli/using-cli#mcp-servers">指南</a>）：

**项目级：**

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

**全局：**

```bash
qodercli mcp add -s user chrome-devtools -- npx chrome-devtools-mcp@latest
```

</details>

<details>
  <summary>Visual Studio</summary>

**点击按钮安装：**

[<img src="https://img.shields.io/badge/Visual_Studio-Install-C16FDE?logo=visualstudio&logoColor=white" alt="在 Visual Studio 中安装">](https://vs-open.link/mcp-install?%7B%22name%22%3A%22chrome-devtools%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22chrome-devtools-mcp%40latest%22%5D%7D)

</details>

<details>
  <summary>Warp</summary>

前往 `Settings | AI | Manage MCP Servers` -> `+ Add` 以 [添加 MCP 服务器](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server).。使用上文提供的配置。

</details>

<details>
  <summary>Windsurf</summary>
  按照 <a href="https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json">MCP 配置指南</a>，并使用上文的标准配置。
</details>

### 你的第一个提示

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

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

你的 MCP 客户端应会打开浏览器并记录性能跟踪（performance trace）。

> [!NOTE]
> MCP 服务器会在 MCP 客户端使用需要运行中浏览器实例的工具时自动启动浏览器。单独连接到 Chrome DevTools MCP 服务器并不会自动启动浏览器。

## 工具

如果遇到任何问题，请参阅我们的[故障排除指南](./docs/troubleshooting.md)。

<!-- BEGIN AUTO GENERATED TOOLS -->

- **输入自动化**（10 个工具）
  - [`click`](docs/tool-reference.md#click)
  - [`drag`](docs/tool-reference.md#drag)
  - [`fill`](docs/tool-reference.md#fill)
  - [`fill_form`](docs/tool-reference.md#fill_form)
  - [`handle_dialog`](docs/tool-reference.md#handle_dialog)
  - [`hover`](docs/tool-reference.md#hover)
  - [`press_key`](docs/tool-reference.md#press_key)
  - [`type_text`](docs/tool-reference.md#type_text)
  - [`upload_file`](docs/tool-reference.md#upload_file)
  - [`click_at`](docs/tool-reference.md#click_at)
- **导航自动化**（6 个工具）
  - [`close_page`](docs/tool-reference.md#close_page)
  - [`list_pages`](docs/tool-reference.md#list_pages)
  - [`navigate_page`](docs/tool-reference.md#navigate_page)
  - [`new_page`](docs/tool-reference.md#new_page)
  - [`select_page`](docs/tool-reference.md#select_page)
  - [`wait_for`](docs/tool-reference.md#wait_for)
- **模拟**（2 个工具）
  - [`emulate`](docs/tool-reference.md#emulate)
  - [`resize_page`](docs/tool-reference.md#resize_page)
- **性能**（3 个工具）
  - [`performance_analyze_insight`](docs/tool-reference.md#performance_analyze_insight)
  - [`performance_start_trace`](docs/tool-reference.md#performance_start_trace)
  - [`performance_stop_trace`](docs/tool-reference.md#performance_stop_trace)
- **网络**（2 个工具）
  - [`get_network_request`](docs/tool-reference.md#get_network_request)
  - [`list_network_requests`](docs/tool-reference.md#list_network_requests)
- **调试**（8 个工具）
  - [`evaluate_script`](docs/tool-reference.md#evaluate_script)
  - [`get_console_message`](docs/tool-reference.md#get_console_message)
  - [`lighthouse_audit`](docs/tool-reference.md#lighthouse_audit)
  - [`list_console_messages`](docs/tool-reference.md#list_console_messages)
  - [`take_screenshot`](docs/tool-reference.md#take_screenshot)
  - [`take_snapshot`](docs/tool-reference.md#take_snapshot)
  - [`screencast_start`](docs/tool-reference.md#screencast_start)
  - [`screencast_stop`](docs/tool-reference.md#screencast_stop)
- **内存**（11 个工具）
  - [`take_heapsnapshot`](docs/tool-reference.md#take_heapsnapshot)
  - [`close_heapsnapshot`](docs/tool-reference.md#close_heapsnapshot)
  - [`compare_heapsnapshots`](docs/tool-reference.md#compare_heapsnapshots)
  - [`get_heapsnapshot_class_nodes`](docs/tool-reference.md#get_heapsnapshot_class_nodes)
  - [`get_heapsnapshot_details`](docs/tool-reference.md#get_heapsnapshot_details)
  - [`get_heapsnapshot_dominators`](docs/tool-reference.md#get_heapsnapshot_dominators)
  - [`get_heapsnapshot_duplicate_strings`](docs/tool-reference.md#get_heapsnapshot_duplicate_strings)
  - [`get_heapsnapshot_edges`](docs/tool-reference.md#get_heapsnapshot_edges)
  - [`get_heapsnapshot_retainers`](docs/tool-reference.md#get_heapsnapshot_retainers)
  - [`get_heapsnapshot_retaining_paths`](docs/tool-reference.md#get_heapsnapshot_retaining_paths)
  - [`get_heapsnapshot_summary`](docs/tool-reference.md#get_heapsnapshot_summary)
- **扩展**（5 个工具）
  - [`install_extension`](docs/tool-reference.md#install_extension)
  - [`list_extensions`](docs/tool-reference.md#list_extensions)
  - [`reload_extension`](docs/tool-reference.md#reload_extension)
  - [`trigger_extension_action`](docs/tool-reference.md#trigger_extension_action)
  - [`uninstall_extension`](docs/tool-reference.md#uninstall_extension)
- **第三方**（2 个工具）
  - [`execute_3p_developer_tool`](docs/tool-reference.md#execute_3p_developer_tool)
  - [`list_3p_developer_tools`](docs/tool-reference.md#list_3p_developer_tools)
- **WebMCP**（2 个工具）
  - [`execute_webmcp_tool`](docs/tool-reference.md#execute_webmcp_tool)
  - [`list_webmcp_tools`](docs/tool-reference.md#list_webmcp_tools)

<!-- END AUTO GENERATED TOOLS -->

## 配置

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

<!-- BEGIN AUTO GENERATED OPTIONS -->

- **`--autoConnect`/ `--auto-connect`**
  若指定，则自动连接到在本地运行的浏览器（Chrome 144+），该浏览器使用由 channel 参数标识的用户数据目录（默认 channel 为 stable）。需要在 Chrome 实例中通过 chrome://inspect/#remote-debugging 启动远程调试服务器。
  - **类型：** 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/<id>）。可作为 --browserUrl 的替代方案。
  - **类型：** string
  - **默认值：** `false`

- **`--wsHeaders`/ `--ws-headers`**
  以 JSON 格式为 WebSocket 连接设置的自定义请求头（例如 '{"Authorization":"Bearer token"}'）。仅在使用 --wsEndpoint 时生效。
  - **类型：** string
  - **默认值：** `false`

- **`--headless`**
  是否以无头（headless，无界面）模式运行。
  - **类型：** boolean
  - **默认值：** `false`

- **`--executablePath`/ `--executable-path`, `-e`**
  自定义 Chrome 可执行文件的路径。
  - **类型：** string
  - **默认值：** `false`

- **`--isolated`**
  若指定，则创建临时 user-data-dir，并在浏览器关闭后自动清理。默认为 false。
  - **类型：** boolean
  - **默认值：** `false`

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

- **`--channel`**
  指定要使用的不同 Chrome channel。默认为 stable channel 版本。
  - **类型：** 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 路由请求（适用于并发的 agent 会话）。
  - **类型：** boolean
  - **默认值：** `false`

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

- **`--experimentalVision`/ `--experimental-vision`**
  是否启用基于坐标的工具，例如 click_at(x,y)。通常需要能够通过查看截图生成准确坐标的 computer-use 模型。
  - **类型：** 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`**
  公开实验性屏幕录制（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 以排除与模拟（emulation）相关的工具。
  - **类型：** boolean
  - **默认值：** `true`

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

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

- **`--categoryExtensions`/ `--category-extensions`**
  设为 true 以包含与扩展相关的工具。注意：此功能目前仅支持管道（pipe）连接。autoConnect、browserUrl 和 wsEndpoint 在此功能下不受支持，直到 149 版本发布。
  - **类型：** boolean
  - **默认值：** `false`

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

- **`--performanceCrux`/ `--performance-crux`**
  设为 false 以禁用将性能跟踪中的 URL 发送至 CrUX API 以获取现场（field）性能数据。
  - **类型：** boolean
  - **默认值：** `true`

- **`--usageStatistics`/ `--usage-statistics`**
  设为 false 以选择退出使用情况统计收集。Google 会收集使用数据以改进工具，处理依据 Google 隐私政策（https://policies.google.com/privacy).）。这与 Chrome 浏览器指标无关。如果设置了 `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` 或 `CI` 环境变量，则会禁用。
  - **类型：** 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`

<!-- END AUTO GENERATED OPTIONS -->

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

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

### 通过 WebSocket 连接并携带自定义标头

你可以直接连接到 Chrome WebSocket 端点并包含自定义标头（例如用于身份验证）：

```json
{
  "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 服务器。如果你的客户端在并发 agent 或 subagent 之间共享单个服务器实例，请使用 `--experimentalPageIdRouting` 启动服务器。这会在页面作用域工具上公开 `pageId`，以便每个 agent 可将工具调用路由到其正在操作的标签页。

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

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

### 用户数据目录

`chrome-devtools-mcp` 使用以下用户数据目录启动 Chrome 稳定版（stable channel）实例：

- 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 server 会启动一个带有独立配置文件的全新 Chrome 实例。并非所有场景都适用：

- 若需要在手动站点测试与代理驱动测试之间切换时保持相同的应用状态。
- 当 MCP 需要登录网站时。部分账号在浏览器通过 WebDriver（Chrome DevTools MCP server 的默认启动机制）受控时可能会阻止登录。
- 若在沙箱环境中运行 LLM，但希望连接到沙箱外运行的 Chrome 实例。

在这些情况下，请先启动 Chrome，再让 Chrome DevTools MCP server 连接到该实例。有两种方式：

- **自动连接（Chrome 144 起可用）**：最适合在手动测试与代理驱动测试之间共享状态。
- **通过远程调试端口手动连接**：最适合在沙箱环境中运行时使用。

#### 自动连接到正在运行的 Chrome 实例

**步骤 1：** 在 Chrome 中设置远程调试

在 Chrome（\>= M144）中，按以下步骤设置远程调试：

1.  访问 `chrome://inspect/#remote-debugging` 以启用远程调试。
2.  按照对话框界面允许或拒绝传入的调试连接。

**步骤 2：** 配置 Chrome DevTools MCP server 以自动连接到正在运行的 Chrome 实例

要将 `chrome-devtools-mcp` server 连接到正在运行的 Chrome 实例，请为 MCP server 使用 `--autoConnect` 命令行参数。

以下代码片段是 gemini-cli 的示例配置：

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

**步骤 3：** 测试你的配置

确保浏览器正在运行。打开 gemini-cli 并运行以下提示词：

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

> [!NOTE]
> <code>autoConnect</code> 选项要求用户先启动 Chrome。若用户有多个活动配置文件，MCP server 将连接到默认配置文件（由 Chrome 决定）。MCP server 可访问所选配置文件的所有打开窗口。

Chrome DevTools MCP server 将尝试连接到你正在运行的 Chrome 实例，并显示对话框请求用户授权。

点击 **Allow** 后，Chrome DevTools MCP server 会打开 [developers.chrome.com](http://developers.chrome.com) and taking a performance trace。

#### 使用端口转发手动连接

你可以使用 `--browser-url` 选项连接到正在运行的 Chrome 实例。若你在不允许启动新 Chrome 实例的沙箱环境中运行 MCP server，此方式很有用。

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

**步骤 1：配置 MCP client**

在你的 MCP client 配置中添加 `--browser-url` 选项。该选项的值应为正在运行的 Chrome 实例的 URL。`http://127.0.0.1:9222` 是常用的默认值。

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

**步骤 2：启动 Chrome 浏览器**

> [!WARNING]
> 启用远程调试端口会在运行中的浏览器实例上开放调试端口。你计算机上的任何应用都可连接该端口并控制浏览器。调试端口开启期间，请确保不要浏览任何敏感网站。

启用远程调试端口后启动 Chrome 浏览器。在启动启用调试端口的新实例前，请先关闭所有正在运行的 Chrome 实例。所选端口号必须与 MCP client 配置中 `--browser-url` 选项指定的端口号一致。

出于安全考虑，[Chrome 要求在启用远程调试端口时使用非默认用户数据目录](https://developer.chrome.com/blog/remote-debugging-port) when enabling the remote debugging port. 可使用 `--user-data-dir` 标志指定自定义目录。这可确保你的常规浏览配置文件和数据不会暴露给调试会话。

**macOS**

```bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
```

**Linux**

```bash
/usr/bin/google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
```

**Windows**

```bash
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%TEMP%\chrome-profile-stable"
```

**步骤 3：测试你的配置**

配置好 MCP client 并启动 Chrome 浏览器后，可在 MCP client 中运行简单提示词来测试配置：

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

MCP client 应能连接到正在运行的 Chrome 实例并收到性能报告。

若遇到虚拟机（VM）到主机的端口转发问题，请参阅 [`docs/troubleshooting.md`](./docs/troubleshooting.md#remote-debugging-between-virtual-machine-vm-and-host-fails) 中的“虚拟机（VM）与主机之间远程调试失败”章节。

有关远程调试的更多详情，请参阅 [Chrome DevTools 文档](https://developer.chrome.com/docs/devtools/remote-debugging/).

### 在 Android 上调试 Chrome

请参阅[这些说明](./docs/debugging-android.md)。

## 已知限制

请参阅 [Troubleshooting](./docs/troubleshooting.md)。

## 集成为浏览器子代理（browser subagent）

若你正在开发代理式工具（agentic tooling），并希望在产品中提供集成的浏览器子代理，我们建议在 Chrome DevTools for agents 之上进行构建。

有关参考实现，请参阅 [Gemini CLI 浏览器代理文档](https://geminicli.com/docs/core/subagents/#browser-agent).