使用chrome-devtools CLI通过HTTPS驱动远程chrome-devtools-mcp服务器(通常部署在tailnet上)。用于用户需要导航、截屏等操作时。
chrome-devtools-remote. 您正在远程运行 chrome-devtools CLI , 以对抗用户运行在另一个主机上的 chrome-dev是一项面向实际任务的技能。它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。
实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。
执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;涉及批量任务时,还应保存进度,避免中断后重复操作。
您正在以 远程 模式运行 chrome-devtools CLI,连接至用户在另一台主机上运行的 chrome-devtools-mcp 服务端。该远程服务端拥有并管理浏览器实例;您的职责是驱动它完成操作。
当收到以下任一请求时触发:
chrome-devtools-mcp 的 HTTPS URL(通常以 /mcp 结尾),并请求执行交互式浏览器操作;CHROME_DEVTOOLS_MCP_REMOTE_URL 或 CHROME_DEVTOOLS_MCP_REMOTE_INSECURE。若用户希望控制一台 本地 浏览器,请改用标准的 chrome-devtools CLI(不带 --remote 参数),或使用 mcp__chrome-devtools__* MCP 工具。
chrome-devtools 客户端 CLI 与服务端同属一个 npm 包。请在运行 agent 的机器上全局安装 —— 不要 在远程主机上安装:
npm install -g @vibebrowser/chrome-devtools-mcp chrome-devtools --version # 应输出 0.26.6 或更高版本
您无需在远程主机上安装任何内容 —— 远程主机应已部署好 https://.../mcp 服务,并通过带外方式完成配置。
常见问题排查:
command not found: chrome-devtools — npm 全局 bin 路径未加入 PATH。请将 $(npm config get prefix)/bin 添加至 PATH;若使用 macOS Homebrew,则在 shell 配置文件(如 ~/.zshrc)中添加 eval "$(brew shellenv)"。Cannot find package 'pkce-challenge' — 属已知打包缺陷(issue dzianisv/chrome-devtools-mcp#17)。临时解决方案:cd "$(npm root -g)/@vibebrowser/chrome-devtools-mcp" && npm install pkce-challenge --no-save。请在每个 shell 会话中 仅配置一次 终端地址,并在执行其他操作前验证连通性。
export CHROME_DEVTOOLS_MCP_REMOTE_URL="https://lab.tailnet.ts.net/mcp" chrome-devtools status --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
健康响应将打印 status=ok http=200 及一段 JSON 正文。任何其他响应均为硬性失败 —— 请直接向用户呈现错误信息,切勿重试。
若未设置 URL,请向用户询问一次终端地址。推荐格式为:https://(/mcp 路径为必需项;仅访问裸域名将返回 404)。
连接时可选参数说明:
| 场景 | 应传入的参数 |
|---|---|
| 自签名证书(常见于未使用 Tailscale 签发证书的 Tailnet 环境) | 每次调用均加 --insecure,或设置环境变量 export CHROME_DEVTOOLS_MCP_REMOTE_INSECURE=1 |
| Bearer Token 网关认证 | --header "Authorization: Bearer $TOKEN" —— 可重复指定,不缓存,每次调用均需显式传入 |
自定义静态请求头(例如 X-Tenant: foo) |
--header "X-Tenant: foo" |
终端位于 Tailscale 后方,但 status 返回 Failed to reach remote |
在本地运行 tailscale status;可能原因:目标主机离线,或 URL 中主机名错误 |
一旦 status 返回成功,后续所有形如 chrome-devtools 的调用,都将复用同一个服务端标签页(Tab),其会话 ID 以粘性方式缓存在 ~/.cache/chrome-devtools-mcp/remote/ 中。
每次 CLI 调用均复用存储于 ~/.cache/chrome-devtools-mcp/remote/ 下的粘性会话 ID。这意味着:
navigate_page → take_snapshot → click → take_screenshot 均作用于 同一 服务端标签页。您可以将其拆分为多个独立 CLI 调用并默认保持上下文连续性。chrome-devtools stop --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"。所有命令均支持 --output-format json 参数,以返回结构化输出,便于通过管道传递给 jq 等工具处理。
# 打开网页
chrome-devtools navigate_page "https://example.com" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
# 获取结构化可访问性快照(用于查找可点击元素的 uid)
chrome-devtools take_snapshot --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL" --output-format json
# 根据快照中获取的 uid 点击元素
chrome-devtools click "$UID" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
# 向输入框填充内容
chrome-devtools fill "$UID" "value" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
# 截图(保存至本地 /tmp/.png )
chrome-devtools take_screenshot --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
# 在页面中执行 JavaScript —— 返回值必须为 JSON 可序列化类型
chrome-devtools evaluate_script '() => document.title' --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
# 读取页面控制台日志
chrome-devtools list_console_messages --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
# 列出页面加载以来的所有网络请求
chrome-devtools list_network_requests --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
URL="$CHROME_DEVTOOLS_MCP_REMOTE_URL"
chrome-devtools navigate_page "https://app.example.com" --remote "$URL"
chrome-devtools evaluate_script '() => ({title: document.title, ready: document.readyState})' --remote "$URL"
chrome-devtools list_console_messages --remote "$URL" --output-format json
chrome-devtools take_screenshot --remote "$URL"
若 console_messages 输出中包含任意 level: "error" 条目,请向用户明确呈现 —— 这类错误通常是“页面显示异常”类问题的根本原因。
chrome-devtools navigate_page "https://app.example.com/login" --remote "$URL" chrome-devtools take_snapshot --remote "$URL" --output-format json > /tmp/snap.json # 从 /tmp/snap.json 中找出邮箱输入框、密码输入框和提交按钮的 uid chrome-devtools fill "" "$LOGIN_EMAIL" --remote "$URL" chrome-devtools fill " " "$LOGIN_PASSWORD" --remote "$URL" chrome-devtools click " " --remote "$URL"
chrome-devtools performance_start_trace --remote "$URL" chrome-devtools navigate_page "https://app.example.com" --remote "$URL" chrome-devtools performance_stop_trace --remote "$URL" --output-format json
Saved to /tmp/.png. )—— CLI 已在 stdout 中自动输出该行。evaluate_script,优先使用 --output-format json,并仅透出相关字段,避免完整输出 structuredContent 封装体。take_snapshot 而非 take_screenshot —— 快照为纯文本,更轻量且易于推理分析。| 现象 | 原因 | 解决方法 |
|---|---|---|
Failed to reach remote |
DNS 解析失败、Tailscale 离线,或 URL 错误 | 在本地主机运行 tailscale status;核对 --remote 参数中的 URL |
Streamable HTTP error: ... 404 Session not found |
服务端重启导致粘性会话 ID 失效;CLI 内部已自动重试一次 —— 若仍出现此错误,说明重试也返回了 404 | 执行 chrome-devtools stop --remote $URL 清除本地粘性会话指针,再重试原命令 |
TLS 验证错误(UNABLE_TO_VERIFY_LEAF_SIGNATURE、SELF_SIGNED_CERT_IN_CHAIN) |
服务端使用自签名证书(未使用 Tailscale 签发的证书) | 添加 --insecure 参数,或设置 export CHROME_DEVTOOLS_MCP_REMOTE_INSECURE=1 |
Bad Request: Mcp-Session-Id header is required |
本地缓存目录在会话中途被清空 | 首次调用将自动创建新会话;直接重试即可 |
| 长时间空闲后首次调用卡住 | 服务端空闲回收机制已关闭该会话 | 同 404 场景处理方式 —— 先 stop,再重试 |
navigate_page 来“等待页面加载完成” —— 应改用带文本选择器的 wait_for。take_screenshot —— 用户几乎总是只需要最终结果截图,而非五张中间过程截图。--insecure —— 此参数会静默禁用整个 CLI 进程的 TLS 验证。--remote 模式下执行 start 子命令 —— 该子命令仅用于管理本地守护进程。