Chrome Devtools MCP

🚀 Chrome DevTools MCP

Chrome DevTools MCP 是一個模型上下文協議（MCP）服務器，它通過 MCP 提供與 Chrome 開發者工具協議的集成。藉助該服務器，你可以連接到 Chrome 的開發者工具，對 Web 應用程序進行調試。

支持作為 Claude 桌面擴展（.dxt）使用，輕鬆一鍵安裝！

🚀 快速開始

在 Claude 桌面版中安裝此工具後，你就可以開始調試任何 Web 應用程序：

調試你的 Web 應用程序

一步設置（推薦）：

start_chrome_and_connect("localhost:3000")

將 localhost:3000 替換為你的應用程序的 URL

如果無法自動找到 Chrome：

start_chrome_and_connect("localhost:3000", chrome_path="/path/to/chrome")

使用 chrome_path 參數指定自定義的 Chrome 位置

此命令將執行以下操作：

• 啟動啟用調試功能的 Chrome
• 導航到你的應用程序
• 將 MCP 服務器連接到 Chrome

手動設置（如果你更喜歡分步操作）：

start_chrome()
navigate_to_url("localhost:3000")
connect_to_browser()

開始調試

連接成功後，你可以使用以下命令：

• get_network_requests() - 查看 HTTP 流量
• get_console_error_summary() - 分析 JavaScript 錯誤
• inspect_console_object("window") - 檢查任何 JavaScript 對象

✨ 主要特性

• 網絡監控：通過過濾選項捕獲和分析 HTTP 請求/響應
• 控制檯集成：讀取瀏覽器控制檯日誌、分析錯誤並執行 JavaScript
• 性能指標：獲取計時數據、資源加載情況和內存利用率
• 頁面檢查：獲取 DOM 信息、頁面指標並支持多框架
• 存儲訪問：讀取 cookie、localStorage 和 sessionStorage
• 即時監控：即時跟蹤控制檯輸出
• 對象檢查：檢查 JavaScript 對象和變量

📦 安裝指南

選項 1：Claude 桌面擴展（最簡單）

下載預構建的擴展：

1. 從 Releases 下載最新的 .dxt 文件。
2. 打開 Claude 桌面版。
3. 轉到“擴展”並安裝下載的 .dxt 文件。
4. 如果需要，在擴展設置中配置 Chrome 路徑。

該擴展包含所有依賴項，可立即使用！

選項 2：MCP CLI（高級）

快速安裝（最常見）：

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp
mcp install server.py -n "Chrome DevTools MCP" --with-editable .

注意：mcp 命令是 Python MCP SDK 的一部分。如果尚未安裝，請使用 pip install mcp 進行安裝。

所有安裝選項：

# 克隆倉庫
git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp

# --with-editable 標誌使用 pyproject.toml 安裝依賴項

# 基本安裝，使用本地依賴項
mcp install server.py --with-editable .

# 使用自定義名稱安裝
mcp install server.py -n "Chrome DevTools MCP" --with-editable .

# 使用環境變量安裝
mcp install server.py -n "Chrome DevTools MCP" --with-editable . -v CHROME_DEBUG_PORT=9222

# 如果需要，安裝額外的包
mcp install server.py -n "Chrome DevTools MCP" --with-editable . --with websockets --with aiohttp

# 使用環境文件安裝（先將 .env.example 複製到 .env）
cp .env.example .env
# 使用你的設置編輯 .env
mcp install server.py -n "Chrome DevTools MCP" --with-editable . -f .env

選項 3：Claude 代碼集成

對於 Claude 代碼 CLI 用戶：

1. 克隆此倉庫

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp

2. 使用 UV 安裝依賴項（創建虛擬環境）

uv sync  # 創建 .venv 並安裝依賴項

3. 使用 Claude CLI 並使用絕對路徑添加 MCP 服務器

重要提示：Claude 代碼需要 Python 解釋器和服務器腳本的絕對路徑才能正常工作。

推薦使用絕對路徑進行設置：

