diff --git a/README.md b/README.md index a8b18a8..0b6070d 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,78 @@ -# Chrome DevTools for agents + +> [!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 for agents (`chrome-devtools-mcp`) lets your coding agent (such as Antigravity, Claude, Cursor or Copilot) -control and inspect a live Chrome browser. It acts as a Model-Context-Protocol -(MCP) server, giving your AI coding assistant access to the full power of -Chrome DevTools for reliable automation, in-depth debugging, and performance analysis. -A [CLI](docs/cli.md) is also provided for use without MCP. +面向智能体的 Chrome DevTools（`chrome-devtools-mcp`）让你的编程智能体（例如 Antigravity、Claude、Cursor 或 Copilot） +能够控制并检查实时 Chrome 浏览器。它作为模型上下文协议 +（Model-Context-Protocol，MCP）服务器运行，为你的 AI 编程助手提供 +Chrome DevTools 的全部能力，以实现可靠的自动化、深入调试和性能分析。 +同时还提供了[CLI](docs/cli.md)，可在不使用 MCP 的情况下使用。 -## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md) +## [工具参考](./docs/tool-reference.md) | [更新日志](./CHANGELOG.md) | [贡献指南](./CONTRIBUTING.md) | [故障排除](./docs/troubleshooting.md) | [设计原则](./docs/design-principles.md) -## Key features +## 主要特性 -- **Get performance insights**: Uses [Chrome - DevTools](https://github.com/ChromeDevTools/devtools-frontend) to record - traces and extract actionable performance insights. -- **Advanced browser debugging**: Analyze network requests, take screenshots and - check browser console messages (with source-mapped stack traces). -- **Reliable automation**. Uses - [puppeteer](https://github.com/puppeteer/puppeteer) to automate actions in - Chrome and automatically wait for action results. +- **获取性能洞察**：使用 [Chrome + DevTools](https://github.com/ChromeDevTools/devtools-frontend) 录制 + 跟踪并提取可操作的性能洞察。 +- **高级浏览器调试**：分析网络请求、截取屏幕截图，并 + 检查浏览器控制台消息（含 source-mapped 堆栈跟踪）。 +- **可靠的自动化**：使用 + [puppeteer](https://github.com/puppeteer/puppeteer) 在 Chrome 中自动化操作， + 并自动等待操作结果。 -## Disclaimers +## 免责声明 -`chrome-devtools-mcp` exposes content of the browser instance to the MCP clients -allowing them to inspect, debug, and modify any data in the browser or DevTools. -Avoid sharing sensitive or personal information that you don't want to share with -MCP clients. +`chrome-devtools-mcp` 会将浏览器实例的内容暴露给 MCP 客户端， +使其能够检查、调试和修改浏览器或 DevTools 中的任何数据。 +请避免共享你不希望与 MCP 客户端共享的敏感或个人信息。 -`chrome-devtools-mcp` officially supports Google Chrome and [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing/) only. -Other Chromium-based browsers may work, but this is not guaranteed, and you may encounter unexpected behavior. Use at your own discretion. -We are committed to providing fixes and support for the latest version of [Extended Stable Chrome](https://chromiumdash.appspot.com/schedule). +`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). 提供修复和支持。 -Performance tools may send trace URLs to the Google CrUX API to fetch real-user -experience data. This helps provide a holistic performance picture by -presenting field data alongside lab data. This data is collected by the [Chrome -User Experience Report (CrUX)](https://developer.chrome.com/docs/crux). To disable -this, run with the `--no-performance-crux` flag. +性能工具可能会将跟踪 URL 发送到 Google CrUX API，以获取真实用户体验数据。 +这有助于通过将现场数据与实验室数据一并呈现，提供全面的性能视图。 +这些数据由 [Chrome +User Experience Report (CrUX)](https://developer.chrome.com/docs/crux). 收集。要禁用 +此功能，请使用 `--no-performance-crux` 标志运行。 -## **Usage statistics** +## **使用统计** -Google collects usage statistics (such as tool invocation success rates, latency, and environment information) to improve the reliability and performance of Chrome DevTools MCP. +Google 会收集使用统计信息（例如工具调用成功率、延迟和环境信息），以提升 Chrome DevTools MCP 的可靠性和性能。 -Data collection is **enabled by default**. You can opt-out by passing the `--no-usage-statistics` flag when starting the server: +默认**启用**数据收集。你可以在启动服务器时传入 `--no-usage-statistics` 标志以选择退出： ```json "args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"] ``` -Google handles this data in accordance with the [Google Privacy Policy](https://policies.google.com/privacy). +Google 会根据 [Google 隐私政策](https://policies.google.com/privacy). 处理这些数据。 -Google's collection of usage statistics for Chrome DevTools MCP is independent from the Chrome browser's usage statistics. Opting out of Chrome metrics does not automatically opt you out of this tool, and vice-versa. +Google 对 Chrome DevTools MCP 使用统计信息的收集，独立于 Chrome 浏览器的使用统计。退出 Chrome 指标并不会自动使你退出本工具，反之亦然。 -Collection is disabled if `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` or `CI` env variables are set. +如果设置了 `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` 或 `CI` 环境变量，则禁用收集。 -## Update checks +## 更新检查 -By default, the server periodically checks the npm registry for updates and logs a notification when a newer version is available. -You can disable these update checks by setting the `CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS` environment variable. +默认情况下，服务器会定期检查 npm registry 是否有更新，并在有更新版本可用时记录通知。 +你可以通过设置 `CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS` 环境变量来禁用这些更新检查。 -## Requirements +## 环境要求 -- [Node.js](https://nodejs.org/) [LTS](https://github.com/nodejs/Release#release-schedule) version. -- [Chrome](https://www.google.com/chrome/) current stable version or newer. +- [Node.js](https://nodejs.org/) [LTS](https://github.com/nodejs/Release#release-schedule) 版本。 +- [Chrome](https://www.google.com/chrome/) 当前稳定版或更高版本。 - [npm](https://www.npmjs.com/) -## Getting started +## 快速开始 -Add the following config to your MCP client: +将以下配置添加到你的 MCP 客户端： ```json { @@ -81,9 +86,9 @@ Add the following config to your MCP client: ``` > [!NOTE] -> Using `chrome-devtools-mcp@latest` ensures that your MCP client will always use the latest version of the Chrome DevTools MCP server. +> 使用 `chrome-devtools-mcp@latest` 可确保你的 MCP 客户端始终使用最新版本的 Chrome DevTools MCP 服务器。 -If you are interested in doing only basic browser tasks, use the `--slim` mode: +如果你只想执行基本的浏览器任务，请使用 `--slim` 模式： ```json { @@ -96,13 +101,13 @@ If you are interested in doing only basic browser tasks, use the `--slim` mode: } ``` -See [Slim tool reference](./docs/slim-tool-reference.md). +请参阅 [Slim 工具参考](./docs/slim-tool-reference.md)。 -### MCP Client configuration +### 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: + 遵循 https://ampcode.com/manual#mcp 并使用上面提供的配置。你也可以使用 CLI 安装 Chrome DevTools MCP 服务器： ```bash amp mcp add chrome-devtools -- npx chrome-devtools-mcp@latest @@ -113,7 +118,7 @@ amp mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
Antigravity -To use the Chrome DevTools MCP server follow the instructions from Antigravity's docs to install a custom MCP server. Add the following config to the MCP servers config: +要使用 Chrome DevTools MCP 服务器，请按照 Antigravity 文档 中的说明安装自定义 MCP 服务器。将以下配置添加到 MCP 服务器配置中： ```bash { @@ -130,64 +135,64 @@ To use the Chrome DevTools MCP server follow the instructions from guide): +使用 Claude Code CLI 添加 Chrome DevTools MCP 服务器（指南）： ```bash claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest ``` -**Install as a Plugin (MCP + Skills)** +**作为插件安装（MCP + Skills）** > [!NOTE] -> If you already had Chrome DevTools MCP installed previously for Claude Code, make sure to remove it first from your installation and configuration files. +> 如果你之前已为 Claude Code 安装过 Chrome DevTools MCP，请确保先从安装和配置文件中将其移除。 -To install Chrome DevTools MCP with skills, add the marketplace registry in Claude Code: +要安装带 skills 的 Chrome DevTools MCP，请在 Claude Code 中添加 marketplace registry： ```sh /plugin marketplace add ChromeDevTools/chrome-devtools-mcp ``` -Then, install the plugin: +然后安装插件： ```sh /plugin install chrome-devtools-mcp@chrome-devtools-plugins ``` -Restart Claude Code to have the MCP server and skills load (check with `/skills`). +重启 Claude Code 以加载 MCP 服务器和 skills（使用 `/skills` 检查）。 > [!TIP] -> If the plugin installation fails with a `Failed to clone repository` error (e.g., HTTPS connectivity issues behind a corporate firewall), see the [troubleshooting guide](./docs/troubleshooting.md#claude-code-plugin-installation-fails-with-failed-to-clone-repository) for workarounds, or use the CLI installation method above instead. +> 如果插件安装失败并出现 `Failed to clone repository` 错误（例如，企业防火墙后的 HTTPS 连接问题），请参阅[故障排除指南](./docs/troubleshooting.md#claude-code-plugin-installation-fails-with-failed-to-clone-repository) 了解变通方法，或改用上面的 CLI 安装方式。
Cline - Follow https://docs.cline.bot/mcp/configuring-mcp-servers and use the config provided above. + 遵循 https://docs.cline.bot/mcp/configuring-mcp-servers 并使用上面提供的配置。
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: + 按照 配置 MCP 指南 + 使用上面的标准配置。你也可以使用 Codex CLI 安装 Chrome DevTools MCP 服务器： ```bash codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest ``` -**On Windows 11** +**在 Windows 11 上** -Configure the Chrome install location and increase the startup timeout by updating `.codex/config.toml` and adding the following `env` and `startup_timeout_ms` parameters: +通过更新 `.codex/config.toml` 并添加以下 `env` 和 `startup_timeout_ms` 参数，配置 Chrome 安装位置并增加启动超时时间： ``` [mcp_servers.chrome-devtools] @@ -207,7 +212,7 @@ startup_timeout_ms = 20_000
Command Code -Use the Command Code CLI to add the Chrome DevTools MCP server (MCP guide): +使用 Command Code CLI 添加 Chrome DevTools MCP 服务器（MCP 指南）： ```bash cmd mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest @@ -218,62 +223,61 @@ cmd mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
Copilot CLI -Start Copilot CLI: +启动 Copilot CLI： ``` copilot ``` -Start the dialog to add a new MCP server by running: +运行以下命令以打开添加新 MCP 服务器的对话框： ``` /mcp add ``` -Configure the following fields and press `CTRL+S` to save the configuration: +配置以下字段，然后按 `CTRL+S` 保存配置： -- **Server name:** `chrome-devtools` -- **Server Type:** `[1] Local` -- **Command:** `npx -y chrome-devtools-mcp@latest` +- **服务器名称：** `chrome-devtools` +- **服务器类型：** `[1] Local` +- **命令：** `npx -y chrome-devtools-mcp@latest`
Copilot / VS Code -**Install as a Plugin (Recommended)** +**以插件方式安装（推荐）** -The easiest way to get up and running is to install `chrome-devtools-mcp` as an agent plugin. -This bundles the **MCP server** and all **skills** together, so your agent gets both the tools -and the expert guidance it needs to use them effectively. +最简便的入门方式是将 `chrome-devtools-mcp` 安装为 agent 插件。 +它将 **MCP 服务器** 和所有 **skills** 打包在一起，让你的 agent 同时获得工具以及有效使用它们所需的专业指导。 -1. Open the **Command Palette** (`Cmd+Shift+P` on macOS or `Ctrl+Shift+P` on Windows/Linux). -2. Search for and run the **Chat: Install Plugin From Source** command. -3. Paste in our repository name: `ChromeDevTools/chrome-devtools-mcp`. +1. 打开 **命令面板（Command Palette）**（macOS 上为 `Cmd+Shift+P`，Windows/Linux 上为 `Ctrl+Shift+P`）。 +2. 搜索并运行 **Chat: Install Plugin From Source** 命令。 +3. 粘贴我们的仓库名称：`ChromeDevTools/chrome-devtools-mcp`。 -That's it! Your agent is now supercharged with Chrome DevTools capabilities. +就这么简单！你的 agent 现已具备 Chrome DevTools 能力。 --- -**Install as an MCP Server (MCP only)** +**以 MCP 服务器方式安装（仅 MCP）** -**Click the button to install:** +**点击按钮安装：** -[Install in 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) +[在 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) -[Install in 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 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) -**Or install manually:** +**或手动安装：** -Follow the VS Code [MCP configuration guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) using the standard config from above, or use the CLI: +按照 VS Code 的 [MCP 配置指南](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server)，使用上文的标准配置，或使用 CLI： -For macOS and Linux: +适用于 macOS 和 Linux： ```bash code --add-mcp '{"name":"io.github.ChromeDevTools/chrome-devtools-mcp","command":"npx","args":["-y","chrome-devtools-mcp"],"env":{}}' ``` -For Windows (PowerShell): +适用于 Windows（PowerShell）： ```powershell code --add-mcp '{"""name""":"""io.github.ChromeDevTools/chrome-devtools-mcp""","""command""":"""npx""","""args""":["""-y""","""chrome-devtools-mcp"""]}' @@ -284,19 +288,19 @@ code --add-mcp '{"""name""":"""io.github.ChromeDevTools/chrome-devtools-mcp""","
Cursor -**Click the button to install:** +**点击按钮安装：** -[Install in Cursor](https://cursor.com/en/install-mcp?name=chrome-devtools&config=eyJjb21tYW5kIjoibnB4IC15IGNocm9tZS1kZXZ0b29scy1tY3BAbGF0ZXN0In0%3D) +[在 Cursor 中安装](https://cursor.com/en/install-mcp?name=chrome-devtools&config=eyJjb21tYW5kIjoibnB4IC15IGNocm9tZS1kZXZ0b29scy1tY3BAbGF0ZXN0In0%3D) -**Or install manually:** +**或手动安装：** -Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above. +前往 `Cursor Settings` -> `MCP` -> `New MCP Server`。使用上文提供的配置。
Factory CLI -Use the Factory CLI to add the Chrome DevTools MCP server (guide): +使用 Factory CLI 添加 Chrome DevTools MCP 服务器（指南）： ```bash droid mcp add chrome-devtools "npx -y chrome-devtools-mcp@latest" @@ -306,9 +310,9 @@ droid mcp add chrome-devtools "npx -y chrome-devtools-mcp@latest"
Gemini CLI -Install the Chrome DevTools MCP server using the Gemini CLI. +使用 Gemini CLI 安装 Chrome DevTools MCP 服务器。 -**Project wide:** +**项目级：** ```bash # Either MCP only: @@ -317,20 +321,19 @@ gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest gemini extensions install --auto-update https://github.com/ChromeDevTools/chrome-devtools-mcp ``` -**Globally:** +**全局：** ```bash gemini mcp add -s user chrome-devtools npx chrome-devtools-mcp@latest ``` -Alternatively, follow the MCP guide and use the standard config from above. +或者，按照 MCP 指南，并使用上文的标准配置。
Gemini Code Assist - Follow the configure MCP guide - using the standard config from above. + 按照 MCP 配置指南，并使用上文的标准配置。
@@ -340,54 +343,54 @@ Alternatively, follow the docs for more options +更多选项请参阅 文档
JetBrains AI Assistant & Junie -Go to `Settings | Tools | AI Assistant | Model Context Protocol (MCP)` -> `Add`. Use the config provided above. -The same way chrome-devtools-mcp can be configured for JetBrains Junie in `Settings | Tools | Junie | MCP Settings` -> `Add`. Use the config provided above. +前往 `Settings | Tools | AI Assistant | Model Context Protocol (MCP)` -> `Add`。使用上文提供的配置。 +同样地，可在 `Settings | Tools | Junie | MCP Settings` -> `Add` 中为 JetBrains Junie 配置 chrome-devtools-mcp。使用上文提供的配置。
Kiro -In **Kiro Settings**, go to `Configure MCP` > `Open Workspace or User MCP Config` > Use the configuration snippet provided above. +在 **Kiro Settings** 中，前往 `Configure MCP` > `Open Workspace or User MCP Config` > 使用上文提供的配置片段。 -Or, from the IDE **Activity Bar** > `Kiro` > `MCP Servers` > `Click Open MCP Config`. Use the configuration snippet provided above. +或者，在 IDE **Activity Bar** 中，依次进入 `Kiro` > `MCP Servers` > `Click Open MCP Config`。使用上文提供的配置片段。
Katalon Studio -The Chrome DevTools MCP server can be used with Katalon StudioAssist via an MCP proxy. +Chrome DevTools MCP 服务器可通过 MCP 代理与 Katalon StudioAssist 配合使用。 -**Step 1:** Install the MCP proxy by following the MCP proxy setup guide. +**步骤 1：** 按照 MCP 代理设置指南 安装 MCP 代理。 -**Step 2:** Start the Chrome DevTools MCP server with the proxy: +**步骤 2：** 通过代理启动 Chrome DevTools MCP 服务器： ```bash mcp-proxy --transport streamablehttp --port 8080 -- npx -y chrome-devtools-mcp@latest ``` -**Note:** You may need to pick another port if 8080 is already in use. +**注意：** 如果 8080 端口已被占用，你可能需要选择其他端口。 -**Step 3:** In Katalon Studio, add the server to StudioAssist with the following settings: +**步骤 3：** 在 Katalon Studio 中，使用以下设置将该服务器添加到 StudioAssist： -- **Connection URL:** `http://127.0.0.1:8080/mcp` -- **Transport type:** `HTTP` +- **连接 URL：** `http://127.0.0.1:8080/mcp` +- **传输类型：** `HTTP` -Once connected, the Chrome DevTools MCP tools will be available in StudioAssist. +连接成功后，Chrome DevTools MCP 工具即可在 StudioAssist 中使用。
Mistral Vibe -Add in ~/.vibe/config.toml: +在 ~/.vibe/config.toml 中添加： ```toml [[mcp_servers]] @@ -402,7 +405,7 @@ args = ["chrome-devtools-mcp@latest"]
OpenCode -Add the following configuration to your `opencode.json` file. If you don't have one, create it at `~/.config/opencode/opencode.json` (guide): +将以下配置添加到你的 `opencode.json` 文件中。如果尚未创建，请在 `~/.config/opencode/opencode.json` 创建（指南）： ```json { @@ -421,24 +424,24 @@ Add the following configuration to your `opencode.json` file. If you don't have
Qoder -In **Qoder Settings**, go to `MCP Server` > `+ Add` > Use the configuration snippet provided above. +在 **Qoder Settings** 中，前往 `MCP Server` > `+ Add` > 使用上文提供的配置片段。 -Alternatively, follow the MCP guide and use the standard config from above. +或者，按照 MCP 指南，并使用上文的标准配置。
Qoder CLI -Install the Chrome DevTools MCP server using the Qoder CLI (guide): +使用 Qoder CLI 安装 Chrome DevTools MCP 服务器（指南）： -**Project wide:** +**项目级：** ```bash qodercli mcp add chrome-devtools -- npx chrome-devtools-mcp@latest ``` -**Globally:** +**全局：** ```bash qodercli mcp add -s user chrome-devtools -- npx chrome-devtools-mcp@latest @@ -449,45 +452,44 @@ qodercli mcp add -s user chrome-devtools -- npx chrome-devtools-mcp@latest
Visual Studio -**Click the button to install:** +**点击按钮安装：** -[Install in 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) +[在 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)
Warp -Go to `Settings | AI | Manage MCP Servers` -> `+ Add` to [add an MCP Server](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). Use the config provided above. +前往 `Settings | AI | Manage MCP Servers` -> `+ Add` 以 [添加 MCP 服务器](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server).。使用上文提供的配置。
Windsurf - Follow the configure MCP guide - using the standard config from above. + 按照 MCP 配置指南，并使用上文的标准配置。
-### Your first prompt +### 你的第一个提示 -Enter the following prompt in your MCP Client to check if everything is working: +在你的 MCP 客户端中输入以下提示，以检查一切是否正常工作： ``` Check the performance of https://developers.chrome.com ``` -Your MCP client should open the browser and record a performance trace. +你的 MCP 客户端应会打开浏览器并记录性能跟踪（performance trace）。 > [!NOTE] -> The MCP server will start the browser automatically once the MCP client uses a tool that requires a running browser instance. Connecting to the Chrome DevTools MCP server on its own will not automatically start the browser. +> MCP 服务器会在 MCP 客户端使用需要运行中浏览器实例的工具时自动启动浏览器。单独连接到 Chrome DevTools MCP 服务器并不会自动启动浏览器。 -## Tools +## 工具 -If you run into any issues, checkout our [troubleshooting guide](./docs/troubleshooting.md). +如果遇到任何问题，请参阅我们的[故障排除指南](./docs/troubleshooting.md)。 -- **Input automation** (10 tools) +- **输入自动化**（10 个工具） - [`click`](docs/tool-reference.md#click) - [`drag`](docs/tool-reference.md#drag) - [`fill`](docs/tool-reference.md#fill) @@ -498,24 +500,24 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles - [`type_text`](docs/tool-reference.md#type_text) - [`upload_file`](docs/tool-reference.md#upload_file) - [`click_at`](docs/tool-reference.md#click_at) -- **Navigation automation** (6 tools) +- **导航自动化**（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) -- **Emulation** (2 tools) +- **模拟**（2 个工具） - [`emulate`](docs/tool-reference.md#emulate) - [`resize_page`](docs/tool-reference.md#resize_page) -- **Performance** (3 tools) +- **性能**（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) -- **Network** (2 tools) +- **网络**（2 个工具） - [`get_network_request`](docs/tool-reference.md#get_network_request) - [`list_network_requests`](docs/tool-reference.md#list_network_requests) -- **Debugging** (8 tools) +- **调试**（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) @@ -524,7 +526,7 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles - [`take_snapshot`](docs/tool-reference.md#take_snapshot) - [`screencast_start`](docs/tool-reference.md#screencast_start) - [`screencast_stop`](docs/tool-reference.md#screencast_stop) -- **Memory** (11 tools) +- **内存**（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) @@ -536,232 +538,232 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles - [`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) -- **Extensions** (5 tools) +- **扩展**（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) -- **Third-party** (2 tools) +- **第三方**（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 tools) +- **WebMCP**（2 个工具） - [`execute_webmcp_tool`](docs/tool-reference.md#execute_webmcp_tool) - [`list_webmcp_tools`](docs/tool-reference.md#list_webmcp_tools) -## Configuration +## 配置 -The Chrome DevTools MCP server supports the following configuration option: +Chrome DevTools MCP 服务器支持以下配置选项： - **`--autoConnect`/ `--auto-connect`** - If specified, automatically connects to a browser (Chrome 144+) running locally from the user data directory identified by the channel param (default channel is stable). Requires the remote debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging. - - **Type:** boolean - - **Default:** `false` + 若指定，则自动连接到在本地运行的浏览器（Chrome 144+），该浏览器使用由 channel 参数标识的用户数据目录（默认 channel 为 stable）。需要在 Chrome 实例中通过 chrome://inspect/#remote-debugging 启动远程调试服务器。 + - **类型：** boolean + - **默认值：** `false` - **`--browserUrl`/ `--browser-url`, `-u`** - Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp#connecting-to-a-running-chrome-instance. - - **Type:** string - - **Default:** `false` + 连接到正在运行且可调试的 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`** - WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/). Alternative to --browserUrl. - - **Type:** string - - **Default:** `false` + 用于连接正在运行的 Chrome 实例的 WebSocket 端点（例如 ws://127.0.0.1:9222/devtools/browser/）。可作为 --browserUrl 的替代方案。 + - **类型：** string + - **默认值：** `false` - **`--wsHeaders`/ `--ws-headers`** - Custom headers for WebSocket connection in JSON format (e.g., '{"Authorization":"Bearer token"}'). Only works with --wsEndpoint. - - **Type:** string - - **Default:** `false` + 以 JSON 格式为 WebSocket 连接设置的自定义请求头（例如 '{"Authorization":"Bearer token"}'）。仅在使用 --wsEndpoint 时生效。 + - **类型：** string + - **默认值：** `false` - **`--headless`** - Whether to run in headless (no UI) mode. - - **Type:** boolean - - **Default:** `false` + 是否以无头（headless，无界面）模式运行。 + - **类型：** boolean + - **默认值：** `false` - **`--executablePath`/ `--executable-path`, `-e`** - Path to custom Chrome executable. - - **Type:** string - - **Default:** `false` + 自定义 Chrome 可执行文件的路径。 + - **类型：** string + - **默认值：** `false` - **`--isolated`** - If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false. - - **Type:** boolean - - **Default:** `false` + 若指定，则创建临时 user-data-dir，并在浏览器关闭后自动清理。默认为 false。 + - **类型：** boolean + - **默认值：** `false` - **`--userDataDir`/ `--user-data-dir`** - Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE - - **Type:** string - - **Default:** `false` + Chrome 用户数据目录的路径。默认为 $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE + - **类型：** string + - **默认值：** `false` - **`--channel`** - Specify a different Chrome channel that should be used. The default is the stable channel version. - - **Type:** string - - **Choices:** `canary`, `dev`, `beta`, `stable` - - **Default:** `false` + 指定要使用的不同 Chrome channel。默认为 stable channel 版本。 + - **类型：** string + - **可选值：** `canary`, `dev`, `beta`, `stable` + - **默认值：** `false` - **`--logFile`/ `--log-file`** - Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports. - - **Type:** string - - **Default:** `false` + 用于写入调试日志的文件路径。将环境变量 `DEBUG` 设置为 `*` 可启用详细日志。便于提交错误报告。 + - **类型：** string + - **默认值：** `false` - **`--viewport`** - Initial viewport size for the Chrome instances started by the server. For example, `1280x720`. In headless mode, max size is 3840x2160px. - - **Type:** string - - **Default:** `false` + 由服务器启动的 Chrome 实例的初始视口大小。例如 `1280x720`。在无头模式下，最大尺寸为 3840x2160px。 + - **类型：** string + - **默认值：** `false` - **`--proxyServer`/ `--proxy-server`** - Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details. - - **Type:** string - - **Default:** `false` + 启动浏览器时作为 --proxy-server 传递给 Chrome 的代理服务器配置。详情请参阅 https://www.chromium.org/developers/design-documents/network-settings/。 + - **类型：** string + - **默认值：** `false` - **`--acceptInsecureCerts`/ `--accept-insecure-certs`** - If enabled, ignores errors relative to self-signed and expired certificates. Use with caution. - - **Type:** boolean - - **Default:** `false` + 若启用，则忽略与自签名和过期证书相关的错误。请谨慎使用。 + - **类型：** boolean + - **默认值：** `false` - **`--experimentalPageIdRouting`/ `--experimental-page-id-routing`** - Whether to expose pageId on page-scoped tools and route requests by page ID (useful for concurrent agent sessions). - - **Type:** boolean - - **Default:** `false` + 是否在页面作用域工具上暴露 pageId，并按页面 ID 路由请求（适用于并发的 agent 会话）。 + - **类型：** boolean + - **默认值：** `false` - **`--experimentalDevtools`/ `--experimental-devtools`** - Whether to enable automation over DevTools targets - - **Type:** boolean - - **Default:** `false` + 是否启用对 DevTools 目标的自动化。 + - **类型：** boolean + - **默认值：** `false` - **`--experimentalVision`/ `--experimental-vision`** - Whether to enable coordinate-based tools such as click_at(x,y). Usually requires a computer-use model able to produce accurate coordinates by looking at screenshots. - - **Type:** boolean - - **Default:** `false` + 是否启用基于坐标的工具，例如 click_at(x,y)。通常需要能够通过查看截图生成准确坐标的 computer-use 模型。 + - **类型：** boolean + - **默认值：** `false` - **`--memoryDebugging`/ `--memory-debugging`, `-experimentalMemory`** - Whether to enable memory debugging tools. - - **Type:** boolean - - **Default:** `false` + 是否启用内存调试工具。 + - **类型：** boolean + - **默认值：** `false` - **`--experimentalStructuredContent`/ `--experimental-structured-content`** - Whether to output structured formatted content. - - **Type:** boolean - - **Default:** `false` + 是否输出结构化格式化内容。 + - **类型：** boolean + - **默认值：** `false` - **`--experimentalIncludeAllPages`/ `--experimental-include-all-pages`** - Whether to include all kinds of pages such as webviews or background pages as pages. - - **Type:** boolean - - **Default:** `false` + 是否将所有类型的页面（例如 webview 或后台页面）视为页面。 + - **类型：** boolean + - **默认值：** `false` - **`--experimentalScreencast`/ `--experimental-screencast`** - Exposes experimental screencast tools (requires ffmpeg). Install ffmpeg https://www.ffmpeg.org/download.html and ensure it is available in the MCP server PATH. - - **Type:** boolean - - **Default:** `false` + 公开实验性屏幕录制（screencast）工具（需要 ffmpeg）。安装 ffmpeg https://www.ffmpeg.org/download.html 并确保其在 MCP 服务器 PATH 中可用。 + - **类型：** boolean + - **默认值：** `false` - **`--experimentalFfmpegPath`/ `--experimental-ffmpeg-path`** - Path to ffmpeg executable for screencast recording. - - **Type:** string - - **Default:** `false` + 屏幕录制所用的 ffmpeg 可执行文件路径。 + - **类型：** string + - **默认值：** `false` - **`--categoryExperimentalWebmcp`/ `--category-experimental-webmcp`** - Set to true to enable debugging WebMCP tools. Requires Chrome 149+ with the following flags: `--enable-features=WebMCP,DevToolsWebMCPSupport` - - **Type:** boolean - - **Default:** `false` + 设为 true 以启用 WebMCP 工具调试。需要 Chrome 149+ 及以下标志：`--enable-features=WebMCP,DevToolsWebMCPSupport` + - **类型：** boolean + - **默认值：** `false` - **`--chromeArg`/ `--chrome-arg`** - Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp. - - **Type:** array - - **Default:** `false` + Chrome 的额外参数。仅在 chrome-devtools-mcp 启动 Chrome 时生效。 + - **类型：** array + - **默认值：** `false` - **`--blockedUrlPattern`/ `--blocked-url-pattern`** - Restricts browser's network access by blocking specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Silently detaches from targets with blocked URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns. - - **Type:** array - - **Default:** `false` + 通过阻止指定的 URL 模式来限制浏览器的网络访问（使用 https://urlpattern.spec.whatwg.org/).）。连接时会静默断开与包含被阻止 URL 的目标的关联，并阻止运行时请求（包括导航和子资源）。接受模式数组。 + - **类型：** array + - **默认值：** `false` - **`--allowedUrlPattern`/ `--allowed-url-pattern`** - Restricts browser's network access by allowing only specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Requires Chrome 149+. Silently detaches from targets with unallowed URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns. - - **Type:** array - - **Default:** `false` + 通过仅允许指定的 URL 模式来限制浏览器的网络访问（使用 https://urlpattern.spec.whatwg.org/).）。需要 Chrome 149+。连接时会静默断开与包含未允许 URL 的目标的关联，并阻止运行时请求（包括导航和子资源）。接受模式数组。 + - **类型：** array + - **默认值：** `false` - **`--ignoreDefaultChromeArg`/ `--ignore-default-chrome-arg`** - Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp. - - **Type:** array - - **Default:** `false` + 显式禁用 Chrome 的默认参数。仅在 chrome-devtools-mcp 启动 Chrome 时生效。 + - **类型：** array + - **默认值：** `false` - **`--categoryEmulation`/ `--category-emulation`** - Set to false to exclude tools related to emulation. - - **Type:** boolean - - **Default:** `true` + 设为 false 以排除与模拟（emulation）相关的工具。 + - **类型：** boolean + - **默认值：** `true` - **`--categoryPerformance`/ `--category-performance`** - Set to false to exclude tools related to performance. - - **Type:** boolean - - **Default:** `true` + 设为 false 以排除与性能相关的工具。 + - **类型：** boolean + - **默认值：** `true` - **`--categoryNetwork`/ `--category-network`** - Set to false to exclude tools related to network. - - **Type:** boolean - - **Default:** `true` + 设为 false 以排除与网络相关的工具。 + - **类型：** boolean + - **默认值：** `true` - **`--categoryExtensions`/ `--category-extensions`** - Set to true to include tools related to extensions. Note: This feature is currently only supported with a pipe connection. autoConnect, browserUrl, and wsEndpoint are not supported with this feature until 149 will be released. - - **Type:** boolean - - **Default:** `false` + 设为 true 以包含与扩展相关的工具。注意：此功能目前仅支持管道（pipe）连接。autoConnect、browserUrl 和 wsEndpoint 在此功能下不受支持，直到 149 版本发布。 + - **类型：** boolean + - **默认值：** `false` - **`--categoryExperimentalThirdParty`/ `--category-experimental-third-party`** - Set to true to enable third-party developer tools exposed by the inspected page itself - - **Type:** boolean - - **Default:** `false` + 设为 true 以启用由被检查页面本身公开的第三方开发者工具。 + - **类型：** boolean + - **默认值：** `false` - **`--performanceCrux`/ `--performance-crux`** - Set to false to disable sending URLs from performance traces to CrUX API to get field performance data. - - **Type:** boolean - - **Default:** `true` + 设为 false 以禁用将性能跟踪中的 URL 发送至 CrUX API 以获取现场（field）性能数据。 + - **类型：** boolean + - **默认值：** `true` - **`--usageStatistics`/ `--usage-statistics`** - Set to false to opt-out of usage statistics collection. Google collects usage data to improve the tool, handled under the Google Privacy Policy (https://policies.google.com/privacy). This is independent from Chrome browser metrics. Disabled if `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` or `CI` env variables are set. - - **Type:** boolean - - **Default:** `true` + 设为 false 以选择退出使用情况统计收集。Google 会收集使用数据以改进工具，处理依据 Google 隐私政策（https://policies.google.com/privacy).）。这与 Chrome 浏览器指标无关。如果设置了 `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` 或 `CI` 环境变量，则会禁用。 + - **类型：** boolean + - **默认值：** `true` - **`--screenshotFormat`/ `--screenshot-format`** - Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which helps reduce context size in AI conversations. Unset preserves the existing default ("png"). - - **Type:** string - - **Choices:** `jpeg`, `png`, `webp` - - **Default:** `false` + 当调用方未指定格式时，覆盖 take_screenshot 使用的默认输出格式。JPEG 和 WebP 比 PNG 小约 3-5 倍，有助于减小 AI 对话中的上下文大小。未设置则保留现有默认值（"png"）。 + - **类型：** string + - **选项：** `jpeg`, `png`, `webp` + - **默认值：** `false` - **`--screenshotQuality`/ `--screenshot-quality`** - Override the default compression quality (0-100) used by take_screenshot for JPEG and WebP when the caller does not specify one. Lower values mean smaller files. Ignored for PNG. Unset preserves the Puppeteer default. - - **Type:** number - - **Default:** `false` + 当调用方未指定时，覆盖 take_screenshot 用于 JPEG 和 WebP 的默认压缩质量（0-100）。值越低文件越小。对 PNG 忽略。未设置则保留 Puppeteer 默认值。 + - **类型：** number + - **默认值：** `false` - **`--screenshotMaxWidth`/ `--screenshot-max-width`** - Maximum width in pixels for screenshots. If the captured image is wider, it is downscaled (preserving aspect ratio) before being returned. Reduces context size in AI conversations. Unset means no resize. - - **Type:** number - - **Default:** `false` + 截图的最大宽度（像素）。如果捕获的图像更宽，会在返回前按比例缩小。可减小 AI 对话中的上下文大小。未设置表示不调整大小。 + - **类型：** number + - **默认值：** `false` - **`--screenshotMaxHeight`/ `--screenshot-max-height`** - Maximum height in pixels for screenshots. If the captured image is taller, it is downscaled (preserving aspect ratio) before being returned. Can be combined with --screenshot-max-width; the smaller scale factor wins. Unset means no resize. - - **Type:** number - - **Default:** `false` + 截图的最大高度（像素）。如果捕获的图像更高，会在返回前按比例缩小。可与 --screenshot-max-width 组合使用；取较小的缩放因子。未设置表示不调整大小。 + - **类型：** number + - **默认值：** `false` - **`--slim`** - Exposes a "slim" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks. - - **Type:** boolean - - **Default:** `false` + 公开一组“精简”的 3 个工具，仅涵盖导航、脚本执行和截图。适用于基本浏览器任务。 + - **类型：** boolean + - **默认值：** `false` - **`--redactNetworkHeaders`/ `--redact-network-headers`** - If true, redacts some of the network headers considered sensitive before returning to the client. - - **Type:** boolean - - **Default:** `false` + 若为 true，在返回给客户端之前会脱敏部分被视为敏感的网络标头。 + - **类型：** boolean + - **默认值：** `false` - **`--allowUnrestrictedPaths`/ `--allow-unrestricted-paths`** - If set, disables the default path restriction that applies when the MCP client does not negotiate the roots capability. By default, file-writing tools are restricted to the OS temp directory when no roots are configured. Use this only when connecting a trusted local client that does not implement MCP roots and requires access to paths outside the temp directory. - - **Type:** boolean - - **Default:** `false` + 若设置，则禁用当 MCP 客户端未协商 roots 能力时应用的默认路径限制。默认情况下，未配置 roots 时，文件写入工具仅限于操作系统临时目录。仅在连接不实现 MCP roots 且需要访问临时目录以外路径的可信本地客户端时使用。 + - **类型：** boolean + - **默认值：** `false` -Pass them via the `args` property in the JSON configuration. For example: +通过 JSON 配置中的 `args` 属性传递它们。例如： ```json { @@ -779,9 +781,9 @@ Pass them via the `args` property in the JSON configuration. For example: } ``` -### Connecting via WebSocket with custom headers +### 通过 WebSocket 连接并携带自定义标头 -You can connect directly to a Chrome WebSocket endpoint and include custom headers (e.g., for authentication): +你可以直接连接到 Chrome WebSocket 端点并包含自定义标头（例如用于身份验证）： ```json { @@ -798,19 +800,15 @@ You can connect directly to a Chrome WebSocket endpoint and include custom heade } ``` -To get the WebSocket endpoint from a running Chrome instance, visit `http://127.0.0.1:9222/json/version` and look for the `webSocketDebuggerUrl` field. +要从正在运行的 Chrome 实例获取 WebSocket 端点，请访问 `http://127.0.0.1:9222/json/version` 并查找 `webSocketDebuggerUrl` 字段。 -You can also run `npx chrome-devtools-mcp@latest --help` to see all available configuration options. +你也可以运行 `npx chrome-devtools-mcp@latest --help` 查看所有可用的配置选项。 -## Concepts +## 概念 -### Concurrent sessions +### 并发会话 -Most MCP clients start one Chrome DevTools MCP server per conversation. If your -client shares a single server instance across concurrent agents or subagents, -start the server with `--experimentalPageIdRouting`. This exposes `pageId` on -page-scoped tools so each agent can route tool calls to the tab it is working -with. +大多数 MCP 客户端会为每个会话启动一个 Chrome DevTools MCP 服务器。如果你的客户端在并发 agent 或 subagent 之间共享单个服务器实例，请使用 `--experimentalPageIdRouting` 启动服务器。这会在页面作用域工具上公开 `pageId`，以便每个 agent 可将工具调用路由到其正在操作的标签页。 ```json { @@ -827,52 +825,44 @@ with. } ``` -If you run multiple independent MCP client sessions and want each session to -launch its own temporary Chrome profile, also pass `--isolated`. This avoids -sharing the default Chrome DevTools MCP user data directory between those -server instances. +如果你运行多个独立的 MCP 客户端会话，并希望每个会话启动自己的临时 Chrome 配置文件，还需传递 `--isolated`。这可避免在这些服务器实例之间共享默认的 Chrome DevTools MCP 用户数据目录。 -### User data directory +### 用户数据目录 -`chrome-devtools-mcp` starts a Chrome's stable channel instance using the following user -data directory: +`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` +- Linux / macOS：`$HOME/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL` +- Windows：`%HOMEPATH%/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL` -The user data directory is not cleared between runs and shared across -all instances of `chrome-devtools-mcp`. Set the `isolated` option to `true` -to use a temporary user data dir instead which will be cleared automatically after -the browser is closed. +用户数据目录在多次运行之间不会被清除，并在 `chrome-devtools-mcp` 的所有实例之间共享。将 `isolated` 选项设置为 `true`，可改用临时用户数据目录；浏览器关闭后会自动清除该目录。 -### Connecting to a running Chrome instance +### 连接到正在运行的 Chrome 实例 -By default, the Chrome DevTools MCP server will start a new Chrome instance with a dedicated profile. This might not be ideal in all situations: +默认情况下，Chrome DevTools MCP server 会启动一个带有独立配置文件的全新 Chrome 实例。并非所有场景都适用： -- If you would like to maintain the same application state when alternating between manual site testing and agent-driven testing. -- When the MCP needs to sign into a website. Some accounts may prevent sign-in when the browser is controlled via WebDriver (the default launch mechanism for the Chrome DevTools MCP server). -- If you're running your LLM inside a sandboxed environment, but you would like to connect to a Chrome instance that runs outside the sandbox. +- 若需要在手动站点测试与代理驱动测试之间切换时保持相同的应用状态。 +- 当 MCP 需要登录网站时。部分账号在浏览器通过 WebDriver（Chrome DevTools MCP server 的默认启动机制）受控时可能会阻止登录。 +- 若在沙箱环境中运行 LLM，但希望连接到沙箱外运行的 Chrome 实例。 -In these cases, start Chrome first and let the Chrome DevTools MCP server connect to it. There are two ways to do so: +在这些情况下，请先启动 Chrome，再让 Chrome DevTools MCP server 连接到该实例。有两种方式： -- **Automatic connection (available in Chrome 144)**: best for sharing state between manual and agent-driven testing. -- **Manual connection via remote debugging port**: best when running inside a sandboxed environment. +- **自动连接（Chrome 144 起可用）**：最适合在手动测试与代理驱动测试之间共享状态。 +- **通过远程调试端口手动连接**：最适合在沙箱环境中运行时使用。 -#### Automatically connecting to a running Chrome instance +#### 自动连接到正在运行的 Chrome 实例 -**Step 1:** Set up remote debugging in Chrome +**步骤 1：** 在 Chrome 中设置远程调试 -In Chrome (\>= M144), do the following to set up remote debugging: +在 Chrome（\>= M144）中，按以下步骤设置远程调试： -1. Navigate to `chrome://inspect/#remote-debugging` to enable remote debugging. -2. Follow the dialog UI to allow or disallow incoming debugging connections. +1. 访问 `chrome://inspect/#remote-debugging` 以启用远程调试。 +2. 按照对话框界面允许或拒绝传入的调试连接。 -**Step 2:** Configure Chrome DevTools MCP server to automatically connect to a running Chrome Instance +**步骤 2：** 配置 Chrome DevTools MCP server 以自动连接到正在运行的 Chrome 实例 -To connect the `chrome-devtools-mcp` server to the running Chrome instance, use -`--autoConnect` command line argument for the MCP server. +要将 `chrome-devtools-mcp` server 连接到正在运行的 Chrome 实例，请为 MCP server 使用 `--autoConnect` 命令行参数。 -The following code snippet is an example configuration for gemini-cli: +以下代码片段是 gemini-cli 的示例配置： ```json { @@ -885,33 +875,30 @@ The following code snippet is an example configuration for gemini-cli: } ``` -**Step 3:** Test your setup +**步骤 3：** 测试你的配置 -Make sure your browser is running. Open gemini-cli and run the following prompt: +确保浏览器正在运行。打开 gemini-cli 并运行以下提示词： ```none Check the performance of https://developers.chrome.com ``` > [!NOTE] -> The autoConnect option requires the user to start Chrome. If the user has multiple active profiles, the MCP server will connect to the default profile (as determined by Chrome). The MCP server has access to all open windows for the selected profile. +> autoConnect 选项要求用户先启动 Chrome。若用户有多个活动配置文件，MCP server 将连接到默认配置文件（由 Chrome 决定）。MCP server 可访问所选配置文件的所有打开窗口。 -The Chrome DevTools MCP server will try to connect to your running Chrome -instance. It shows a dialog asking for user permission. +Chrome DevTools MCP server 将尝试连接到你正在运行的 Chrome 实例，并显示对话框请求用户授权。 -Clicking **Allow** results in the Chrome DevTools MCP server opening -[developers.chrome.com](http://developers.chrome.com) and taking a performance -trace. +点击 **Allow** 后，Chrome DevTools MCP server 会打开 [developers.chrome.com](http://developers.chrome.com) and taking a performance trace。 -#### Manual connection using port forwarding +#### 使用端口转发手动连接 -You can connect to a running Chrome instance by using the `--browser-url` option. This is useful if you are running the MCP server in a sandboxed environment that does not allow starting a new Chrome instance. +你可以使用 `--browser-url` 选项连接到正在运行的 Chrome 实例。若你在不允许启动新 Chrome 实例的沙箱环境中运行 MCP server，此方式很有用。 -Here is a step-by-step guide on how to connect to a running Chrome instance: +以下是连接到正在运行 Chrome 实例的分步指南： -**Step 1: Configure the MCP client** +**步骤 1：配置 MCP client** -Add the `--browser-url` option to your MCP client configuration. The value of this option should be the URL of the running Chrome instance. `http://127.0.0.1:9222` is a common default. +在你的 MCP client 配置中添加 `--browser-url` 选项。该选项的值应为正在运行的 Chrome 实例的 URL。`http://127.0.0.1:9222` 是常用的默认值。 ```json { @@ -927,14 +914,14 @@ Add the `--browser-url` option to your MCP client configuration. The value of th } ``` -**Step 2: Start the Chrome browser** +**步骤 2：启动 Chrome 浏览器** > [!WARNING] -> Enabling the remote debugging port opens up a debugging port on the running browser instance. Any application on your machine can connect to this port and control the browser. Make sure that you are not browsing any sensitive websites while the debugging port is open. +> 启用远程调试端口会在运行中的浏览器实例上开放调试端口。你计算机上的任何应用都可连接该端口并控制浏览器。调试端口开启期间，请确保不要浏览任何敏感网站。 -Start the Chrome browser with the remote debugging port enabled. Make sure to close any running Chrome instances before starting a new one with the debugging port enabled. The port number you choose must be the same as the one you specified in the `--browser-url` option in your MCP client configuration. +启用远程调试端口后启动 Chrome 浏览器。在启动启用调试端口的新实例前，请先关闭所有正在运行的 Chrome 实例。所选端口号必须与 MCP client 配置中 `--browser-url` 选项指定的端口号一致。 -For security reasons, [Chrome requires you to use a non-default user data directory](https://developer.chrome.com/blog/remote-debugging-port) when enabling the remote debugging port. You can specify a custom directory using the `--user-data-dir` flag. This ensures that your regular browsing profile and data are not exposed to the debugging session. +出于安全考虑，[Chrome 要求在启用远程调试端口时使用非默认用户数据目录](https://developer.chrome.com/blog/remote-debugging-port) when enabling the remote debugging port. 可使用 `--user-data-dir` 标志指定自定义目录。这可确保你的常规浏览配置文件和数据不会暴露给调试会话。 **macOS** @@ -954,30 +941,30 @@ For security reasons, [Chrome requires you to use a non-default user data direct "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%TEMP%\chrome-profile-stable" ``` -**Step 3: Test your setup** +**步骤 3：测试你的配置** -After configuring the MCP client and starting the Chrome browser, you can test your setup by running a simple prompt in your MCP client: +配置好 MCP client 并启动 Chrome 浏览器后，可在 MCP client 中运行简单提示词来测试配置： ``` Check the performance of https://developers.chrome.com ``` -Your MCP client should connect to the running Chrome instance and receive a performance report. +MCP client 应能连接到正在运行的 Chrome 实例并收到性能报告。 -If you hit VM-to-host port forwarding issues, see the “Remote debugging between virtual machine (VM) and host fails” section in [`docs/troubleshooting.md`](./docs/troubleshooting.md#remote-debugging-between-virtual-machine-vm-and-host-fails). +若遇到虚拟机（VM）到主机的端口转发问题，请参阅 [`docs/troubleshooting.md`](./docs/troubleshooting.md#remote-debugging-between-virtual-machine-vm-and-host-fails) 中的“虚拟机（VM）与主机之间远程调试失败”章节。 -For more details on remote debugging, see the [Chrome DevTools documentation](https://developer.chrome.com/docs/devtools/remote-debugging/). +有关远程调试的更多详情，请参阅 [Chrome DevTools 文档](https://developer.chrome.com/docs/devtools/remote-debugging/). -### Debugging Chrome on Android +### 在 Android 上调试 Chrome -Please consult [these instructions](./docs/debugging-android.md). +请参阅[这些说明](./docs/debugging-android.md)。 -## Known limitations +## 已知限制 -See [Troubleshooting](./docs/troubleshooting.md). +请参阅 [Troubleshooting](./docs/troubleshooting.md)。 -## Integrating as a browser subagent +## 集成为浏览器子代理（browser subagent） -If you are developing agentic tooling and want to provide an integrated browser subagent as part of your product, we recommend building on top of Chrome DevTools for agents. +若你正在开发代理式工具（agentic tooling），并希望在产品中提供集成的浏览器子代理，我们建议在 Chrome DevTools for agents 之上进行构建。 -For a reference implementation, see the [Gemini CLI browser agent documentation](https://geminicli.com/docs/core/subagents/#browser-agent). +有关参考实现，请参阅 [Gemini CLI 浏览器代理文档](https://geminicli.com/docs/core/subagents/#browser-agent).