Back to Details

chrome-devtools-remote

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

chrome-devtools-remote

chrome-devtools-remote

You are operating the 
chrome-devtools
CLI in remote mode against a 
chrome-devtools-mcp
server that the user has running on another host. The remote server owns the browser; your job is to drive it.
你将以远程模式操作
chrome-devtools
CLI，连接到用户在另一台主机上运行的
chrome-devtools-mcp
服务器。远程服务器拥有浏览器的控制权，你的任务是驱动该服务器执行操作。

When to use this skill

何时使用此技能

Trigger on any request that:
  • Names a remote machine ("on the lab mac", "on host X", "on my tailnet box") and asks you to do something a browser would do
  • Provides a 
    chrome-devtools-mcp
    HTTPS URL (typically ending in 
    /mcp
    ) and asks for an interactive browser action
  • Mentions environment variables 
    CHROME_DEVTOOLS_MCP_REMOTE_URL
    or 
    CHROME_DEVTOOLS_MCP_REMOTE_INSECURE
If the user wants to drive a local browser, use the regular 
chrome-devtools
CLI (without 
--remote
) or the 
mcp__chrome-devtools__*
MCP tools instead.
当用户的请求满足以下任意条件时，触发此技能：
  • 指定了远程机器（如“在实验室Mac上”、“在主机X上”、“在我的tailnet设备上”）并要求执行浏览器相关操作
  • 提供了
    chrome-devtools-mcp
    的HTTPS URL（通常以
    /mcp
    结尾）并要求执行交互式浏览器操作
  • 提到了环境变量
    CHROME_DEVTOOLS_MCP_REMOTE_URL
    或
    CHROME_DEVTOOLS_MCP_REMOTE_INSECURE
如果用户想要驱动本地浏览器，请使用常规的
chrome-devtools
CLI（不带
--remote
参数）或
mcp__chrome-devtools__*
系列MCP工具。

Install (on the local box, once)

安装（仅需在本地设备执行一次）

