chrome-devtools-cli

chrome-devtools-mcp CLI 允许你在终端中直接与浏览器交互。

环境配置

注意：如果这是你第一次使用该 CLI，请参阅 references/installation.md 完成配置。安装属于一次性前置准备工作，不属于日常 AI 工作流的一部分。

AI 工作流

1. 执行：直接运行工具（例如 chrome-devtools list_pages）。后台服务器会自动隐式启动；无需在每次使用前手动运行 start/status/stop。
2. 审查：使用 take_snapshot 获取元素的 <uid>。
3. 操作：使用 click、fill 等指令。状态会在后续命令间自动保持。

快照示例：

uid=1_0 RootWebArea "Example Domain" url="https://example.com/"
  uid=1_1 heading "Example Domain" level="1"

命令用法

chrome-devtools <tool> [arguments] [flags]

在任意命令后加上 --help 即可查看帮助。默认输出格式为 Markdown，若需要 JSON 格式可加上 --output-format=json。

输入自动化（从快照中获取 <uid>）

chrome-devtools take_snapshot --help # 命令帮助信息，适用于任何命令
chrome-devtools take_snapshot # 获取页面的文本快照，用于提取元素的 UID
chrome-devtools click "id" # 点击指定的元素
chrome-devtools click "id" --dblClick true --includeSnapshot true # 双击元素并返回快照
chrome-devtools drag "src" "dst" # 将一个元素拖拽到另一个元素上
chrome-devtools drag "src" "dst" --includeSnapshot true # 拖拽元素并返回快照
chrome-devtools fill "id" "text" # 在输入框中输入文本或选择选项
chrome-devtools fill "id" "text" --includeSnapshot true # 填充元素并返回快照
chrome-devtools handle_dialog accept # 确认/接受浏览器弹窗对话框
chrome-devtools handle_dialog dismiss --promptText "hi" # 取消对话框并带有 prompt 文本
chrome-devtools hover "id" # 悬停在指定元素上
chrome-devtools hover "id" --includeSnapshot true # 悬停在元素上并返回快照
chrome-devtools press_key "Enter" # 按下某个按键或组合键
chrome-devtools press_key "Control+A" --includeSnapshot true # 按下按键并返回快照
chrome-devtools type_text "hello" # 使用键盘向当前聚焦的输入框输入文本
chrome-devtools type_text "hello" --submitKey "Enter" # 输入文本并按下提交键
chrome-devtools upload_file "id" "file.txt" # 通过指定元素上传文件
chrome-devtools upload_file "id" "file.txt" --includeSnapshot true # 上传文件并返回快照

页面导航

chrome-devtools close_page 1 # 根据索引关闭页面
chrome-devtools list_pages # 获取浏览器中所有已打开页面的列表
chrome-devtools navigate_page --url "https://example.com" # 将当前选中的页面导航至指定 URL
chrome-devtools navigate_page --type "reload" --ignoreCache true # 忽略缓存刷新页面
chrome-devtools navigate_page --url "https://example.com" --timeout 5000 # 设置超时时间并进行导航
chrome-devtools navigate_page --handleBeforeUnload "accept" # 处理 beforeunload 离开提示弹窗
chrome-devtools navigate_page --type "back" --initScript "foo()" # 返回上一页并执行初始化脚本
chrome-devtools new_page "https://example.com" # 新建页面
chrome-devtools new_page "https://example.com" --background true --timeout 5000 # 在后台新建页面并设置超时
chrome-devtools new_page "https://example.com" --isolatedContext "ctx" # 使用隔离上下文新建页面
chrome-devtools select_page 1 # 选择页面作为后续工具调用的上下文
chrome-devtools select_page 1 --bringToFront true # 选择页面并将其置于最前

环境模拟

chrome-devtools emulate --networkConditions "Offline" # 模拟网络状况
chrome-devtools emulate --cpuThrottlingRate 4 --geolocation "0x0" # 模拟 CPU 限速与地理位置
chrome-devtools emulate --colorScheme "dark" --viewport "1920x1080" # 模拟配色方案与视口大小
chrome-devtools emulate --userAgent "Mozilla/5.0..." # 模拟 User Agent
chrome-devtools resize_page 1920 1080 # 调整当前选中页面的窗口大小

