Chrome Debug Mcp

chrome-debug-mcp

chrome-debug-mcp 是一款基于异步 Rust 的 Model Context Protocol（MCP） 服务，支持 AI Agent 和大模型通过 Chrome DevTools Protocol（CDP） 原生控制、自动化操作和调试基于 Chromium 的浏览器。它以 Rust 编写，生成单个无依赖的二进制文件，但安装方式与其他 MCP 服务相同：npx -y @raultov/chrome-debug-mcp、Homebrew，或一行安装命令。无需 Rust 工具链。

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

---

✨ 功能

此服务原生实现了一套按 CDP 域和原生进程管理分类的工具： 🛡️ 隐私与安全

• 守护进程稳定性与生命周期（v1.5.0）：

  • 每次导航的有界保留：NetworkState 会自动将每次导航的网络请求数限制为 1,000，并在 Page.frameNavigated 时轮换保留最多 3 次顶层导航的数据。每个连接的 WebSocket 帧数上限为 500 条，控制台日志上限为 1,000 条。
  • 平稳终止工作线程：事件泵任务通过 RAII 句柄（ListenerHandles）管理，并会在标签页关闭或浏览器连接重置时自动中止。
  • 版本匹配与警告：list_instances 会通过 Browser.getVersion 报告检测到的 browser_version 数据，并在 Chrome 主版本低于 120 时附加警告。
  • 可操作的验证：针对标签页和实例的 ID 查找错误会列出所有活动 ID，并在浏览器重启导致先前的标签页句柄失效时提供提示。

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

• 类似无痕模式的体验：默认情况下，个人账户中的 Cookie、历史记录、已保存密码或会话数据不会与受管理的实例共享。

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

• 导入 Cookie（--allow-cookie-import）：使用 --allow-cookie-import 标志启动时，服务允许工具（navigate、open_instance、restart_chrome）接受 copy_cookies: true，以便用你真实 Chrome 会话的 Cookie 填充隔离的临时配置文件。

  • 主动选择与用户同意：默认关闭。设置 copy_cookies: true 前，大模型必须明确征求用户确认。
  • 跨平台兼容性：
    • Linux：支持（通过桌面密钥环解密 AES-128-CBC v11）。会导入 os_crypt.selected_backend，以避免解密失败却未提示的情况。
    • macOS：支持（通过 Chrome 二进制文件 ACL 解密 Keychain v10）。
    • Windows：支持（通过 os_crypt 中的 DPAPI/App-Bound Encryption 处理 v10/v20）。
  • 防止意外重启：如果对正在运行的实例调用 navigate 并设置 copy_cookies: true，系统会返回错误，详细列出所有打开的标签页，并要求设置 confirm_restart: true，才能使用填充了 Cookie 的配置重启实例。
  • 安全性：绝不会复制密码数据库（Login Data）。

• 用户配置文件模式：使用 --user-profile 标志，利用现有系统配置文件启动 Chrome。如果你希望大模型在自己的活动会话（Cookie、已保存的登录信息等）中工作，而不必在每个网站上重新验证身份，此模式会很有用。请谨慎使用，因为这会让大模型访问你的个人浏览器数据。

  • ⚠️ 关于 --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 工具及调用、自定义 CDP 事件、跟踪完成通道）会严格按标签页隔离，避免不同目标之间的事件相互串扰。

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

  • open_tab — 打开新标签页，可选自定义标签和目标 URL。返回包含 tab_id 的 JSON，供其他工具复用。
  • list_tabs — 以 JSON 形式列出该实例所有已打开并注册的标签页（tab_id、label、target_id、url），以及当前活动标签页。如果没有已注册的标签页，工具会回退到实例的默认单标签页连接。
  • close_tab — 按 ID 关闭指定标签页并清理其缓存状态。返回新的活动标签页。
  • switch_tab — 更改工具调用中省略 tab_id 时使用的默认活动标签页，并可选择将其置于前台。

• 便于大模型使用的接口：生命周期工具（open_instance、close_instance、open_tab、list_tabs、switch_tab、close_tab）会返回结构化 JSON，让 Agent 无需通过正则表达式解析文本即可串联调用；其描述遵循标准 MCP 模板（副作用、前置条件、返回值、替代方案），以便模型正确评估其优先级。

