Chrome Debug MCP

🚀 Chrome Debug MCP Server

Chrome Debug MCP Server 是一個基於調試協議的 Chrome 瀏覽器自動化模型上下文協議（MCP）服務器。它專為連接 Chrome 調試端口而設計，能夠在保持登錄會話的情況下實現瀏覽器自動化，為需要用戶認證的自動化場景提供了強大支持。

🚀 快速開始

選項 1：直接使用（推薦）

使用 npx 啟動，無需安裝：

# 1. 以調試模式啟動 Chrome
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# 2. 直接運行 MCP 服務器
npx chrome-debug-mcp

選項 2：本地開發

git clone https://github.com/rainmenxia/chrome-debug-mcp.git
cd chrome-debug-mcp
npm install
npm run build
npm start

✨ 主要特性

• ✅ Chrome 調試端口連接：基於標準的 Chrome DevTools 協議，無需擴展程序。
• 🏢 企業級部署：零依賴部署，無需 Chrome 網上應用店審批。
• 📱 智能標籤管理：對同一域名複用標籤頁，避免重複打開。
• 🖼️ 實時截圖反饋：每次操作後自動截圖，提供可視化反饋。
• 🌐 網絡活動監控：自動等待頁面加載完成。
• 🐳 原生 Docker 支持：完美支持容器化的 Chrome 實例，無擴展限制。
• ⚡ 兩步啟動：以調試模式啟動 Chrome，然後運行 npx chrome-debug-mcp，無需複雜安裝。
• 🔍 智能瀏覽器發現：自動發現本地和 Docker 環境中的 Chrome 實例。

📦 安裝指南

1. 啟動 Chrome 調試模式（必需）

服務器需要連接到啟用了調試端口的 Chrome 實例：

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows
chrome.exe --remote-debugging-port=9222 --user-data-dir=c:\temp\chrome-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

⚠️ 重要提示

• --user-data-dir 參數指向一個臨時目錄，確保 Chrome 以調試模式啟動。
• 啟動後，您可以正常登錄網站，登錄會話將被保留。
• 服務器將複用此 Chrome 實例，無需重新登錄。

2. 配置 MCP 客戶端

在您的 MCP 客戶端中添加以下配置：

{
  "mcpServers": {
    "browser-automation": {
      "command": "npx",
      "args": ["chrome-debug-mcp"]
    }
  }
}

💡 使用建議

無需安裝、下載，也無需複雜的路徑配置。

⚠️ 重要提示

您還可以選擇以下替代安裝方法：

全局安裝：

npm install -g chrome-debug-mcp

{
  "mcpServers": {
    "browser-automation": {
      "command": "chrome-debug-mcp"
    }
  }
}

本地項目安裝：

npm install chrome-debug-mcp

{
  "mcpServers": {
    "browser-automation": {
      "command": "npx",
      "args": ["chrome-debug-mcp"]
    }
  }
}

💻 使用示例

基礎用法

1. launch_browser

連接到 Chrome 調試端口並初始化瀏覽器會話。

{
  "name": "launch_browser",
  "arguments": {
    "remote_host": "http://localhost:9222"  // 可選
  }
}

2. navigate_to

使用智能標籤管理導航到指定 URL。

{
  "name": "navigate_to", 
  "arguments": {
    "url": "https://example.com"
  }
}

3. click

在指定座標處點擊。

{
  "name": "click",
  "arguments": {
    "coordinate": "100,200"
  }
}

4. type_text

輸入文本內容。

{
  "name": "type_text",
  "arguments": {
    "text": "Hello World"
  }
}

5. scroll_down / scroll_up

滾動頁面。

{
  "name": "scroll_down",
  "arguments": {}
}

6. hover

將鼠標懸停在指定位置。

{
  "name": "hover",
  "arguments": {
    "coordinate": "100,200"
  }
}

7. resize_browser

調整瀏覽器窗口大小。