# 獲取絕對路徑
SERVER_PATH="$(pwd)/server.py"
PYTHON_PATH="$(pwd)/.venv/bin/python"

# 使用絕對路徑添加服務器
claude mcp add chrome-devtools "$PYTHON_PATH" "$SERVER_PATH" -e CHROME_DEBUG_PORT=9222

替代方法：使用系統 Python（如果依賴項已全局安裝）：

# 僅當你已全局安裝依賴項時使用
claude mcp add chrome-devtools python "$(pwd)/server.py" -e CHROME_DEBUG_PORT=9222

使用自定義作用域：

# 添加到用戶作用域（在所有項目中可用）
claude mcp add chrome-devtools "$(pwd)/.venv/bin/python" "$(pwd)/server.py" -s user -e CHROME_DEBUG_PORT=9222

# 添加到項目作用域（僅適用於此項目）
claude mcp add chrome-devtools "$(pwd)/.venv/bin/python" "$(pwd)/server.py" -s project -e CHROME_DEBUG_PORT=9222

4. 驗證安裝

# 列出已配置的 MCP 服務器
claude mcp list

# 獲取服務器的詳細信息（檢查路徑是否為絕對路徑）
claude mcp get chrome-devtools

# 輸出應顯示絕對路徑，例如：
# Command: /Users/you/chrome-devtools-mcp/.venv/bin/python
# Args: ["/Users/you/chrome-devtools-mcp/server.py"]

常見路徑問題及解決方案：

• 問題：“python: command not found” 或 “server.py not found”
  • 解決方案：使用上述所示的絕對路徑
• 問題：服務器啟動時出現 “ModuleNotFoundError”
  • 解決方案：使用已安裝依賴項的虛擬環境 Python 解釋器
• 問題：服務器未啟動或顯示為斷開連接
  • 解決方案：手動測試命令：/path/to/.venv/bin/python /path/to/server.py

選項 4：手動進行 Claude 桌面設置

1. 克隆此倉庫

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp

2. 安裝依賴項

使用 uv（推薦）：

uv sync

使用 pip：

pip install -r requirements.txt

3. 添加到 Claude 桌面配置

編輯你的 Claude 桌面配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "python",
      "args": ["/absolute/path/to/chrome-devtools-mcp/server.py"],
      "env": {
        "CHROME_DEBUG_PORT": "9222"
      }
    }
  }
}

4. 重啟 Claude 桌面

驗證安裝

安裝完成後（使用任何一種方法），驗證服務器是否可用：

1. 打開 Claude 桌面版。
2. 在對話中查找 MCP 工具。
3. 嘗試執行一個簡單的命令：get_connection_status()

替代 MCP 客戶端

對於其他 MCP 客戶端，直接運行服務器：

python server.py

💻 使用示例

基礎用法

# 一鍵啟動 Chrome 並連接到應用程序
start_chrome_and_connect("localhost:3000")

高級用法

# 手動分步啟動 Chrome、導航到應用程序並連接到瀏覽器
start_chrome()
navigate_to_url("localhost:3000")
connect_to_browser()

📚 詳細文檔

可用的 MCP 工具

Chrome 管理

• start_chrome(port?, url?, headless?, chrome_path?, auto_connect?) - 啟動具有遠程調試功能的 Chrome，並可選擇自動連接
• start_chrome_and_connect(url, port?, headless?, chrome_path?) - 一步完成啟動 Chrome、連接並導航到指定 URL
• connect_to_browser(port?) - 連接到現有的 Chrome 實例
• navigate_to_url(url) - 導航到指定的 URL
• disconnect_from_browser() - 斷開與瀏覽器的連接
• get_connection_status() - 檢查連接狀態

網絡監控

• get_network_requests(filter_domain?, filter_status?, limit?) - 獲取經過過濾的網絡請求
• get_network_response(request_id) - 獲取詳細的響應數據，包括響應體

控制檯工具

