MCP Browser Agent

🚀 MCP瀏覽器代理

MCP瀏覽器代理是一款強大的Model Context Protocol（MCP）集成工具，它賦予Claude Desktop自主的瀏覽器自動化能力，可幫助用戶更高效地完成各類網頁操作和API請求。

🚀 快速開始

要使用MCP瀏覽器代理，你需要滿足以下要求：

• Node.js 16或更高版本
• Claude Desktop
• Playwright依賴項

瀏覽器支持

npm init playwright@latest

此軟件包包含Playwright和運行瀏覽器自動化所需的依賴項。當你運行npm install時，將安裝所需的Playwright依賴項。該軟件包支持以下瀏覽器：

• Chrome（默認）
• Firefox
• Microsoft Edge
• WebKit（Safari引擎）

首次使用某種瀏覽器類型時，Playwright將根據需要自動安裝相應的瀏覽器驅動程序。你也可以使用以下命令手動安裝它們：

npx playwright install chrome
npx playwright install firefox
npx playwright install webkit
npx playwright install msedge

⚠️ 重要提示

• 關於Safari：Playwright不直接支持Safari瀏覽器，而是使用WebKit，它是Safari的瀏覽器引擎。
• 關於Edge：選擇Edge作為瀏覽器類型時，代理實際上將啟動Microsoft Edge（非Chromium）。從技術上講，在Playwright中，Edge是使用Chromium瀏覽器實例並帶有'msedge'通道參數啟動的，因為Microsoft Edge基於Chromium。

安裝步驟

手動安裝

1. 克隆或下載此倉庫：

git clone https://github.com/imprvhub/mcp-browser-agent
cd mcp-browser-agent

2. 安裝依賴項：

npm install

3. 構建項目：

npm run build

運行MCP服務器

有兩種方法可以運行MCP服務器：

方法一：手動運行

1. 打開終端或命令提示符。
2. 導航到項目目錄。
3. 直接運行服務器：

node dist/index.js

在使用Claude Desktop時，請保持此終端窗口打開。服務器將一直運行，直到你關閉終端。

方法二：隨Claude Desktop自動啟動（建議常規使用）

Claude Desktop可以在需要時自動啟動MCP服務器。要進行設置，請按以下步驟操作：

配置

Claude Desktop配置文件位於：

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

編輯此文件以添加瀏覽器代理MCP配置。如果文件不存在，請創建它：

{
  "mcpServers": {
    "browserAgent": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
      "--browser",
      "chrome"
    ]
    }
  }
}

重要提示：請將ABSOLUTE_PATH_TO_DIRECTORY替換為你安裝MCP的完整絕對路徑：

• macOS/Linux示例：/Users/username/mcp-browser-agent
• Windows示例：C:\\Users\\username\\mcp-browser-agent

如果你已經配置了其他MCP，只需在mcpServers對象中添加browserAgent部分。以下是一個包含多個MCP的配置示例：

{
  "mcpServers": {
    "otherMcp1": {
      "command": "...",
      "args": ["..."]
    },
    "otherMcp2": {
      "command": "...",
      "args": ["..."]
    },
    "browserAgent": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
      "--browser",
      "chrome"
    ]
    }
  }
}

瀏覽器選擇

MCP瀏覽器代理支持多種瀏覽器類型。默認情況下，它使用Chrome，但你可以通過以下幾種方式指定不同的瀏覽器：

方式一：配置文件

在你的主目錄中創建或編輯文件.mcp_browser_agent_config.json：

{
  "browserType": "chrome"
}

browserType支持的值包括：

• chrome - 使用已安裝的Chrome（默認）
• firefox - 使用Firefox 'Nightly'瀏覽器
• webkit - 使用WebKit引擎（注意：這不是Safari本身，而是驅動Safari的WebKit渲染引擎）
• edge - 使用Microsoft Edge

方式二：命令行參數

手動啟動MCP服務器時，你可以指定瀏覽器類型：

node dist/index.js --browser firefox

方式三：環境變量

設置MCP_BROWSER_TYPE環境變量：

MCP_BROWSER_TYPE=firefox node dist/index.js

方式四：Claude Desktop配置

在Claude Desktop的claude_desktop_config.json中配置MCP時，你可以指定瀏覽器類型：