{
  "name": "resize_browser",
  "arguments": {
    "size": "1200,800"
  }
}

8. get_page_content

獲取當前頁面的 HTML 內容。

{
  "name": "get_page_content",
  "arguments": {}
}

9. close_browser

關閉瀏覽器連接。

{
  "name": "close_browser",
  "arguments": {}
}

高級用法

1. 社交媒體自動化

# 先在 Chrome 中手動登錄 Twitter/微博
# 然後使用 MCP 工具進行自動化操作
launch_browser -> navigate_to -> click -> type_text

2. 電商運營

# 保持淘寶/京東的登錄狀態
# 自動進行商品搜索、價格監控等操作
launch_browser -> navigate_to -> type_text -> click

3. 數據抓取

# 從需要登錄的網站抓取數據
# 繞過登錄驗證，直接進行操作
launch_browser -> navigate_to -> get_page_content

📚 詳細文檔

高級特性

智能標籤管理

• 同一域名（例如 example.com）複用現有標籤頁。
• 不同域名自動創建新標籤頁。
• 避免重複打開同一網站。

自動等待機制

• 監控網絡活動，等待頁面完全加載。
• 檢測 HTML 內容的穩定性。
• 自動處理動態內容加載。

錯誤恢復

• 連接中斷時自動重新連接。
• 緩存成功連接的端點。
• 提供詳細的錯誤日誌和反饋。

Docker 環境支持

如果 Chrome 在 Docker 容器中運行：

# 在 Docker 中啟動 Chrome
docker run -d --name chrome-debug \
  -p 9222:9222 \
  --shm-size=2gb \
  zenika/alpine-chrome \
  --no-sandbox \
  --disable-dev-shm-usage \
  --remote-debugging-address=0.0.0.0 \
  --remote-debugging-port=9222

服務器將自動發現 Docker 環境中的 Chrome 實例。

故障排除

Chrome 連接失敗

1. 確認 Chrome 以 --remote-debugging-port=9222 啟動。
2. 檢查端口 9222 是否被佔用：lsof -i :9222。
3. 確保沒有其他 Chrome 實例正在運行。

操作超時

1. 檢查網絡連接。
2. 增加頁面加載超時時間。
3. 確認目標網站可訪問。

截圖失敗

1. 確認頁面已完全加載。
2. 檢查瀏覽器窗口大小設置。
3. 嘗試刷新頁面並重新操作。

技術架構

MCP Client ←→ stdio ←→ MCP Server ←→ Chrome Debug Port ←→ Chrome Browser

開發與調試

# 監聽模式編譯
npm run dev

# 查看 MCP 通信日誌
DEBUG=mcp* npm start

發佈到 npm

# 構建項目
npm run build

# 發佈到 npm
npm publish

致謝

本項目的設計理念和核心概念受到了 RooCode 項目的啟發。RooCode 是一個優秀的瀏覽器自動化 MCP 服務器實現，為我們提供了寶貴的技術參考和設計思路。

特別感謝 RooCode 團隊在以下方面的貢獻：

• 🎯 MCP 協議集成：提供了將 MCP 服務器與瀏覽器自動化相結合的技術解決方案。
• 🔗 瀏覽器連接：展示了優雅的瀏覽器連接和會話管理方式。
• 📋 工具 API 設計：為標準化瀏覽器操作提供了參考框架。

在此基礎上，本項目進一步專注於 保持登錄會話的瀏覽器自動化，通過連接現有的 Chrome 調試端口來維護用戶會話，實現了更實用的自動化功能。

📄 許可證

本項目採用 MIT 許可證。

核心優勢：此 MCP 服務器的最大特點是能夠連接現有的 Chrome 實例並保持登錄會話，非常適合需要用戶認證的自動化場景。通過 Chrome 調試端口，它可以接管已登錄用戶的瀏覽器會話，實現真正的“會話持久化”瀏覽器自動化。