chrome-debug-mcp

chrome-debug-mcp 是一个基于 Rust 的异步 Model Context Protocol (MCP) 服务器，它允许 AI 代理和大语言模型通过 Chrome DevTools Protocol (CDP) 原生地控制、自动化和调试基于 Chromium 的浏览器。

底层使用 cdp-browser-lite（它本身重新导出了 cdp-lite 客户端），这个 MCP 服务器直接挂接到浏览器，避免了繁重的抽象，使你能够直接从编辑器或聊天界面进行实时调试会话。从 v0.2.0 开始，它还可以自动管理 Chrome 进程的生命周期。

✨ 功能特性

该服务器原生实现了一套按 CDP 域和原生进程管理分类的工具：

🛡️ 隐私与安全

• 隔离配置文件（默认）：每次 MCP 服务器启动 Chrome 时，它都会在系统的临时目录中创建一个全新的临时用户配置文件。该配置文件与你的主浏览器配置文件完全独立，并且会在浏览器停止时被删除——一个会话中的 cookies、历史记录、已保存的密码或会话数据绝不会泄漏到下一个会话。

• 类似无痕浏览的体验：默认情况下，来自你个人账户的 cookies、历史记录、已保存的密码或会话数据都不会与受管实例共享。

• 身份保护：即使 LLM 完全控制浏览器，它也无法访问你已登录的会话（例如 Google、GitHub、银行）或冒充你，除非得到明确授权。

• 用户配置文件模式：使用 --user-profile 标志，通过你的现有系统配置文件启动 Chrome。当你希望 LLM 在你活跃的会话（cookies、已保存的登录信息等）中工作，而无需在每个站点重新认证时，这非常有用。请谨慎使用，因为这会让 LLM 访问你的个人浏览器数据。

  • ⚠️ 关于 --user-profile 的说明：由于 Chrome 的单例架构，如果你的浏览器已经打开，它会委托该请求并无法打开调试端口。你必须在启动 MCP 之前关闭所有现有的 Chrome 实例，或者使用 --remote-debugging-port=9222 标志手动启动浏览器。

🚀 Chrome 实例与标签页管理

• 多实例支持：在动态端口上生成并控制多个并发、独立的 Chrome 进程，每个进程都有自己的隔离配置文件目录。使用 --max-instances 标志限制实例数量。

• 实例注册表工具：使用 open_instance、list_instances 和 close_instance 来创建、审计和清理额外的实例。所有现有工具都接受可选的 instance_id 参数，以将命令路由到目标浏览器。

• 多标签页支持（新）：在单个 Chrome 实例中控制多个并发标签页，通过单个 WebSocket 连接多路复用事件流和命令。

  • 自动发现：由目标页面打开的弹出窗口（例如 window.open()）会被自动发现、附加并注册到会话的标签页注册表中。

  • 缓存隔离：状态缓存（控制台消息、网络流量、调试器解析的脚本、WebMCP 工具）按标签页严格隔离，因此事件不会跨目标泄漏。

• 标签页注册表工具（新）：

  • open_tab — 打开一个新标签页，可选地带有自定义标签和目标 URL。返回包含 tab_id 的 JSON，以便在其他工具中复用。

  • list_tabs — 以 JSON 形式列出该实例所有已打开并注册的标签页（tab_id、label、target_id、url），以及当前活动标签页。当没有注册标签页时，工具会回退到实例的默认单标签页连接。

  • close_tab — 按 ID 关闭特定标签页并清理其缓存状态。返回新的活动标签页。

  • switch_tab — 更改在工具调用中省略 tab_id 时使用的默认活动标签页，并可选择将其置于前台。

• 对 LLM 友好的接口：生命周期工具（open_instance、close_instance、open_tab、list_tabs、switch_tab、close_tab）返回结构化 JSON，因此代理可以链接调用而无需用正则表达式解析文本，并且它们的描述遵循标准 MCP 模板（副作用、前提条件、返回值、替代方案），以便模型正确地对它们进行排序。

• 目标路由（新）：所有标签页级工具都接受可选的 tab_id 参数，以将命令定向到特定标签页并从中检索缓存状态。如果省略，则默认以活动标签页为目标。

• 隔离配置文件：默认使用全新的临时配置文件启动 Chrome，确保它不会与你的主浏览器共享 cookies、密码或会话数据。

• 用户配置文件支持：可选地使用 --user-profile 来利用你现有的浏览器会话和 cookies。

• 动态端口管理：自动检测默认端口（9222）是否已被占用。

  • 如果该端口被一个暴露 CDP 的 Chrome 实例（用户启动的或另一个受管的 chrome-debug-mcp 实例）占用，它会自动附加到该实例，而不是生成一个新的实例。

  • 受管配置文件是临时的，因此不存在持久的按端口状态；共享同一端口的第二个服务器只是共享同一个浏览器（并且绝不会杀死已附加的实例）。

