Puppeteer Real Browser MCP Server

🚀 Puppeteer Real Browser MCP Server

Puppeteer Real Browser MCP Server 是一個基於 Model Context Protocol (MCP) 的服務器，藉助 puppeteer-real-browser 為 AI 助手提供強大且難以被檢測的瀏覽器自動化能力。

🚀 快速開始

這是什麼？

這是一個 MCP（模型上下文協議）服務器，它能讓像 Claude 這樣的 AI 助手控制真實的網絡瀏覽器。可以把它想象成給 Claude 裝上了“手”，使其能夠與網站進行交互，比如點擊按鈕、填寫表單、截圖等等，同時還能避免被網站識別為機器人。

逐步設置

1. 安裝 Node.js

• 訪問 nodejs.org
• 下載並安裝 Node.js（版本 18 或更高）
• 打開終端或命令提示符，輸入 node --version 驗證安裝是否成功

2. 使用 Claude Desktop 設置（無需手動安裝）

使用 npx 命令將自動下載並運行最新版本，因此無需手動安裝。

3. 配置 Claude Desktop

Windows 用戶：

1. 打開文件資源管理器，導航到：%APPDATA%\Claude\
2. 打開（或創建）claude_desktop_config.json 文件
3. 添加以下配置：

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": ["puppeteer-real-browser-mcp-server@latest"]
    }
  }
}

Mac 用戶：

1. 打開 Finder，按下 Cmd + Shift + G
2. 前往：~/Library/Application Support/Claude/
3. 打開（或創建）claude_desktop_config.json 文件
4. 添加與上述相同的配置

Linux 用戶：

1. 導航到：~/.config/Claude/
2. 打開（或創建）claude_desktop_config.json 文件
3. 添加與上述相同的配置

4. 重啟 Claude Desktop

完全關閉並重新打開 Claude Desktop。

5. 測試是否正常工作

在 Claude Desktop 中，嘗試輸入：

"Initialize a browser and navigate to google.com, then take a screenshot"（初始化一個瀏覽器並導航到谷歌，然後截圖）

如果一切正常，Claude 應該能夠：

• 啟動瀏覽器
• 導航到谷歌網站
• 截取屏幕截圖並展示給你

它能做什麼？

設置完成後，你可以要求 Claude 執行以下操作：

• 瀏覽網站："Go to amazon.com and search for laptops"（訪問亞馬遜並搜索筆記本電腦）
• 填寫表單："Fill out this contact form with my details"（用我的信息填寫此聯繫表單）
• 截圖："Show me what this page looks like"（給我展示這個頁面的樣子）
• 提取數據："Get all the product prices from this page"（從這個頁面獲取所有產品價格）
• 自動化任務："Log into my account and download my invoice"（登錄我的賬戶並下載發票）
• 解決驗證碼："Handle any captchas that appear"（處理出現的任何驗證碼）

安全注意事項

• Claude 會展示它正在執行的操作，你可以看到瀏覽器窗口
• 在批准敏感操作之前，務必仔細審查 Claude 的操作
• 如果你不想看到瀏覽器窗口，可以使用無頭模式（headless: true）
• 請遵守網站的使用條款

✨ 主要特性

• 默認隱身：所有瀏覽器實例均採用反檢測功能
• 增強頁面方法：支持 page.realClick 和 page.realCursor
• 高級配置：全面支持 puppeteer-real-browser 的所有選項
• 類人操作：具備自然交互工具，避免被檢測
• 綜合工具集：提供 16 種以上工具，滿足所有瀏覽器自動化需求
• 代理支持：內置代理配置，增強隱私保護
• 驗證碼處理：支持解決 reCAPTCHA、hCaptcha 和 Turnstile 驗證碼
• 目標管理：支持 setTarget 函數
• 錯誤處理：強大的錯誤處理和報告機制

📦 安裝指南

從 npm 安裝

npm install -g puppeteer-real-browser-mcp-server

從源代碼安裝

# 克隆倉庫
git clone https://github.com/withLinda/puppeteer-real-browser-mcp-server.git
cd puppeteer-real-browser-mcp-server

# 安裝依賴
npm install

# 構建項目
npm run build

💻 使用示例

與 Claude Desktop 配合使用

在 Claude Desktop 配置文件中添加以下內容：

{
  "mcpServers": {
    "puppeteer-real-browser": {
      "command": "npx",
      "args": ["puppeteer-real-browser-mcp-server@latest"]
    }
  }
}

與其他 AI 助手配合使用

啟動服務器：

puppeteer-real-browser-mcp-server

如果是從源代碼安裝的，可以使用以下命令啟動：

npm start

服務器通過 stdin/stdout 使用 MCP 協議進行通信。

示例交互

基礎網頁瀏覽

用戶："Initialize a browser and navigate to example.com"（初始化一個瀏覽器並導航到 example.com）
AI：I'll initialize a stealth browser and navigate to the website.（我將初始化一個隱身瀏覽器並導航到該網站）
[使用 browser_init 和 navigate 工具]