性能分析

chrome-devtools performance_analyze_insight "1" "LCPBreakdown" # 获取特定性能分析洞察（Performance Insight）的详细信息
chrome-devtools performance_start_trace true false # 开始录制性能追踪（Performance Trace）
chrome-devtools performance_start_trace true true --filePath t.gz # 开始追踪并将结果保存至文件
chrome-devtools performance_stop_trace # 停止当前激活的性能追踪
chrome-devtools performance_stop_trace --filePath "t.json" # 停止追踪并将结果保存至文件
chrome-devtools take_memory_snapshot "./snap.heapsnapshot" # 捕获内存堆快照（Heap Snapshot）

网络请求

chrome-devtools get_network_request # 获取当前选中的网络请求
chrome-devtools get_network_request --reqid 1 --requestFilePath req.md # 根据 ID 获取网络请求并保存至文件
chrome-devtools get_network_request --responseFilePath res.md # 保存响应体（Response Body）至文件
chrome-devtools list_network_requests # 列出所有网络请求
chrome-devtools list_network_requests --pageSize 50 --pageIdx 0 # 分页列出网络请求
chrome-devtools list_network_requests --resourceTypes Fetch # 按资源类型过滤请求
chrome-devtools list_network_requests --includePreservedRequests true # 包含保留的（Preserved）请求

调试与审查

chrome-devtools evaluate_script "() => document.title" # 在页面中执行 JavaScript 函数
chrome-devtools evaluate_script "(a) => a.innerText" --args 1_4 # 传入 UID 参数执行 JS
chrome-devtools get_console_message 1 # 根据 ID 获取控制台消息
chrome-devtools lighthouse_audit --mode "navigation" # 针对页面导航运行 Lighthouse 审查
chrome-devtools lighthouse_audit --mode "snapshot" --device "mobile" # 针对移动端页面快照运行 Lighthouse 审查
chrome-devtools lighthouse_audit --outputDirPath ./out # 运行 Lighthouse 审查并保存报告
chrome-devtools list_console_messages # 列出所有控制台消息
chrome-devtools list_console_messages --pageSize 20 --pageIdx 1 # 分页列出控制台消息
chrome-devtools list_console_messages --types error --types info # 按类型过滤控制台消息
chrome-devtools list_console_messages --includePreservedMessages true # 包含保留的（Preserved）消息
chrome-devtools take_screenshot # 截取页面视口截图
chrome-devtools take_screenshot --fullPage true --format "jpeg" --quality 80 # 截取整页 JPEG 格式截图并设置质量
chrome-devtools take_screenshot --uid "id" --filePath "s.png" # 截取特定元素的截图
chrome-devtools take_snapshot # 从无障碍树（a11y tree）获取页面的文本快照
chrome-devtools take_snapshot --verbose true --filePath "s.txt" # 获取详细快照并保存至文件

浏览器扩展

chrome-devtools list_extensions # 列出浏览器中已安装的所有 Chrome 扩展
chrome-devtools install_extension "/path/to/extension" # 从指定路径安装 Chrome 扩展
chrome-devtools uninstall_extension "extension_id" # 根据 ID 卸载 Chrome 扩展
chrome-devtools reload_extension "extension_id" # 根据 ID 重新加载未打包的 Chrome 扩展
chrome-devtools trigger_extension_action "extension_id" # 根据 ID 触发扩展的默认操作

实验性功能

实验性工具默认处于禁用状态。可以在启动 start 时使用对应的 Flag 来开启。

chrome-devtools click_at 100 200 # 在指定坐标处点击（需要开启 --experimentalVision=true）
chrome-devtools screencast_start # 开始录屏（需要开启 --experimentalScreencast=true 且安装了 ffmpeg）
chrome-devtools screencast_stop # 停止当前录屏
chrome-devtools list_webmcp_tools # 列出所有 WebMCP 工具（需要开启 --categoryExperimentalWebmcp=true）

服务管理

chrome-devtools start   # 启动或重启 chrome-devtools-mcp
chrome-devtools status  # 检查 chrome-devtools-mcp 的运行状态
chrome-devtools stop    # 停止运行中的 chrome-devtools-mcp