• 目标路由（新增）：所有按标签页作用域划分的工具都接受可选的 tab_id 参数，用于将命令路由到特定标签页，并获取该标签页的缓存状态。若省略，则以默认活动标签页为目标。

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

• 用户配置文件支持：可选使用 --user-profile 复用现有的浏览器会话和 Cookie。

• 动态端口管理：自动检测默认端口（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 标志，以免此工具成为命令行注入入口：

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

  预设仅应用于该次调用启动的实例；之后若调用 restart_chrome 时省略 features，则会清除这些预设，与 proxy_server 的行为一致。

• stop_chrome：优雅地关闭受管理的 Chrome 实例（发送 SIGTERM／SIGINT；失败时回退到 SIGKILL）。

• 稳健的生命周期管理：修复了 Chrome 进程未能正常退出的问题。停止时会删除临时配置文件，cdp-browser-lite 会清理因进程被强制终止而遗留的配置文件目录；启动标志和配置文件修补会抑制“Chrome 未正确关闭”的恢复提示气泡。

• ⚠️ 行为变更：现在，MCP 服务进程退出时（包括发生崩溃时），受管理的 Chrome 实例也会终止。此前，受管理的 Chrome 会在服务崩溃后继续运行，并在重启时重新连接；从现在起，它会被终止。已连接的（由用户启动的）Chrome 实例绝不会被终止。

🔐 代理身份验证

• enable_proxy_auth：通过挂接 Fetch CDP 域并提供用户凭据，自动处理代理身份验证挑战。仅当服务通过 --proxy-server 启动时才会开放此功能。
• 稳健性改进：针对较慢的住宅代理提供 30 秒超时，并默认只拦截 Document 请求，以免影响后台请求。
• 预热与凭据：通过 http://api.ipify.org?format=json 预热代理连接。可使用通过 --proxy-username／--proxy-password 传入的凭据，或在工具参数中提供的凭据。

🖱️ 用户输入

• 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），并识别耗时最长的任务（阻塞主线程的操作）。你可以选择禁用缓存并重新加载页面，以模拟冷启动。

🌐 页面与运行时控制

• capture_screenshot：截取当前页面（或完整页面布局）的屏幕截图，并以 base64 编码的图像块形式返回给 LLM 客户端。
• navigate：将活动标签页导航到指定 URL。
• reload：重新加载当前页面。
• inspect_dom：获取完整 HTML，或获取搜索查询附近的智能片段。
  • 上下文搜索：搜索特定文本，并获取其周围可配置数量的字符。
  • 节省令牌：大幅减少大型页面对上下文窗口的占用。
• 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（页面公开的工具） 需要使用 --enable-webmcp 启动服务，以公开工具（webmcp_*）并启用 Chromium 功能开关（--enable-features=WebMCPTesting,DevToolsWebMCPSupport）。所有 WebMCP 工具都接受可选的 tab_id，用于指定目标标签页（省略则使用活动标签页）。

• webmcp_list_tools：列出当前页面向浏览器公开的工具（名称、描述、inputSchema、frameId）。每次跨文档导航后，标签页的工具缓存都会被清除，并通过 WebMCP.enable 重新同步，因此输出始终与 document.modelContext.getTools() 保持一致；同文档（哈希/历史记录）导航会保留缓存。监听器会在启用 CDP 域之前订阅，因此可以捕获 Chrome 的权威重放（WebMCP.enable 会重新发出整个 toolsAdded 列表）：WebMCP.toolsAdded 触发后数毫秒内，这里就会反映新工具（在 Chrome 153 上测得为 1–491 毫秒，而 1.5.5 之前为 2–17 秒）。如果事件通道报告存在事件丢失间隙，工具缓存会从源重新构建，而不会盲目信任现有缓存。

• 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 和依赖注入解耦核心逻辑，确保长期可维护性。

---

📦 安装

每种安装方式都使用在每个 GitHub Release 中发布的相同预编译二进制文件；只有通过 Cargo 和源码安装时才需要 Rust 工具链。npm 包是小型封装程序，其 postinstall 会从 GitHub Releases 下载适用于你平台的预编译二进制文件，无需编译，也无需 Rust 工具链。

