設定

Matthias Rohmer
José Luis Zapata

您可以設定代理專用 Chrome 開發人員工具，自訂與瀏覽器的互動方式、啟用的工具，以及處理資料的方式。

如要設定伺服器，請在 Model Context Protocol (MCP) 用戶端設定檔的 args 陣列中傳遞指令列旗標。這通常是 config.json 檔案。

舉例來說，如要在無頭模式下執行 Chrome 並使用 Canary 版本，請使用下列設定：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--headless",
        "--channel=canary"
      ]
    }
  }
}

常見設定情境

以下情境說明設定代理專用 Chrome 開發人員工具的常見方式。

以無頭模式執行

如要在沒有可見瀏覽器視窗的情況下執行背景工作，請以無頭 (無 UI) 模式執行 Chrome。在伺服器引數中加入 --headless 旗標。

連線至現有的瀏覽器工作階段

根據預設，代理專用開發人員工具會啟動新的 Chrome 執行個體。不過，您可以將代理連結至現有的瀏覽器工作階段。如果服務專員需要調查您已啟動的工作階段 (例如您已登入)，這項功能就非常實用。

您可以透過下列兩種方式連線至現有工作階段：

自動連線 (Chrome 144 以上版本)

如果使用 --autoConnect 旗標，MCP 伺服器會自動連線至執行中的 Chrome 執行個體。

  1. 在執行中的 Chrome 瀏覽器中前往 chrome://inspect/#remote-debugging，然後啟用「遠端偵錯」。
  2. 將 --autoConnect 新增至 MCP 設定： json "args": ["chrome-devtools-mcp@latest", "--autoConnect"]
  3. 代理程式嘗試連線時，Chrome 會顯示對話方塊，要求授予權限。按一下「允許」。

手動連線