• Docker 与无头模式支持：与 Docker 环境完全兼容。使用 --headless 标志在容器内运行没有 GUI 的 Chrome。

• 远程/主机连接：使用 --host 参数连接到运行在另一台机器或主机上的 Chrome 实例（例如，从容器内使用 --host host.docker.internal）。

• 可选的自动化信息栏：添加 --enable-automation 标志以显式显示原生的“Chrome 正受到自动化测试软件控制”消息。默认情况下，此功能被禁用，以实现更隐蔽的交互。

• 代理支持：restart_chrome 现在接受可选的 proxy_server 参数，以启动 Chrome 并通过代理路由流量。

• 自动启动：自动检测 Chrome 是否在指定端口上运行。如果没有，它会使用所需的标志生成一个新实例。

• restart_chrome：重启受管的 Chrome 实例。

• 能力预设：restart_chrome 接受可选的 features 数组，以便客户端可以在每次重启时选择加入额外的浏览器能力。它是一个封闭集合——故意不接受任意的 Chrome 标志，以防止该工具成为命令行注入点：

  • WEB_MCP — 启用实验性的 WebMCP 表面（--enable-features=WebMCPTesting、--categoryExperimentalWebmcp=true），适用于向浏览器暴露工具的网站。

  • WEBGL_SOFTWARE — 强制使用 SwiftShader 软件 WebGL（--use-gl=angle、--use-angle=swiftshader、--enable-unsafe-swiftshader），适用于无 GPU 的环境，例如容器。

  预设适用于该调用启动的实例；之后省略 features 的 restart_chrome 会清除它们，这与 proxy_server 的行为方式一致。

• stop_chrome：优雅地关闭受管的 Chrome 实例（SIGTERM/SIGINT，回退到 SIGKILL）。

• 健壮的生命周期：修复了 Chrome 进程悬挂的问题。临时配置文件会在停止时被删除，cdp-browser-lite 会清理因突然终止而遗留的孤立配置文件目录；通过启动标志和配置文件修补，抑制了“Chrome 未正确关闭”的恢复气泡。

• ⚠️ 行为变更：受管的 Chrome 实例现在会在 MCP 服务器进程退出时被终止（包括崩溃）。以前，受管的 Chrome 在服务器崩溃后仍然存活，并在重启时重新附加；从现在起它会被杀死。已附加的（用户启动的）Chrome 实例永远不会被杀死。

🔐 代理认证

• enable_proxy_auth：通过挂接到 Fetch CDP 域并提供用户提供的凭据（用户名和密码），自动处理代理认证挑战。

• 健壮性改进：现在为较慢的住宅代理提供 30 秒超时，并且默认只拦截 Document 请求，以防止破坏后台请求。

• 预热：自动导航到 prewarm_url（默认为 http://api.ipify.org?format=json），以便在你的主要导航任务之前可靠地建立代理隧道。你可以选择将拦截限制为特定的 resource_type。

🖱️ 用户输入

• click_element：通过使用 CSS 选择器模拟对特定元素的原生鼠标点击。它计算元素的中心坐标并直接分发 CDP 鼠标事件。

• fill_input：用指定的文本填充 DOM 中的输入字段。它通过 CSS 选择器聚焦元素，然后使用原生 CDP Input.insertText。

• scroll：按像素、视口高度（页）滚动页面，或滚动到特定元素。对于与懒加载内容或无限滚动交互至关重要。

📡 网络检查

• get_network_logs：检索拦截到的网络请求（REST/HTTP）和 WebSocket 帧。

• 高级过滤：按 URL、资源类型、WebSocket 方向或负载内容过滤日志。

• 负载检查：访问完整的请求/响应头、REST 响应体和 WebSocket 帧。

• 上下文优化：可选的“摘要模式”，避免淹没 LLM 的上下文窗口。

🪵 控制台与错误

• get_console_logs：从浏览器检索控制台日志。这包括 console.log/warn/error 调用、异常和网络错误。对于排查页面脚本和错误至关重要。包括可选的日志级别过滤和 clear 标志，以高效管理状态。

⚡ 性能与剖析

• get_performance_metrics：从浏览器检索运行时性能指标（例如，JS 堆大小、DOM 节点数、布局持续时间）。有助于快速获取页面内存和计算开销的快照。

• profile_page_performance：记录并分析页面的性能跟踪。它会自动计算 Core Web Vitals（FCP、LCP、DCL、Load）并识别最长的 Long Tasks（主线程阻塞操作）。你可以选择在禁用缓存的情况下重新加载页面，以模拟冷启动。

🌐 页面与运行时控制

• capture_screenshot：截取当前页面（或完整页面布局）的屏幕截图，并将其作为 base64 编码的图像块返回给 LLM 客户端。