⚠️ 请始终使用带作用域的 npm 包名 @raultov/chrome-debug-mcp。 npm 上不带作用域的 chrome-debug-mcp 是另一个无关项目。

想省心安装？下面的一提示词安装方式可以让你的 AI Agent 全程代劳。否则，安装方式按平台分组，并按受欢迎程度排序。

🤖 一提示词安装（适用于任何平台）

将此提示词粘贴到任意 AI 编码 Agent 的聊天窗口（Claude Code、opencode、Cursor、Codex CLI、Copilot 等），让它安装服务，并将其注册到检测到的所有支持 MCP 的客户端：

Install and set up the chrome-debug-mcp MCP server on this machine. Do not launch Chrome yourself — the server launches and manages it automatically.

1. Install the server binary with the first method that works on this OS:
   - Homebrew available (macOS/Linux): brew install raultov/tap/chrome-debug-mcp
   - Node.js >= 14 available (any OS): npm install -g @raultov/chrome-debug-mcp
   - macOS/Linux fallback: curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/chrome-debug-mcp/releases/latest/download/chrome-debug-mcp-installer.sh | sh
   - Windows fallback: download and run the .msi from https://github.com/raultov/chrome-debug-mcp/releases/latest
   Verify with: chrome-debug-mcp --version (add the install dir to PATH if it is not found).

2. Register the MCP server with every AI client you detect on this machine:
   - Claude Code: claude mcp add --scope user chrome-debug-mcp chrome-debug-mcp
   - opencode (and agy, its bridge): merge into ~/.config/opencode/opencode.json —
     "mcp": { "chrome-debug-mcp": { "type": "local", "command": ["chrome-debug-mcp"] } }
   - Codex CLI: append to ~/.codex/config.toml —
     [mcp_servers.chrome-debug-mcp]
     command = "chrome-debug-mcp"
   - Any other MCP-capable client (Cursor, Windsurf, VS Code, ...): add it with its own MCP settings, command "chrome-debug-mcp" with no arguments.

3. Report what you installed and which clients you configured, and remind me to restart each client so the MCP server loads. Do not enable --user-profile or cookie import unless I ask for them.

macOS

1. Homebrew — macOS 上的自然之选：

brew install raultov/tap/chrome-debug-mcp

该 formula 会直接从 GitHub Releases 获取预编译二进制文件（适用于 Apple Silicon 和 Intel），而 brew upgrade 会让你始终使用最新版本。

2. npm / npx — MCP 客户端常用方式（需要 Node.js >= 14）：

npm install -g @raultov/chrome-debug-mcp   # installs the `chrome-debug-mcp` command
npx -y @raultov/chrome-debug-mcp           # ...or just run it once, nothing to install

3. Shell 安装程序 — 一行命令即可安装到 ~/.cargo/bin：

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

4. Cargo — 如果你已经安装了 Rust：

cargo install chrome-debug-mcp     # compiles from crates.io
cargo binstall chrome-debug-mcp    # with cargo-binstall: fetches the pre-compiled binary, no compile

5. 手动下载 — 从 Releases 页面获取 aarch64-apple-darwin 或 x86_64-apple-darwin .tar.xz 压缩包。

Linux

1. npm / npx — MCP 客户端常用方式（需要 Node.js >= 14）：

npm install -g @raultov/chrome-debug-mcp   # installs the `chrome-debug-mcp` command
npx -y @raultov/chrome-debug-mcp           # ...or just run it once, nothing to install

2. Shell 安装程序 — 一行命令即可安装到 ~/.cargo/bin：

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

Linux 二进制文件要求 glibc >= 2.35（Ubuntu 22.04+、Debian 12+、Fedora 36+）。

3. Homebrew（Linuxbrew） — 如果你已经在使用 Linux 版 Homebrew：

brew install raultov/tap/chrome-debug-mcp

4. Cargo — 如果你已经安装了 Rust：

cargo install chrome-debug-mcp     # compiles from crates.io
cargo binstall chrome-debug-mcp    # with cargo-binstall: fetches the pre-compiled binary, no compile

5. 手动下载 — 从 Releases 页面获取 x86_64-unknown-linux-gnu 或 aarch64-unknown-linux-gnu .tar.xz 压缩包。

Windows

1. npm / npx — MCP 客户端常用方式（需要 Node.js >= 14）：