如果無法使用 --autoConnect (例如在沙箱環境中)，可以手動啟動 Chrome 並指定偵錯通訊埠，然後使用 --browser-url 連線。

  1. 從終端機啟動 Chrome，並啟用遠端偵錯和自訂使用者資料目錄。
    • macOS： shell /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
    • Windows： shell start chrome --remote-debugging-port=9222 --user-data-dir=%TEMP%\chrome-profile-stable
    • Linux： shell google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
  2. 將代理程式設為連線至這個通訊埠：json "args": ["chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]

允許存取暫時目錄以外的檔案

讀取或寫入檔案的工具 (例如儲存螢幕截圖、追蹤或載入擴充功能) 只能存取已設定工作區根目錄中的路徑。伺服器會使用 MCP 用戶端透過 MCP 根目錄功能提供的根目錄，以及您透過 --filesystemRoot (別名 --workspace) 傳遞的任何目錄。如果用戶端未提供根目錄，且您未設定 --filesystemRoot，則檔案存取權僅限於 OS 暫存目錄。其他路徑的要求會失敗，並顯示 Access denied: ... is not within any of the configured workspace roots 錯誤。

如要允許存取專案目錄，請在伺服器引數中新增 --filesystemRoot。您可以重複使用這個標記，允許多個目錄：

"args": ["chrome-devtools-mcp@latest", "--filesystemRoot=/path/to/project"]

設定選項參考資料

以下各節列出可用的設定旗標。如需最新選項和更新，請參閱 Chrome 開發人員工具 MCP GitHub 存放區。

連線選項

使用這些選項，設定伺服器連線至 Chrome 的方式。

檢舉 類型 預設 說明
--autoConnect 或 --auto-connect 布林值 false 自動連線至在本機執行的 Chrome (144 以上版本) 執行個體。必須使用 chrome://inspect/#remote-debugging 啟用遠端偵錯功能。
--browserUrl 或 --browser-url
-u		 字串 false 連線至執行中且可偵錯的 Chrome 執行個體 (例如 http://127.0.0.1:9222)。
--wsEndpoint 或 --ws-endpoint
-w		 字串 false 用於連線至執行中 Chrome 執行個體的 WebSocket 端點 (例如 ws://127.0.0.1:9222/devtools/browser/<id>)。可做為 --browserUrl 的替代方案。
--wsHeaders 或 --ws-headers 字串 false WebSocket 連線的自訂標頭，採用 JSON 格式 (例如 '{"Authorization":"Bearer token"}')。僅適用於 --wsEndpoint。

瀏覽器啟動選項

MCP 伺服器啟動 Chrome 時，會套用這些選項。

檢舉 類型 預設 說明
--headless 布林值 false 以無頭 (無 UI) 模式執行 Chrome。
--channel 字串 stable 指定要使用的 Chrome 版本。選項：canary、dev、beta 和 stable。
--executablePath 或 --executable-path
-e		 字串 false 自訂 Chrome 執行檔的路徑。
--userDataDir 或 --user-data-dir 字串 查看說明 使用者資料目錄的路徑。預設值為 $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE。
--isolated 布林值 false 建立暫時的使用者資料目錄，並在瀏覽器關閉時自動清理。
--viewport 字串 false 初始可視區域大小 (例如 1280x720)。在無頭模式下，大小上限為 3840x2160。
--proxyServer 或 --proxy-server 字串 false 傳遞至 Chrome 的 Proxy 伺服器設定。
--chromeArg 或 --chrome-arg 陣列 false 要傳遞至 Chrome 的其他引數。
--ignoreDefaultChromeArg 或 --ignore-default-chrome-arg 陣列 false 明確停用 Chrome 的預設引數。

安全性與隱私權選項

使用這些選項管理安全性設定和資料隱私權。

檢舉 類型 預設 說明
--acceptInsecureCerts 或 --accept-insecure-certs 布林值 false 忽略與自行簽署和過期憑證相關的錯誤。請謹慎使用。
--blockedUrlPattern 或 --blocked-url-pattern 陣列 false 封鎖特定網址模式 (使用 URLPattern)，限制網路存取權。封鎖導覽和子資源。
--allowedUrlPattern 或 --allowed-url-pattern 陣列 false 僅允許指定的網址模式，藉此限制網路存取權。必須使用 Chrome 149 以上版本。
--redactNetworkHeaders 或 --redact-network-headers 布林值 false 先遮蓋機密網路標頭，再傳回用戶端。
--usageStatistics 或 --usage-statistics 布林值 true 啟用使用統計資料收集功能，以利改善工具。您也可以使用 CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS 或 CI 環境變數停用這項功能。
--performanceCrux 或 --performance-crux 布林值 true 將效能追蹤記錄中的網址傳送至 Google CrUX API，以擷取實際使用者體驗資料。
--javascriptEvaluation 或 --javascript-evaluation 布林值 true 設為 false 即可停用 JavaScript 執行作業。停用後，系統會停用指令碼評估工具、關閉 navigate_page 的 initScript 參數，且不允許前往 javascript:、data: 或 vbscript: 網址。
--filesystemRoot 或 --filesystem-root
--workspace		 陣列 OS 暫存目錄 除了 MCP 用戶端提供的根目錄外，檔案存取工具還可使用的目錄。可指定多次。請參閱「允許存取暫存目錄以外的檔案」。
--allowUnrestrictedPaths 或 --allow-unrestricted-paths 布林值 false 已淘汰：請改用 --workspace=/。停用 MCP 用戶端未提供根目錄時適用的路徑限制。

功能類別

您可以使用這些旗標啟用或停用工具群組。

檢舉 類型 預設 說明
--categoryInput 或 --category-input 布林值 true 啟用輸入相關工具。
--categoryNavigation 或 --category-navigation 布林值 true 啟用導覽相關工具。
--categoryEmulation 或 --category-emulation 布林值 true 啟用與模擬相關的工具。
--categoryNetwork 或 --category-network 布林值 true 啟用網路相關工具。
--categoryPerformance 或 --category-performance 布林值 true 啟用與效能相關的工具。
--categoryDebugging 或 --category-debugging 布林值 true 啟用與偵錯相關的工具。
--categoryMemory 或 --category-memory 布林值 true 啟用記憶體相關工具。
--categoryExtensions 或 --category-extensions 布林值 false 啟用擴充功能相關工具。僅支援管道連線。
--categoryPwa 或 --category-pwa 布林值 false 啟用自動化漸進式網頁應用程式的工具 (安裝、啟動、解除安裝和 OS 狀態)。僅支援管道連線。
--categoryExperimentalThirdParty 或 --category-experimental-third-party 布林值 false 啟用受檢查頁面公開的第三方開發人員工具。
--categoryExperimentalWebmcp 或 --category-experimental-webmcp 布林值 false 啟用 WebMCP 工具偵錯功能。必須使用 Chrome 149 以上版本，並啟用 WebMCP 功能。
--memoryDebugging 或 --memory-debugging 布林值 false 啟用記憶體偵錯工具。

螢幕截圖選項

使用這些選項，自訂代理程式擷取螢幕截圖的方式。

檢舉 類型 預設 說明
--screenshotFormat 或 --screenshot-format 字串 false 覆寫預設輸出格式 (png)。選項：jpeg、png 和 webp。jpeg 和 webp 格式較小，有助於縮減 AI 對話中的脈絡大小。
--screenshotQuality 或 --screenshot-quality 數字 false 覆寫 jpeg 和 webp 的壓縮品質 (0-100)。
--screenshotMaxWidth 或 --screenshot-max-width 數字 false 寬度上限 (以像素為單位)。較大的螢幕截圖會縮小。
--screenshotMaxHeight 或 --screenshot-max-height 數字 false 高度上限 (以像素為單位)。較大的螢幕截圖會縮小。

實驗選項

使用這些選項，即可啟用開發中的實驗功能。

檢舉 類型 預設 說明
--experimentalDevtools 或 --experimental-devtools 布林值 false 啟用 DevTools 目標的自動化功能。
--experimentalVision 或 --experimental-vision 布林值 false 啟用以座標為基礎的工具 (例如 click_at)。通常需要電腦使用模型，才能透過查看螢幕截圖產生準確的座標。
--experimentalStructuredContent 或 --experimental-structured-content 布林值 false 輸出結構化格式的內容。
--experimentalIncludeAllPages 或 --experimental-include-all-pages 布林值 false 包括各種網頁 (例如 Webview 和背景網頁)。
--experimentalScreencast 或 --experimental-screencast 布林值 false 公開螢幕側錄工具 (PATH 中須有 ffmpeg)。
--experimentalFfmpegPath 或 --experimental-ffmpeg-path 字串 false ffmpeg 執行檔的路徑。
--experimentalScreencastFps 或 --experimental-screencast-fps 數字 false 螢幕側錄的每秒影格數。如果頁面產生影格的速度快於 ffmpeg 編碼的速度，降低這個值可減輕記憶體壓力。

其他選項

使用這些選項設定記錄、頁面轉送和來源對應，或啟用簡化工具組。

檢舉 類型 預設 說明
--slim 布林值 false 提供三個精簡工具 (導覽、指令碼執行和螢幕截圖)。適合用於基本瀏覽器工作。
--pageIdRouting 或 --page-id-routing 布林值 true 需要網頁範圍工具上的 pageId，並依網頁 ID 傳送要求，這對並行代理程式工作階段很有幫助。使用 --no-page-id-routing 停用。
--sourceMaps 或 --source-maps 布林值 true 在開發人員工具中啟用來源對應。使用 --no-source-maps 停用。
--logFile 或 --log-file 字串 false 要寫入偵錯記錄檔的檔案路徑。將 NODE_DEBUG 環境變數設為 *，即可啟用詳細記錄。
--config 字串 false JSON 設定檔的路徑。

環境變數

您也可以使用下列環境變數設定伺服器：

  • CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS：如果設定這個值，系統會停用使用統計資料收集功能 (等同於 --no-usage-statistics)。
  • CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS：如果設定，系統會停用定期檢查更新。
  • CI：如果設定，則會停用使用統計資料收集功能。
  • NODE_DEBUG：設為 *，啟用詳細偵錯記錄檔 (與 --logFile 搭配使用)。