• get_console_logs(level?, limit?) - 獲取瀏覽器控制檯日誌
• get_console_error_summary() - 獲取組織好的錯誤和警告摘要
• execute_javascript(code) - 在瀏覽器上下文中執行 JavaScript
• clear_console() - 清除瀏覽器控制檯
• inspect_console_object(expression) - 深入檢查任何 JavaScript 對象
• monitor_console_live(duration_seconds) - 即時監控控制檯輸出

頁面分析

• get_page_info() - 獲取全面的頁面指標和性能數據
• evaluate_in_all_frames(code) - 在所有框架/iframe 中執行 JavaScript
• get_performance_metrics() - 獲取詳細的性能指標和資源計時數據

存儲與數據

• get_storage_usage_and_quota(origin) - 獲取存儲使用情況和配額信息
• clear_storage_for_origin(origin, storage_types?) - 按類型和來源清除存儲
• get_all_cookies() - 獲取所有瀏覽器 cookie
• clear_all_cookies() - 清除所有瀏覽器 cookie
• set_cookie(name, value, domain, path?, expires?, http_only?, secure?, same_site?) - 設置一個 cookie
• get_cookies(domain?) - 獲取經過可選域名過濾的瀏覽器 cookie
• get_storage_key_for_frame(frame_id) - 獲取特定框架的存儲鍵
• track_cache_storage(origin, enable?) - 啟用/禁用緩存存儲跟蹤
• track_indexeddb(origin, enable?) - 啟用/禁用 IndexedDB 跟蹤
• override_storage_quota(origin, quota_size_mb?) - 覆蓋存儲配額

使用案例

調試 Web 應用程序中的 API 調用

當你的 Web 應用程序進行 API 調用時，如果調用失敗或返回意外數據：

簡單設置：使用一步命令啟動 Chrome 並導航到你的應用程序：

示例工作流程：

你：“我需要調試運行在 localhost:3000 上的 React 應用程序”
Claude：我將啟動啟用調試功能的 Chrome 並導航到你的應用程序。

start_chrome_and_connect("localhost:3000")

完美！Chrome 現已啟動並啟用調試功能，且已連接到你的應用程序。讓我檢查是否有失敗的網絡請求：

get_network_requests(filter_status=500)

我發現有 3 個請求你的 API 的請求失敗了。讓我獲取第一個請求的詳細信息：

get_network_response("request-123")

手動設置（如果你更喜歡手動操作）：

1. 啟動 Chrome：使用 start_chrome()
2. 導航到你的應用程序：使用 navigate_to_url("localhost:3000")
3. 連接：使用 connect_to_browser()
4. 監控網絡流量：使用 get_network_requests() 查看所有 API 調用

檢查 JavaScript 控制檯錯誤

當你的 Web 應用程序出現 JavaScript 錯誤或意外行為時：

1. 在已連接的 Chrome 實例中導航到你的應用程序
2. 檢查控制檯錯誤：使用 get_console_error_summary() 查看所有錯誤
3. 監控即時錯誤：使用 monitor_console_live(10) 在你與應用程序交互時監控新的錯誤
4. 檢查變量：使用 inspect_console_object("myVariable") 檢查應用程序的狀態

示例工作流程：

你：“我的 React 組件更新不正常”
Claude：讓我檢查 JavaScript 控制檯是否有錯誤。

get_console_error_summary()

我發現有 2 個 JavaScript 錯誤。讓我在你與組件交互時監控控制檯：

monitor_console_live(15)

現在嘗試點擊不正常工作的組件。我會監控是否有新的錯誤或警告。

性能調試

當你的 Web 應用程序加載緩慢或使用過多內存時：

1. 在已連接的瀏覽器中加載你的應用程序
2. 檢查頁面指標：使用 get_page_info() 查看加載時間和資源數量
3. 分析性能：使用 get_performance_metrics() 查看詳細的計時數據
4. 監控內存使用情況：在性能指標中檢查內存信息

示例工作流程：

你：“我的應用程序加載時間過長”
Claude：讓我分析你的應用程序的性能。