npm install -g @raultov/chrome-debug-mcp   # installs the `chrome-debug-mcp` command
npx -y @raultov/chrome-debug-mcp           # ...or just run it once, nothing to install

2. MSI 安装程序 — 原生 Windows 体验：从 Releases 页面下载 chrome-debug-mcp-x86_64-pc-windows-msvc.msi，然后双击安装。

3. PowerShell 安装程序 — 一行命令：

powershell -ExecutionPolicy Bypass -c "irm https://github.com/raultov/chrome-debug-mcp/releases/latest/download/chrome-debug-mcp-installer.ps1 | iex"

4. Cargo — 如果你已经安装了 Rust：

cargo install chrome-debug-mcp     # compiles from crates.io
cargo binstall chrome-debug-mcp    # with cargo-binstall: fetches the pre-compiled binary, no compile

5. 手动下载 — 从 Releases 页面获取 x86_64-pc-windows-msvc .zip 压缩包。

Docker 与云端

如需了解容器隔离、主机混合模式，以及 Glama 云端的零安装部署，请参阅下方的 Docker 与无头模式用法 部分。

从源码安装

请参阅下方的 编译（从源码） 部分。

---

⚙️ 配置

MCP 服务会通过跨平台搜索来查找 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）。

---

1. MCP 服务启动标志（CLI）

启动 chrome-debug-mcp 时，在命令行中传递这些标志（或在客户端的 args / command 定义中传递），以配置 MCP 服务进程。

标志	描述	默认值	可能的值 / 格式
--local	仅允许导航到本地地址（localhost、127.0.0.1、192.168.x.x、*.local）。强烈建议启用以确保安全。	off	提供标志（on）或省略（off）
--enable-automation	显示原生提示栏：“Chrome is being controlled by automated test software”。	off	提供标志（on）或省略（off）
--user-profile	使用系统默认的 Chrome 配置文件（Cookie、保存的登录信息），而非全新、隔离的临时配置文件。	off	提供标志（on）或省略（off）
--allow-cookie-import	向工具（navigate、open_instance、restart_chrome）公开 Cookie 导入参数（copy_cookies、source_profile、confirm_restart）。	off	提供标志（on）或省略（off）
--enable-webmcp	在 Chrome 实例上启用 WebMCP 测试开关（--enable-features=WebMCPTesting,DevToolsWebMCPSupport），并公开 WebMCP 工具（webmcp_*）。别名：--webmcp。	off	提供标志（on）或省略（off）
--proxy-server <URL>	为 Chrome 实例配置代理服务，并公开代理工具（enable_proxy_auth）。别名：--proxy。	(无)	有效的代理 URL（例如 http://proxy.example.com:8080）
--proxy-username <USER>	代理身份验证的默认用户名。	(无)	字符串用户名
--proxy-password <PASS>	代理身份验证的默认密码。	(无)	字符串密码
--headless	以无头模式运行 Chrome（无 GUI）。在无 GPU 或 Docker 环境中必需。	off	提供标志（on）或省略（off）
--host <HOST>	Chrome 远程调试连接的目标主机 IP 地址。	127.0.0.1	有效的 IP 地址（例如 127.0.0.1、host.docker.internal）
--port <PORT>	主实例的 Chrome 远程调试端口。	9222	任意可用的 TCP 端口（1–65535）
--max-instances <N>	实例池允许的最大并发独立 Chrome 实例数。如果设置了 --user-profile，则忽略此项。	8	正整数（例如 1、4、16）

---

2. 环境变量

变量	描述	默认值	值格式
CHROME_PATH	Chrome 或 Chromium 二进制文件的绝对路径。优先于所有自动二进制文件查找路径。	(未设置)	绝对文件路径（例如 /usr/bin/google-chrome-stable 或 C:\Program Files\Google\Chrome\Application\chrome.exe）

---

3. Chrome 实例启动开关与预设

MCP 服务启动 Chrome 时，会根据启动标志、动态分配的端口，以及每个实例请求的能力预设（例如通过 open_instance 或 restart_chrome 请求）来构造开关。

A. 已应用的 Chromium 原生开关