{
  "mcpServers": {
    "browserAgent": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
        "--browser",
        "chrome"
      ]
    }
  }
}

✨ 主要特性

• 高級瀏覽器自動化
  • 可使用自定義加載策略導航到任何URL。
  • 捕獲全頁或特定元素的屏幕截圖。
  • 執行精確的DOM交互（點擊、填充、選擇、懸停）。
  • 在瀏覽器上下文中執行任意JavaScript並捕獲控制檯日誌。
• 強大的API客戶端
  • 執行HTTP請求（GET、POST、PUT、PATCH、DELETE）。
  • 配置請求頭和主體內容。
  • 使用JSON格式處理響應數據。
  • 進行錯誤處理並提供詳細反饋。
• MCP資源管理
  • 將瀏覽器控制檯日誌作為資源訪問。
  • 通過MCP資源接口檢索屏幕截圖。
  • 使用有頭瀏覽器實例保持持久會話。
• AI代理功能
  • 為複雜任務鏈式執行多個瀏覽器操作。
  • 遵循多步驟指令並進行智能錯誤恢復。
  • 通過自然語言指令實現技術任務自動化。

💻 使用示例

基礎用法

以下是一些使用MCP瀏覽器代理與Claude的實際示例：

Navigate to the Google homepage at https://www.google.com

Take a screenshot of the current page and name it "google-homepage"

Type "weather forecast" in the search box

Navigate to https://www.wikipedia.org and search for "Model Context Protocol"

Go to https://the-internet.herokuapp.com/dropdown and select the option "Option 1" from the dropdown

Navigate to https://the-internet.herokuapp.com/login and fill in the username field with "tomsmith" and the password field with "SuperSecretPassword!"

Go to https://the-internet.herokuapp.com/login, fill in the username and password fields, then click the login button

Go to https://example.com and execute a JavaScript script to return the page title

Navigate to https://www.google.com and execute a JavaScript script to count the number of links on the page

Perform a GET request to https://jsonplaceholder.typicode.com/todos/1

Make a POST request to https://jsonplaceholder.typicode.com/posts with appropriate JSON data

📚 詳細文檔

可用工具

瀏覽器工具

工具名稱	描述	參數
browser_navigate	導航到URL	url（必需）, timeout, waitUntil
browser_screenshot	捕獲屏幕截圖	name（必需）, selector, fullPage, mask, savePath
browser_click	點擊元素	selector（必需）
browser_fill	填充表單輸入	selector（必需）, value（必需）
browser_select	選擇下拉選項	selector（必需）, value（必需）
browser_hover	懸停在元素上	selector（必需）
browser_evaluate	執行JavaScript	script（必需）

API工具

工具名稱	描述	參數
api_get	GET請求	url（必需）, headers
api_post	POST請求	url（必需）, data（必需）, headers
api_put	PUT請求	url（必需）, data（必需）, headers
api_patch	PATCH請求	url（必需）, data（必需）, headers
api_delete	DELETE請求	url（必需）, headers

資源訪問

MCP瀏覽器代理公開了以下資源：

• browser://logs - 訪問瀏覽器控制檯日誌
• screenshot://[name] - 按名稱訪問屏幕截圖

🔧 技術細節

技術實現

MCP瀏覽器代理基於Model Context Protocol構建，使Claude能夠通過Playwright與有頭瀏覽器進行交互。該實現包含四個主要組件：

1. 服務器（index.ts）

• 使用Model Context Protocol標準協議初始化MCP服務器。
• 配置服務器的工具和資源功能。
• 通過stdio傳輸與Claude建立通信。

2. 工具註冊表（tools.ts）

• 定義瀏覽器和API工具模式。
• 指定參數、驗證規則和描述。
• 向MCP服務器註冊工具以供Claude發現。

3. 請求處理程序（handlers.ts）

• 管理工具和資源的MCP協議請求。
• 將瀏覽器日誌和屏幕截圖作為可查詢資源公開。
• 將工具執行請求路由到適當的處理程序。

4. 執行器（executor.ts）

• 管理瀏覽器和API客戶端的生命週期。
• 使用Playwright實現瀏覽器自動化功能。
• 處理API請求並進行適當的錯誤處理和響應解析。
• 在命令之間維護有狀態的瀏覽器會話。

代理功能

與基本集成不同，MCP瀏覽器代理作為真正的AI代理，具有以下特點：