get_page_info()

我發現你的頁面有 47 個腳本，加載時間為 3.2 秒。讓我獲取更詳細的性能數據：

get_performance_metrics()

主要的瓶頸是初始 JavaScript 包，大小為 2.1MB。DOM 處理也需要 800ms。

調試身份驗證問題

當登錄或會話管理出現問題時：

1. 導航到你的登錄頁面
2. 檢查 cookie：使用 get_cookies() 查看身份驗證 cookie
3. 在登錄過程中監控網絡：在登錄過程中使用 monitor_console_live() 和 get_network_requests()
4. 檢查存儲的數據：使用 JavaScript 執行來檢查 localStorage/sessionStorage

示例工作流程：

你：“用戶無法保持登錄狀態”
Claude：讓我檢查身份驗證設置。

get_cookies()

我發現身份驗證 cookie 存在。讓我通過監控網絡來檢查登錄過程中發生了什麼：

get_network_requests(filter_domain="your-api.com")

我注意到登錄請求返回了 200 狀態碼，但沒有 Set-Cookie 頭。讓我也檢查一下 localStorage：

execute_javascript("Object.keys(localStorage)")

DOM 元素檢查

• get_document(depth?, pierce?) - 檢索 DOM 文檔結構
• query_selector(node_id, selector) - 通過 CSS 選擇器查找單個元素
• query_selector_all(node_id, selector) - 通過 CSS 選擇器查找多個元素
• get_element_attributes(node_id) - 獲取元素的所有屬性
• get_element_outer_html(node_id) - 獲取元素的外部 HTML
• get_element_box_model(node_id) - 獲取元素的佈局信息
• describe_element(node_id, depth?) - 獲取元素的詳細描述
• get_element_at_position(x, y) - 獲取屏幕指定位置的元素
• search_elements(query) - 通過文本/屬性搜索 DOM 元素
• focus_element(node_id) - 聚焦 DOM 元素

CSS 樣式分析

• get_computed_styles(node_id) - 獲取計算後的 CSS 樣式
• get_inline_styles(node_id) - 獲取內聯樣式
• get_matched_styles(node_id) - 獲取與元素匹配的所有 CSS 規則
• get_stylesheet_text(stylesheet_id) - 獲取樣式表內容
• get_background_colors(node_id) - 獲取背景顏色和字體信息
• get_platform_fonts(node_id) - 獲取平臺字體信息
• get_media_queries() - 獲取所有媒體查詢
• collect_css_class_names(stylesheet_id) - 收集 CSS 類名
• start_css_coverage_tracking() - 開始 CSS 覆蓋率跟蹤
• stop_css_coverage_tracking() - 停止並獲取 CSS 覆蓋率結果

常見命令

配置

環境變量

• CHROME_DEBUG_PORT - Chrome 遠程調試端口（默認值：9222）

MCP 兼容性

• MCP 協議版本：2024 - 11 - 05
• 最低 Python 版本：3.10+
• 支持的 MCP 客戶端：Claude 桌面版，任何兼容 MCP 的客戶端
• 包管理器：uv（推薦）或 pip

使用工作流程

先決條件（你的開發環境）

• 確保你的 Web 應用程序正在運行（例如，npm run dev、python -m http.server 等）
• 記錄你的應用程序可訪問的 URL

調試會話

1. 通過 Claude 桌面版連接到你的應用程序：

   start_chrome_and_connect("localhost:3000")
   

   將其替換為你的應用程序的 URL

2. 使用 MCP 工具調試你的應用程序：

   • 監控網絡請求
   • 檢查控制檯錯誤
   • 檢查 JavaScript 對象
   • 分析性能

3. 在編輯器中修改你的代碼

4. 刷新或與你的應用程序進行交互

5. 使用即時數據繼續調試

手動連接（替代方法）

如果你更喜歡分步控制：

1. start_chrome() - 啟動具有調試功能的 Chrome
2. navigate_to_url("your-app-url") - 導航到你的應用程序
3. connect_to_browser() - 連接 MCP 服務器
4. 根據需要使用調試工具