用戶："Take a screenshot of the main content"（對主要內容進行截圖）
AI：I'll capture a screenshot of the page.（我將截取頁面的屏幕截圖）
[使用 screenshot 工具]

表單自動化

用戶："Fill in the search form with 'test query'"（在搜索表單中輸入 'test query'）
AI：I'll type that into the search field using human-like typing.（我將以類似人類的方式在搜索框中輸入該內容）
[使用 human_like_type 工具，指定選擇器和文本]

用戶："Click the search button"（點擊搜索按鈕）
AI：I'll click the search button with human-like movement.（我將以類似人類的動作點擊搜索按鈕）
[使用 human_like_click 工具]

數據提取

用戶："Get all the product names from this e-commerce page"（從這個電商頁面獲取所有產品名稱）
AI：I'll extract the product information from the page.（我將從頁面提取產品信息）
[使用 get_content 工具並指定適當的選擇器]

用戶："Save the page content as text"（將頁面內容保存為文本）
AI：I'll get the text content of the entire page.（我將獲取整個頁面的文本內容）
[使用 get_content 工具並指定類型為 'text']

高級交互

用戶："Use real click on the dropdown menu"（在下拉菜單上使用真實點擊）
AI：I'll use the enhanced real_click method for better interaction.（我將使用增強的 real_click 方法以實現更好的交互）
[使用 real_click 工具並指定選擇器和選項]

用戶："Move the cursor to coordinates 500, 300 smoothly"（將光標平滑移動到座標 500, 300）
AI：I'll move the cursor using enhanced movement.（我將使用增強的移動方式移動光標）
[使用 real_cursor 工具並指定 x、y 座標和步驟選項]

使用代理

用戶："Initialize a browser with a proxy server"（使用代理服務器初始化一個瀏覽器）
AI：I'll set up the browser with your proxy configuration.（我將根據你的代理配置設置瀏覽器）
[使用 browser_init 工具並指定 proxy: "https://proxy.example.com:8080"]

📚 詳細文檔

可用工具

核心瀏覽器工具

工具名稱	描述	必需參數	可選參數
browser_init	使用高級選項初始化隱身瀏覽器	無	headless, disableXvfb, ignoreAllFlags, proxy, plugins, connectOption
navigate	導航到指定 URL	url	waitUntil
screenshot	截取頁面或元素的屏幕截圖	無	fullPage, selector
get_content	獲取頁面內容（HTML 或文本）	無	type, selector
browser_close	關閉瀏覽器實例	無	無

交互工具

工具名稱	描述	必需參數	可選參數
click	對元素進行標準點擊	selector	waitForNavigation
type	在輸入字段中輸入文本	selector, text	delay
wait	等待各種條件	type, value	timeout

增強的 Puppeteer-Real-Browser 工具

工具名稱	描述	必需參數	可選參數
real_click	使用 page.realClick 進行增強點擊	selector	options (button, clickCount, delay)
real_cursor	使用 page.realCursor 進行增強光標移動	selector 或 x, y	options (steps)
set_target	使用 setTarget 函數進行高級目標定位	target	無

類人行為工具

工具名稱	描述	必需參數	可選參數
human_like_click	以類似人類的鼠標移動方式點擊	selector	無
human_like_type	以類似人類的時間間隔輸入文本	selector, text	無
random_scroll	以自然的時間間隔和可變距離進行隨機滾動	無	無

反檢測工具

工具名稱	描述	必需參數	可選參數
solve_captcha	嘗試解決驗證碼	type	無

高級特性

類人交互

服務器包含多個模擬人類行為的工具：

• 類人鼠標移動：以自然的非線性路徑移動光標
• 可變輸入速度：在按鍵之間隨機延遲輸入
• 隨機滾動：以自然的時間間隔和可變距離進行滾動

這些特性有助於避免被分析用戶行為模式的複雜機器人檢測系統識別。

驗證碼處理

服務器基本支持解決常見的驗證碼類型：

• reCAPTCHA
• hCaptcha
• Cloudflare Turnstile

請注意，驗證碼解決能力取決於底層的 puppeteer-real-browser 實現。

配置

配置自定義選項（如無頭模式）

像無頭模式這樣的自定義選項不在 MCP 配置文件中配置。相反，它們在使用 browser_init 工具初始化瀏覽器時傳遞。

當你要求 Claude 初始化瀏覽器時，你可以指定如下選項：

Please initialize a browser with headless mode enabled and a 30-second timeout（請初始化一個啟用無頭模式並設置 30 秒超時的瀏覽器）

Claude 將使用 browser_init 工具並傳遞適當的參數：

{
  "headless": true,
  "connectOption": {
    "timeout": 30000
  }
}

可用的瀏覽器選項

使用 browser_init 初始化時，你可以配置以下選項：

• headless：true/false（設置為 true 以啟用無頭模式）
• disableXvfb：true/false（禁用 X 虛擬幀緩衝）
• ignoreAllFlags：true/false（忽略所有 Chrome 標誌）
• proxy："https://proxy:8080"（代理服務器 URL）
• plugins：["plugin1", "plugin2"]（要加載的插件數組）
• connectOption：其他連接選項，如：
  • slowMo：250（以毫秒為單位減慢操作速度）
  • timeout：60,000（連接超時時間）