The 
chrome-devtools
client CLI ships in the same npm package as the server. Install globally on the machine where the agent runs — not on the remote host:
bash
npm install -g @vibebrowser/chrome-devtools-mcp
chrome-devtools --version   # should print 0.26.6 or newer
You do not install anything on the remote host — that host is whoever already serves 
https://.../mcp
and is set up out-of-band.
Troubleshooting:
  • command not found: chrome-devtools
    — npm's global bin isn't on 
    PATH
    . Add 
    $(npm config get prefix)/bin
    to 
    PATH
    , or on macOS Homebrew add 
    eval "$(brew shellenv)"
    to your shell rc.
  • Cannot find package 'pkce-challenge'
    on first run — known bundling gap (issue dzianisv/chrome-devtools-mcp#17). Workaround: 
    cd "$(npm root -g)/@vibebrowser/chrome-devtools-mcp" && npm install pkce-challenge --no-save
    .
chrome-devtools
客户端CLI与服务器端程序打包在同一个npm包中。请在Agent运行的机器上全局安装——不要在远程主机上安装：
bash
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环境下，将
    eval "$(brew shellenv)"
    添加到shell配置文件中。
  • 首次运行时出现
    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
    。

Connect

连接配置

Configure the endpoint once per shell session and verify connectivity before doing anything else.
bash
export CHROME_DEVTOOLS_MCP_REMOTE_URL="https://lab.tailnet.ts.net/mcp"
chrome-devtools status --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
A healthy response prints 
status=ok http=200
plus a JSON body. Anything else is a hard stop — surface the error to the user instead of retrying.
If the URL is unset, ask the user once for the endpoint. Conventional shape: 
https://<host>/mcp
(the 
/mcp
path is required — the bare host returns a 404).
Connection-time flags:
SituationWhat to pass
Self-signed cert (common on tailnets without Tailscale-issued certs)
--insecure
on every call, or 
export CHROME_DEVTOOLS_MCP_REMOTE_INSECURE=1
Bearer-token gateway
--header "Authorization: Bearer $TOKEN"
— repeatable, not cached, must be on every invocation
Custom static header (e.g. 
X-Tenant: foo
)
--header "X-Tenant: foo"
Endpoint behind Tailscale and 
status
returns 
Failed to reach remote
tailscale status
locally; the box is offline or the URL has the wrong hostname
Once 
status
is green, every subsequent 
chrome-devtools <tool> ... --remote "$URL"
call reuses the same server-side tab via a sticky session id cached at 
~/.cache/chrome-devtools-mcp/remote/<hash>.session
.
每个shell会话只需配置一次端点，在执行其他操作前先验证连接性。
bash
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://<host>/mcp
（必须包含
/mcp
路径——仅输入主机地址会返回404错误）。
连接时可用的参数：
场景需传入的参数
使用自签名证书（在未使用Tailscale颁发证书的tailnet中很常见）每次调用时添加
--insecure
，或设置环境变量
export CHROME_DEVTOOLS_MCP_REMOTE_INSECURE=1
需Bearer令牌验证的网关
--header "Authorization: Bearer $TOKEN"
——可重复添加，不会被缓存，每次调用都必须传入
自定义静态请求头（例如
X-Tenant: foo
）
--header "X-Tenant: foo"
端点位于Tailscale后，且
status
命令返回
Failed to reach remote
在本地执行
tailscale status
；设备可能离线或URL中的主机名错误
当
status
命令返回正常后，后续所有
chrome-devtools <tool> ... --remote "$URL"
调用都会通过存储在
~/.cache/chrome-devtools-mcp/remote/<hash>.session
中的粘性会话ID，复用同一服务器端标签页。

Session model — read this before chaining commands

会话模型——执行链式命令前请阅读

Each CLI invocation reuses a sticky session id stored under 
~/.cache/chrome-devtools-mcp/remote/<hash>.session
. This means:
  • navigate_page
    → 
    take_snapshot
    → 
    click
    → 
    take_screenshot
    all hit the same server-side tab. You can chain them as separate CLI calls and assume continuity.
  • If the server restarts between calls, the next call transparently re-initializes against a fresh session. Tab state on the server is lost — re-navigate before assuming anything.
  • To explicitly end the server-side session and free its browser context, run 
    chrome-devtools stop --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
    .
每个CLI调用都会复用存储在
~/.cache/chrome-devtools-mcp/remote/<hash>.session
中的粘性会话ID，这意味着：
  • navigate_page
    → 
    take_snapshot
    → 
    click
    → 
    take_screenshot
    所有操作都会作用于同一服务器端标签页。你可以将它们作为独立的CLI调用链式执行，无需担心上下文中断。
  • 如果在两次调用之间服务器重启，下一次调用会自动重新初始化新会话。服务器端标签页的状态会丢失——请重新导航后再执行后续操作。
  • 要显式终止服务器端会话并释放浏览器上下文，请执行
    chrome-devtools stop --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
    。

Common operations

常用操作

All commands accept 
--output-format json
to return structured output you can pipe into 
jq
.
bash
undefined
所有命令都支持
--output-format json
参数，返回结构化输出可通过管道传入
jq
工具处理。
bash
undefined

Open a page

打开页面

chrome-devtools navigate_page "https://example.com" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
chrome-devtools navigate_page "https://example.com" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

Get a structured a11y snapshot (use for finding clickable uids)

获取结构化无障碍快照（用于查找可点击元素的uid）

chrome-devtools take_snapshot --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL" --output-format json
chrome-devtools take_snapshot --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL" --output-format json

Click an element by uid from the snapshot

通过快照中的uid点击元素

chrome-devtools click "$UID" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
chrome-devtools click "$UID" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

Fill an input

填充输入框

chrome-devtools fill "$UID" "value" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
chrome-devtools fill "$UID" "value" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

Take a screenshot (saved to /tmp/<uuid>.png locally)

截图（保存到本地/tmp/<uuid>.png）

chrome-devtools take_screenshot --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
chrome-devtools take_screenshot --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

Evaluate JS in the page — return value must be JSON-serializable

在页面中执行JS代码——返回值必须可序列化为JSON

chrome-devtools evaluate_script '() => document.title' --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
chrome-devtools evaluate_script '() => document.title' --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

Read console messages from the page

读取页面的控制台消息

chrome-devtools list_console_messages --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
chrome-devtools list_console_messages --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

List network requests since page load

列出页面加载后的网络请求

chrome-devtools list_network_requests --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
undefined
chrome-devtools list_network_requests --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"
undefined

Recipes

操作示例

Smoke-check a deployed web app

冒烟测试已部署的Web应用

bash
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"
If 
console_messages
contains any 
level: "error"
entries, surface them — they are usually the root cause of "the page looks broken" reports.
bash
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"
的条目，请向用户反馈——这些通常是“页面显示异常”问题的根本原因。

Drive a login form

驱动登录表单

bash
chrome-devtools navigate_page "https://app.example.com/login" --remote "$URL"
chrome-devtools take_snapshot --remote "$URL" --output-format json > /tmp/snap.json
bash
chrome-devtools navigate_page "https://app.example.com/login" --remote "$URL"
chrome-devtools take_snapshot --remote "$URL" --output-format json > /tmp/snap.json

Find the uid of the email input + password input + submit button from /tmp/snap.json

从/tmp/snap.json中找到邮箱输入框、密码输入框和提交按钮的uid

chrome-devtools fill "<email-uid>" "$LOGIN_EMAIL" --remote "$URL" chrome-devtools fill "<password-uid>" "$LOGIN_PASSWORD" --remote "$URL" chrome-devtools click "<submit-uid>" --remote "$URL"
undefined
chrome-devtools fill "<email-uid>" "$LOGIN_EMAIL" --remote "$URL" chrome-devtools fill "<password-uid>" "$LOGIN_PASSWORD" --remote "$URL" chrome-devtools click "<submit-uid>" --remote "$URL"
undefined

Capture a CrUX-style trace

捕获CrUX风格的性能追踪数据

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

Output discipline

输出规范

  • Always print the URL of the page you navigated to so the user knows which tab they're looking at.
  • For screenshots, print the path of the saved file (
    Saved to /tmp/<uuid>.png.
    ) — the CLI already writes that line on stdout.
  • For 
    evaluate_script
    , prefer 
    --output-format json
    and forward only the relevant field instead of dumping the whole structuredContent envelope.
  • If the user asks "what's on the page", prefer 
    take_snapshot
    over 
    take_screenshot
    — the snapshot is text and cheaper to reason over.
  • 始终输出你导航到的页面URL，让用户清楚当前操作的标签页。
  • 截图完成后，输出保存的文件路径（如
    Saved to /tmp/<uuid>.png.
    ）——CLI会自动在标准输出中打印该信息。
  • 执行
    evaluate_script
    时，优先使用
    --output-format json
    参数，仅转发相关字段而非完整的structuredContent信封结构。
  • 如果用户询问“页面上有什么”，优先使用
    take_snapshot
    而非
    take_screenshot
    ——快照是文本格式，更便于分析。

Failure modes

故障排查

SymptomCauseFix
Failed to reach remote
DNS, Tailscale offline, or wrong URL
tailscale status
on the local box; verify 
--remote
URL
Streamable HTTP error: ... 404 Session not found
Server restarted; sticky id was stale. Retried once internally — if you see this it means the retry also 404'd
chrome-devtools stop --remote $URL
to wipe the sticky pointer, then retry the command
TLS verify error (
UNABLE_TO_VERIFY_LEAF_SIGNATURE
, 
SELF_SIGNED_CERT_IN_CHAIN
)		Server uses a self-signed cert (no Tailscale-issued cert)Add 
--insecure
or 
export CHROME_DEVTOOLS_MCP_REMOTE_INSECURE=1
Bad Request: Mcp-Session-Id header is required
Local cache directory was wiped mid-sessionFirst call after the wipe will mint a fresh session; just retry
Hangs on first call after a long idleServer idle reaper closed the sessionSame fix as the 404 row — 
stop
then retry
症状原因解决方法
Failed to reach remote
DNS解析失败、Tailscale离线或URL错误在本地执行
tailscale status
；验证
--remote
参数中的URL是否正确
Streamable HTTP error: ... 404 Session not found
服务器重启，粘性会话ID失效。已自动重试一次——出现此提示说明重试也失败了执行
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
命令后重试

Don'ts

注意事项

  • Don't loop 
    navigate_page
    to "wait for the page to load" — use 
    wait_for
    with a text selector instead.
  • Don't 
    take_screenshot
    for every step in a chain — the user almost always wants one final screenshot, not five intermediate ones.
  • Don't pass 
    --insecure
    for a hosted endpoint with a real cert. It silently disables TLS for the whole CLI process.
  • Don't try to 
    start
    a server with 
    --remote
    — that subcommand only manages local daemons.
  • 不要通过循环调用
    navigate_page
    来“等待页面加载完成”——应使用
    wait_for
    配合文本选择器。
  • 不要在链式操作的每一步都调用
    take_screenshot
    ——用户通常只需要最终的一张截图，而非中间过程的多张截图。
  • 不要对拥有有效证书的托管端点使用
    --insecure
    参数——这会静默禁用整个CLI进程的TLS验证。
  • 不要尝试使用
    --remote
    参数执行
    start
    命令——该子命令仅用于管理本地守护进程。