安全注意事項

• 僅在開發環境中使用此工具。
• 切勿連接到生產環境的 Chrome 實例。
• 該服務器僅用於本地主機調試。
• 不會永久存儲任何數據，所有數據均基於會話。

故障排除

服務器在 Claude 桌面版中顯示為“已禁用”

如果服務器在 Claude 中顯示但顯示為“已禁用”，請嘗試以下步驟：

1. 檢查 Claude 桌面版日誌：

   • macOS：~/Library/Logs/Claude/mcp*.log
   • Windows：%APPDATA%/Claude/logs/mcp*.log

2. 常見修復方法：

   # 重新安裝並顯示詳細輸出
   mcp remove "Chrome DevTools MCP"
   mcp install server.py -n "Chrome DevTools MCP" --with-editable . -v CHROME_DEBUG_PORT=9222
   
   # 檢查安裝狀態
   mcp list
   
   # 手動測試服務器
   python3 server.py
   

3. 檢查依賴項：

   # 確保所有依賴項都可用
   pip install mcp websockets aiohttp
   
   # 測試導入
   python3 -c "from server import mcp; print('OK')"
   

4. 完全重啟 Claude 桌面版（退出並重新打開）

安裝問題

• 未找到 MCP CLI：從 Python MCP SDK 安裝 MCP CLI，使用 pip install mcp。
• 服務器未在 Claude 中顯示：
  • 對於 MCP CLI：運行 mcp list 以驗證服務器是否已安裝。
  • 對於手動設置：檢查 Claude 桌面版配置文件的路徑和 JSON 語法。
• 導入錯誤：
  • 對於 MCP CLI：使用 --with-editable . 安裝本地依賴項。
  • 對於手動設置：運行 pip install -r requirements.txt。
• 權限錯誤：在配置中使用絕對路徑。
• 環境變量不起作用：驗證 .env 文件的格式或 -v 標誌的語法。
• 未找到模塊：確保在安裝本地包時使用 --with-editable . 標誌。

調試步驟

步驟 1：檢查 MCP CLI 狀態

# 列出所有已安裝的服務器
mcp list

# 檢查特定服務器的狀態
mcp status "Chrome DevTools MCP"

步驟 2：手動測試服務器

# 測試服務器是否可以無錯誤啟動
python3 server.py

# 測試導入
python3 -c "from server import mcp; print(f'Server: {mcp.name}')"

步驟 3：檢查配置

對於 Claude 桌面版：

# 查看當前配置（macOS）
cat "~/Library/Application Support/Claude/claude_desktop_config.json"

# 查看當前配置（Windows）
type "%APPDATA%/Claude/claude_desktop_config.json"

對於 Claude 代碼：

# 列出已配置的 MCP 服務器
claude mcp list

# 獲取特定服務器的詳細信息
claude mcp get chrome-devtools

# 重要提示：驗證路徑是否為絕對路徑，而不是相對路徑
# 良好的輸出示例：
#   Command: /Users/you/chrome-devtools-mcp/.venv/bin/python
#   Args: ["/Users/you/chrome-devtools-mcp/server.py"]
# 不良的輸出示例：
#   Command: python
#   Args: ["server.py"]

# 測試 Claude 代碼將使用的精確命令
/path/to/.venv/bin/python /path/to/server.py

# 檢查服務器是否正常工作
claude mcp serve --help

步驟 3.5：修復路徑問題（Claude 代碼特定）

# 如果路徑是相對路徑，請移除並使用絕對路徑重新添加
claude mcp remove chrome-devtools

# 使用絕對路徑重新添加
SERVER_PATH="$(pwd)/server.py"
PYTHON_PATH="$(pwd)/.venv/bin/python"
claude mcp add chrome-devtools "$PYTHON_PATH" "$SERVER_PATH" -e CHROME_DEBUG_PORT=9222

步驟 4：如有需要，重新安裝

對於 MCP CLI：

