chrome-devtools-cli

chrome-devtools-mcp CLI 讓你能夠直接在終端機中與瀏覽器互動。

環境設定

註：若這是你第一次使用此 CLI，請參閱 references/installation.md 進行設定。安裝為一次性的前置準備，不屬於日常 AI 工作流程的一部分。

AI 工作流程

1. 執行（Execute）：直接執行工具（例如 chrome-devtools list_pages）。背景伺服器會自動啟動；每次使用前無需執行 start/status/stop。
2. 檢視（Inspect）：使用 take_snapshot 取得元素的 <uid>。
3. 操作（Act）：使用 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" # 關閉對話方塊並輸入提示文字
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 # 開始錄製效能追蹤
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 快照

網路

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 Requests）

除錯與檢視

chrome-devtools evaluate_script "() => document.title" # 在頁面上執行 JavaScript 函式
chrome-devtools evaluate_script "(a) => a.innerText" --args 1_4 # 傳入 UID 參數並執行 JavaScript
chrome-devtools get_console_message 1 # 依 ID 取得主控台（Console）訊息
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 # 包含保留的主控台訊息
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 時帶入對應的旗標。

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