• navigate：将活动标签页导航到特定 URL。

• reload：重新加载当前页面。

• inspect_dom：获取整个 HTML 或围绕搜索查询的智能片段。

  • 上下文搜索：搜索特定文本，并获取其周围可配置数量的字符。

  • Token 效率：大幅减少大型页面的上下文窗口使用量。

• evaluate_js：在页面上下文中全局运行任意的 JavaScript 表达式。

🐞 实时调试与执行控制

• pause_on_load: 启用调试器并触发页面重新加载，在解析到的第一条脚本语句处暂停执行。

• search_scripts: 在所有已解析的脚本上下文中搜索查询，以精确定位断点的行和列。

• set_breakpoint: 使用 script_id、url 或精确的 script_hash 设置精确的 JS 断点。

• evaluate_on_call_frame: 直接在当前暂停的调试器调用帧的局部作用域内计算 JavaScript 表达式。

• step_over: 单步跳过下一条表达式语句。

• resume: 取消暂停并恢复执行。

• remove_breakpoint: 移除先前设置的断点。

🧩 WebMCP（页面暴露的工具） 需要使用 WEB_MCP 能力预设重启 Chrome（参见 restart_chrome）。

• webmcp_list_tools: 列出当前页面暴露给浏览器的工具（名称、描述、inputSchema、frameId）。

• webmcp_invoke_tool: 按名称调用页面工具。input 是一个 JSON 对象字符串（例如 "{}" 或 "{\"product\":\"knot\"}"），需与工具的 inputSchema 匹配。最多阻塞等待结果 30 秒。

• webmcp_get_invocation: 按 invocationId 返回调用的状态（Pending/Completed/Error/Canceled）和结果——非阻塞。

• webmcp_list_invocations: 列出会话中所有调用的状态，可选用 status 过滤。

  ⚠️ 同意对话框：具有副作用（剪贴板写入、表单提交等）的页面工具可能会显示一个需要人工点击的页内确认对话框。在这种情况下，webmcp_invoke_tool 会返回一个包含 invocationId 的超时错误——该调用保持 Pending 状态（绝不会被取消），因此你可以在用户批准或拒绝后使用 webmcp_get_invocation 轮询它。

🧪 稳定性与可靠性

• 广泛的单元测试：全面的测试套件，确保事件处理和工具反序列化的可靠性，尤其是在 debugger 领域。

• 无副作用测试：所有单元测试都设计为隔离运行，不启动真实的 Chrome 实例，也不修改文件系统。

• 内部重构：通过 trait 和依赖注入解耦核心逻辑，确保长期可维护性。

Related MCP server: chrome-devtools-mcp

⚙️ 配置

默认情况下，MCP 服务器通过 cdp-browser-lite 的跨平台搜索来发现 Chrome 可执行文件：首先查找 CHROME_PATH（绝对优先级），然后查找 PATH 中的常见二进制文件（google-chrome、google-chrome-stable、chromium、chromium-browser），最后查找操作系统特定的位置（macOS 上的 /Applications/Google Chrome.app/...、Windows 上的 chrome.exe 安装目录、Linux 上的 /usr/bin/google-chrome、/opt/google/chrome/chrome 和 /snap/bin/chromium）。这是服务器先前硬编码路径的严格超集。

参数：

• --local: 仅将导航限制为本地地址（localhost、127.0.0.1、192.168.x.x 或 *.local）。出于安全考虑，强烈推荐。

• --headless: 以无头模式运行 Chrome（无 GUI）。对于 Docker 或服务器环境至关重要。

• --user-profile: 使用默认的系统用户配置文件（会话、Cookie 等），而不是全新的配置文件。这对于在研究会话期间避免重复登录非常有用。

• --host: 指定 Chrome 实例的目标主机（默认：127.0.0.1）。使用 host.docker.internal 从容器连接到宿主机。

• --port: 指定远程调试端口（默认：9222）。

• --enable-automation: 启用“受自动化软件控制”的信息栏。

• --max-instances: 限制并发 Chrome 实例的最大数量（默认：8）。如果设置了 --user-profile，则忽略此参数。

环境变量：

• CHROME_PATH: 显式定义 Chrome 可执行文件的路径。

🐳 Docker 与无头模式用法（v1.0.0）

chrome-debug-mcp 完全支持容器化。这为 LLM 提供了几种强大的用例：

1. 云部署（通过 Glama）

使用此服务器的最简单方式。Glama 会生成一个预装了 Chrome 的 Docker 容器。LLM 无需任何本地设置即可立即访问云中的浏览器。

2. 隔离的本地使用

在 Docker 中运行所有内容，避免在宿主机上安装 Chrome 或 Rust：

docker build -t chrome-mcp .
docker run -i --rm chrome-mcp --headless