MCP 配置文件僅告訴 Claude 服務器的位置 - 所有特定於瀏覽器的選項都通過與 Claude 的對話進行配置。

瀏覽器選項示例

使用 browser_init 初始化瀏覽器時，你可以進行如下配置：

{
  "headless": false,
  "disableXvfb": false,
  "ignoreAllFlags": false,
  "proxy": "https://proxy:8080",
  "plugins": ["plugin1", "plugin2"],
  "connectOption": {
    "slowMo": 250,
    "timeout": 60000
  }
}

高級配置示例

使用代理

{
  "headless": true,
  "proxy": "https://username:password@proxy.example.com:8080"
}

自定義選項的隱身模式

{
  "headless": false,
  "ignoreAllFlags": true,
  "disableXvfb": false,
  "connectOption": {
    "slowMo": 100,
    "devtools": false
  }
}

增強的真實瀏覽器功能

使用 real_click 並指定選項：

{
  "selector": "#submit-button",
  "options": {
    "button": "left",
    "clickCount": 2,
    "delay": 150
  }
}

使用 real_cursor 並指定座標：

{
  "x": 500,
  "y": 300,
  "options": {
    "steps": 30
  }
}

服務器配置

對於高級用戶，你可以通過編輯源代碼來修改服務器行為：

• 在 initializeBrowser 函數中更改默認視口大小
• 調整各種操作的超時值
• 啟用調試日誌

🔧 技術細節

常見問題

1. 使用 npx 時出現 "command not found" 或 "syntax error"

   • 此問題在 1.0.3 版本中通過添加正確的 shebang 行得到修復
   • 確保使用的是最新版本：npx puppeteer-real-browser-mcp-server@latest
   • 全局安裝：npm install -g puppeteer-real-browser-mcp-server@latest
   • 如果仍然存在問題，進行全局安裝：npm install -g puppeteer-real-browser-mcp-server
   • 檢查你的 PATH 環境變量是否包含 npm 全局二進制文件路徑：npm config get prefix

2. 瀏覽器無法啟動

   • 檢查是否安裝了 Chrome 或 Chromium
   • Linux 系統：安裝依賴：sudo apt-get install -y chromium-browser
   • Windows 系統：確保已安裝 Chrome
   • 先嚐試使用 headless: true

3. Claude 無法檢測到 MCP 服務器

   • 驗證 claude_desktop_config.json 文件是否位於正確的位置
   • 檢查 JSON 語法是否有效（可使用 jsonlint.com）
   • 完全重啟 Claude Desktop
   • 檢查 Claude Desktop 中的任何錯誤消息

4. 權限被拒絕錯誤

   • Linux/Mac 系統：嘗試使用 sudo npm install -g puppeteer-real-browser-mcp-server
   • 或者使用 nvm 管理 Node.js，避免使用 sudo
   • Windows 系統：以管理員身份運行命令提示符

5. 檢測問題

   • 使用 real_click 和 real_cursor 代替基本的點擊操作
   • 啟用類人工具：human_like_click, human_like_type
   • 使用 random_scroll 添加隨機延遲
   • 如有需要，使用代理：proxy: "http://proxy.example.com:8080"

6. 內存洩漏

   • 完成操作後，始終使用 browser_close 關閉瀏覽器實例
   • 不要在未關閉前一個瀏覽器的情況下初始化多個瀏覽器
   • 檢查是否存在未捕獲的異常，可能會阻止清理操作

7. 超時錯誤

   • 增加超時值：{ "timeout": 60000 }
   • 在與元素交互之前使用 wait 工具
   • 檢查網絡連接和網站響應時間

常見問題解答

問：它是否適用於無頭瀏覽器？ 答：是的，在 browser_init 選項中設置 headless: true。

問：我可以同時使用多個瀏覽器嗎？ 答：目前僅支持一個瀏覽器實例。在啟動新瀏覽器之前，請關閉當前瀏覽器。

問：它可以解決哪些驗證碼？ 答：通過 puppeteer-real-browser 支持 reCAPTCHA、hCaptcha 和 Cloudflare Turnstile。

問：網站能檢測到它嗎？ 答：puppeteer-real-browser 包含反檢測功能，但沒有一種解決方案是 100% 不可檢測的。

問：我可以使用自定義 Chrome 擴展嗎？ 答：是的，通過 browser_init 中的 plugins 選項。

問：它是否適用於所有操作系統？ 答：是的，已在 Windows、macOS 和 Linux 上進行測試。

調試模式

要啟用調試日誌：

DEBUG=true npm start

或者從源代碼運行時：

DEBUG=true npm run dev

獲取幫助

如果你仍然遇到問題：

1. 查看 GitHub Issues
2. 創建一個新問題，並提供以下信息：
   • 你的操作系統
   • Node.js 版本（node --version）
   • npm 版本（npm --version）
   • 完整的錯誤消息
   • 重現問題的步驟

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。