Chrome / Chromium 原生开关	在使用以下参数启动 chrome-debug-mcp 时触发……	效果 / 说明
--remote-debugging-port=<PORT>	--port <PORT>	将 V8 Inspector CDP WebSocket 端点绑定到指定端口。
--user-data-dir=<TMP_DIR>	未指定 --user-profile (默认)	在 /tmp 中创建隔离的临时配置文件目录，并在关闭时自动删除。
(无 --user-data-dir 开关)	指定 --user-profile	使用系统默认配置文件位置（~/.config/google-chrome、Keychain/DPAPI）。
--headless	指定 --headless	在没有图形界面的情况下运行浏览器。
--disable-infobars	未指定 --enable-automation (默认)	隐藏“受自动化软件控制”通知栏，实现更隐蔽的交互。
(无 --disable-infobars 开关)	指定 --enable-automation	显示原生自动化信息栏。
--proxy-server="<PROXY_URL>"	指定 --proxy-server <URL>	通过指定的 HTTP/SOCKS 代理转发实例的网络流量。
--enable-features=WebMCPTesting,DevToolsWebMCPSupport	指定 --enable-webmcp	在 Chrome 中启用 WebMCP 运行时测试 API（#enable-webmcp-testing）和 DevTools CDP 检查开关（#devtools-webmcp-support）。
--user-data-dir=<SEEDED_TMP_DIR>	配置文件预置 / Cookie 导入 (动态)	将解密后的 Chrome Cookie 复制到新的临时配置文件副本中。

B. 功能预设（features 参数）

动态工具（open_instance、restart_chrome）接受一个 features 数组，其中包含一组封闭的功能预设：

预设名称	应用的 Chrome 命令行开关	使用场景 / 目的
"WEBGL_SOFTWARE"	--use-gl=angle --use-angle=swiftshader --enable-unsafe-swiftshader	在没有 GPU 的容器中强制使用 SwiftShader 软件光栅化来渲染 WebGL。

---

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

chrome-debug-mcp 已全面支持容器运行。这为大模型带来了多种强大的使用场景：

1. 云端部署（通过 Glama）

这是使用此服务最简单的方式。Glama 会启动一个预装 Chrome 的 Docker 容器。大模型无需进行任何本地设置，即可立即访问云端浏览器。

2. 隔离的本地使用

在 Docker 中运行所有内容，无需在主机上安装 Chrome 或 Rust：

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

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

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

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 客户端指向 chrome-debug-mcp 命令。无需再手动启动 Chrome，MCP 服务会自动启动带有正确调试标志的可见 Chrome 实例。

1. 配置 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 中添加并激活此服务。两个位置参数分别是 <name>（服务在 Claude 中的标签）和 <command>（要启动的可执行文件）：

# Run the binary installed by any method above (Homebrew, npm -g, installer, cargo, MSI):
claude mcp add chrome-debug-mcp chrome-debug-mcp
# ...or without installing anything first (Node.js >= 14):
claude mcp add chrome-debug-mcp -- npx -y @raultov/chrome-debug-mcp

2. 使用方法

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

3. Agent 工作流和多实例指南

大模型可以通过几种优化模式使用此服务：

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. 出于安全考虑，WebMCP 默认处于禁用状态。使用 --enable-webmcp 启动 chrome-debug-mcp，以开放 WebMCP 工具并启用 Chrome 的 WebMCP 功能开关（--enable-features=WebMCPTesting,DevToolsWebMCPSupport）。
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

开发与代码质量

make check                                  # Run all local quality gates (fmt, clippy, test, dupes)

# Or run gates individually:
cargo clippy --all-targets -- -D warnings  # Must pass
cargo fmt -- --check                        # Must pass
cargo test --all-targets                    # Run unit tests
cargo dupes check                           # Code duplication check

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

---

📖 为什么选择此 MCP 服务？

Puppeteer/Playwright 包装器等其他集成服务层级较高、体量较大，而且通常无法提供真正可交互的逐步调试器。此 MCP 服务使用原始 CDP 消息，并将其一对一映射到大模型工具，从而让智能 Agent 能够逐句执行 JS、原生读取局部作用域变量、在 V8 编译器上下文中搜索，并准确理解脚本崩溃的原因。

---

📜 许可证

此项目采用 MIT 许可证授权。详情请参阅 LICENSE 文件。