3. 混合模式（容器控制宿主机）

MCP 服务器在安全的 Docker 容器内运行，但控制你实际桌面上的 Chrome 实例。这使 LLM 能够在你的真实浏览会话中为你提供帮助：

1. 使用以下参数启动本地 Chrome：--remote-debugging-port=9222

   • 注意：如果在此模式下需要代理支持，你还必须使用 --proxy-server="http://your-proxy:port" 标志启动 Chrome。

2. 运行容器：

# On macOS/Windows
docker run -i --rm chrome-mcp --host host.docker.internal

🚀 快速开始

以原生方式安装和运行 MCP 服务器的最简单方法是通过 Rust 的 Cargo 或下载预编译的二进制文件。你不再需要手动启动 Chrome，MCP 服务器将自动启动一个带有正确调试标志的可见 Chrome 实例。

1. 安装

选项 A：预编译二进制文件（推荐） 前往 Releases 页面，下载适用于你平台（macOS、Windows、Linux）的原生可执行文件。我们为 Windows 提供 .msi 安装程序，为 UNIX 系统提供 shell 脚本。

选项 B：通过 Cargo 安装

cargo install --git https://github.com/raultov/chrome-debug-mcp

选项 C：通过 Shell 脚本安装（Unix）

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/chrome-debug-mcp/releases/latest/download/chrome-debug-mcp-installer.sh | sh

2. 配置你的 MCP 客户端

此服务器已经过全面测试，并确认可与 Claude Code、agy 和 codex 配合使用。使用以下任一模式配置你的 AI 客户端以执行服务器。

通用配置（JSON）

大多数 MCP 客户端（如 Claude Code 或任何基于 JSON 的配置）使用此结构。以下是三种主要使用模式：

{
  "mcpServers": {
    "chrome-debug-mcp": {
      "command": "chrome-debug-mcp",
      "args": [],
      "env": {}
    },
    "chrome-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "chrome-debug-mcp:v1.0.9", "--headless"]
    },
    "chrome-docker-hybrid": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--net=host",
        "chrome-debug-mcp:v1.0.9",
        "--host",
        "127.0.0.1"
      ]
    }
  }
}

注意：在 Linux 上，使用 --net=host 的 chrome-docker-hybrid 模式是推荐的方式，可让容器访问你在 127.0.0.1 上的本地 Chrome 实例。

Claude Code

要在 Claude Code 中添加并激活服务器：

claude mcp add chrome-debug-mcp chrome-debug-mcp

3. 使用

连接后，AI 代理将在执行第一条命令时自动处理启动 Chrome 的操作。浏览器将保持可见，以便你可以直观地跟踪调试过程。

4. 代理工作流与多实例指南

LLM 可以使用几种优化模式来操作此服务器：

A. 隔离的多实例场景

在运行自动化浏览器会话时，你可以启动独立的 Chrome 进程，以防止 Cookie 污染或标签页冲突：

1. 调用 open_instance，并传入 label: "user-session-1" 或可选的代理服务器配置。这将返回一个唯一的 instance_id（例如 chrome-2）。

2. 将 instance_id 显式传递给下游工具，如 navigate、evaluate_js 或 webmcp_list_tools。

3. 完成后使用 close_instance 清理资源。

B. 使用 WebMCP

如果你导航到支持 WebMCP 的页面（例如 https://www.knot.kz/#/agent-tools）：

1. 可以使用 webmcp_list_tools 获取网页注册的工具。

2. 默认情况下，出于安全考虑，WEB_MCP 处于禁用状态。如果工具列表为空，请调用 restart_chrome 并传入 features: ["WEB_MCP"]，然后执行 reload。

3. 使用 webmcp_invoke_tool 调用页面工具，并提供输入 JSON 参数。如果同意对话框暂停了网页上的执行，工具将在 30 秒后超时，但会保持调用挂起状态。你可以使用 webmcp_get_invocation 轮询其结果。

🛠 编译（从源码）

如果你想从源码编译：

git clone https://github.com/raultov/chrome-debug-mcp
cd chrome-debug-mcp
cargo build --release

生成的二进制文件将位于 target/release/chrome-debug-mcp。此项目利用 cargo-dist 通过 GitHub Actions 无缝处理跨平台原生分发。

📖 为什么选择此 MCP 服务器？

其他集成服务器（如 Puppeteer/Playwright 包装器）是高层级的、重量级的，并且通常无法暴露真实的、可交互的逐步调试器。此 MCP 服务器使用原始 CDP 消息，将其 1:1 映射到 LLM 工具，使智能代理能够真正地单步跳过 JS、原生读取局部作用域变量、在 V8 编译器上下文中搜索，并准确理解脚本崩溃的原因。

📜 许可证

此项目根据 MIT 许可证 授权。有关更多详细信息，请参阅 LICENSE 文件。