• 在多個命令之間保持持久的瀏覽器狀態。
• 捕獲詳細的控制檯日誌以進行調試。
• 存儲屏幕截圖以供參考和審查。
• 管理複雜的交互序列。
• 提供詳細的錯誤信息以進行恢復。
• 支持鏈式操作以實現複雜工作流程。

🐞 故障排除

"服務器斷開連接"錯誤

如果你在Claude Desktop中看到錯誤 "MCP Browser Agent: Server disconnected"：

1. 驗證服務器是否正在運行：

• 打開終端，從項目目錄手動運行node dist/index.js。
• 如果服務器成功啟動，請在保持此終端打開的情況下使用Claude。

2. 檢查你的配置：

• 確保claude_desktop_config.json中的絕對路徑對於你的系統是正確的。
• 仔細檢查Windows路徑是否使用了雙反斜槓 (\\)。
• 驗證你使用的是從文件系統根目錄開始的完整路徑。

瀏覽器未出現

如果瀏覽器未啟動或你看不到它：

1. 檢查指定的瀏覽器是否已安裝：

• 驗證你已在系統上安裝了瀏覽器（Chrome、Firefox、Edge或Safari/WebKit）。
• 瀏覽器驅動程序由Playwright自動處理。

2. 重啟服務器和Claude Desktop：

• 終止任何可能正在運行服務器的現有節點進程。
• 重啟Claude Desktop以建立新連接。

瀏覽器進程未正確關閉

Chromium和Chrome瀏覽器存在已知問題，有時使用後進程不會正確終止。如果你遇到此問題：

1. 手動關閉瀏覽器進程：

• Windows：按Ctrl+Shift+Esc打開任務管理器，找到Chrome/Chromium進程並結束它。
• macOS：打開活動監視器（應用程序 > 實用工具 > 活動監視器），找到Chrome/Chromium進程並點擊X終止它。
• Linux：運行ps aux | grep chrome或ps aux | grep chromium查找進程，然後使用kill <PID>終止它。

2. 關於瀏覽器兼容性的注意事項：

• 此問題主要在Chromium和Chrome上觀察到。
• Firefox和Playwright內置的瀏覽器通常不會遇到此問題。

⚠️ 重要提示

此MCP集成基於Playwright構建，Playwright存在已知問題和錯誤，可能會影響其操作。請將你在瀏覽器自動化中遇到的任何問題報告給 Playwright的GitHub問題。Playwright團隊正在不斷努力解決這些問題，但儘管存在這些限制，此代理仍為Claude Desktop提供了瀏覽器自動化功能的基礎。

🛠️ 開發

項目結構

• src/index.ts：主入口點和MCP服務器初始化。
• src/tools.ts：工具模式和註冊。
• src/handlers.ts：工具和資源的MCP請求處理程序。
• src/executor.ts：使用Playwright的工具實現邏輯。

構建

npm run build

監視更改

npm run watch

測試

項目包含測試以驗證核心功能和瀏覽器處理。

npm test               # 運行測試
npm run test:watch     # 監視模式
npm run test:coverage  # 覆蓋率報告

測試驗證配置完整性、瀏覽器自動化功能、錯誤處理和進程清理。由於Chrome/Chromium終止存在已知問題，測試套件特別關注確保正確處理瀏覽器進程。

⚠️ 安全考慮

⚠️ 重要提示

此MCP集成賦予Claude自主的瀏覽器控制能力。請查看我們的 安全策略，瞭解有關禁止使用、安全影響和最佳實踐的重要信息。

MCP瀏覽器代理旨在用於合法的自動化任務，但可能會被濫用。用戶有責任確保其使用符合所有適用的法律、服務條款和道德準則。有關更多信息，請參閱我們詳細的 安全策略。

👥 貢獻

歡迎為MCP瀏覽器代理做出貢獻！你可以在以下方面提供幫助：

• 添加新的瀏覽器自動化功能。
• 改進錯誤處理和恢復。
• 增強屏幕截圖和資源管理。
• 創建有用的工作流程和示例。
• 優化複雜操作的性能。

📄 許可證

本項目採用Mozilla公共許可證2.0 - 有關詳細信息，請參閱 LICENSE 文件。

🔗 相關鏈接

• Model Context Protocol
• Claude Desktop
• Playwright文檔
• MCP系列