# 徹底重新安裝
mcp remove "Chrome DevTools MCP"
mcp install server.py -n "Chrome DevTools MCP" --with-editable .

# 完全重啟 Claude 桌面版

對於 Claude 代碼：

# 移除並重新添加服務器
claude mcp remove chrome-devtools
claude mcp add chrome-devtools python server.py -e CHROME_DEBUG_PORT=9222

# 或者使用不同的作用域進行更新
claude mcp add chrome-devtools python server.py -s user -e CHROME_DEBUG_PORT=9222

常見錯誤消息

手動配置備用方案

對於 Claude 桌面版： 如果 MCP CLI 無法正常工作，請手動將以下內容添加到 Claude 桌面版配置中：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "python3",
      "args": ["/absolute/path/to/chrome-devtools-mcp/server.py"],
      "env": {
        "CHROME_DEBUG_PORT": "9222"
      }
    }
  }
}

對於 Claude 代碼： 如果 claude mcp add 命令無法正常工作，你可以使用帶有絕對路徑的 JSON 格式：

# 首先獲取絕對路徑
SERVER_PATH="$(pwd)/server.py"
PYTHON_PATH="$(pwd)/.venv/bin/python"

# 使用帶有絕對路徑的 JSON 配置添加服務器
claude mcp add-json chrome-devtools "{
  \"command\": \"$PYTHON_PATH\",
  \"args\": [\"$SERVER_PATH\"],
  \"env\": {
    \"CHROME_DEBUG_PORT\": \"9222\"
  }
}"

# 或者如果你在 Claude 桌面版中已配置成功，可以從那裡導入
claude mcp add-from-claude-desktop

Claude 代碼正確配置示例（使用絕對路徑）：

{
  "command": "/Users/you/chrome-devtools-mcp/.venv/bin/python",
  "args": ["/Users/you/chrome-devtools-mcp/server.py"],
  "env": {
    "CHROME_DEBUG_PORT": "9222"
  }
}

連接問題

• Chrome 無法啟動：當你使用 start_chrome() 時，MCP 服務器將自動啟動 Chrome。
• 無法連接：嘗試使用 get_connection_status() 檢查連接狀態。
• 工具無法正常工作：確保你已調用 connect_to_browser() 或使用了 start_chrome_and_connect()。

常見誤解

• 這不是一個 Web 服務器：MCP 服務器在 Claude 桌面版內部運行，而不是作為一個獨立的 Web 服務。
• 無需單獨安裝：一旦在 Claude 桌面版中配置完成，服務器將自動啟動。
• 你的應用程序獨立運行：此工具用於連接到你現有的 Web 應用程序，而不是運行該應用程序。

🔧 技術細節

開發與測試

本節適用於想要測試或修改 MCP 服務器本身的開發者。

開發設置

使用 uv（推薦）：

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp
uv sync

使用 pip：

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp
pip install -e ".[dev]"

代碼質量工具

# 格式化代碼
uv run ruff format .

# 代碼檢查
uv run ruff check .

# 類型檢查
uv run mypy src/

構建擴展

安裝 DXT 打包工具：

npm install -g @anthropic-ai/dxt

構建擴展：

# 快速構建
make package

# 或者手動構建
npx @anthropic-ai/dxt pack

在開發中使用 Makefile：

make help           # 顯示所有命令
make install        # 安裝依賴項
make dev            # 設置開發環境並配置預提交鉤子
make check          # 運行所有檢查（檢查、類型檢查和測試）
make pre-commit     # 手動運行預提交鉤子
make package        # 構建 .dxt 擴展
make release        # 完整的發佈構建

預提交鉤子

本項目使用預提交鉤子來確保代碼質量：

• ruff：代碼檢查和格式化
• mypy：類型檢查
• pytest：測試驗證
• MCP 驗證：服務器註冊檢查

預提交鉤子在 git commit 時自動運行，也可以使用 make pre-commit 手動運行。

📄 許可證

本項目採用 MIT 許可證。