Claude Browser MCP

🚀 瀏覽器MCP服務器

這是一個模型上下文協議（MCP）服務器，藉助 Playwright 提供全面的瀏覽器自動化功能。該服務器允許AI助手通過標準化的MCP工具與網頁進行交互，實現導航、內容提取、表單填充和截圖捕獲等操作。

🚀 快速開始

該服務器可讓AI助手通過標準化的MCP工具與網頁交互，實現導航、內容提取等功能。以下是快速開始的步驟：

安裝

前提條件

• Python 3.8 或更高版本
• Node.js（用於安裝Playwright瀏覽器）

從源代碼安裝

# 克隆倉庫
git clone <repository-url>
cd claude-browser-mcp

# 安裝依賴
pip install -e .

# 安裝Playwright瀏覽器
playwright install

從PyPI安裝（如果可用）

pip install claude-browser-mcp
playwright install

啟動服務器

使用標準輸入輸出傳輸啟動服務器：

browser-mcp
# 或者
python -m src.server

配置

通過環境變量配置瀏覽器：

export BROWSER_HEADLESS=true          # 以無頭模式運行
export BROWSER_TYPE=chromium          # 瀏覽器類型（chromium/firefox/webkit）
export BROWSER_TIMEOUT=30000          # 默認超時時間（毫秒）

MCP客戶端集成

添加到您的MCP客戶端配置中：

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

✨ 主要特性

核心瀏覽器操作

• 導航到URL：採用智能等待策略
• 提取頁面內容：可使用自定義選擇器
• 截圖：支持全頁、視口或特定元素截圖
• 執行JavaScript：並捕獲結果
• 點擊元素：通過CSS選擇器
• 自動填充表單：並進行驗證

高級功能

• 多瀏覽器支持：（Chromium、Firefox、WebKit）
• 請求攔截和監控
• 視口定製和響應式測試
• 鏈接提取和URL處理
• 錯誤處理：提供詳細響應
• 資源管理和清理

📦 安裝指南

前提條件

• Python 3.8 或更高版本
• Node.js（用於安裝Playwright瀏覽器）

從源代碼安裝

# 克隆倉庫
git clone <repository-url>
cd claude-browser-mcp

# 安裝依賴
pip install -e .

# 安裝Playwright瀏覽器
playwright install

從PyPI安裝（如果可用）

pip install claude-browser-mcp
playwright install

💻 使用示例

基礎用法

作為MCP服務器啟動

browser-mcp
# 或者
python -m src.server

配置瀏覽器

export BROWSER_HEADLESS=true          # 以無頭模式運行
export BROWSER_TYPE=chromium          # 瀏覽器類型（chromium/firefox/webkit）
export BROWSER_TIMEOUT=30000          # 默認超時時間（毫秒）

MCP客戶端集成

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

高級用法

可用工具示例

navigate_to

導航到指定URL，並可選擇等待。

{
  "name": "navigate_to",
  "arguments": {
    "url": "https://example.com",
    "wait_for": "selector", 
    "timeout": 30
  }
}

get_page_content

從當前頁面提取文本內容。

{
  "name": "get_page_content", 
  "arguments": {
    "include_links": true,
    "selector": ".main-content"
  }
}

click_element

通過CSS選擇器點擊元素。

{
  "name": "click_element",
  "arguments": {
    "selector": "button#submit",
    "timeout": 10
  }
}

fill_form

用數據填充表單字段。

{
  "name": "fill_form",
  "arguments": {
    "fields": {
      "#email": "user@example.com",
      "#password": "secretpass"
    },
    "submit": true
  }
}

take_screenshot

捕獲頁面截圖。

{
  "name": "take_screenshot",
  "arguments": {
    "full_page": true,
    "selector": ".dashboard"
  }
}

execute_javascript

在瀏覽器上下文中運行JavaScript。

{
  "name": "execute_javascript", 
  "arguments": {
    "code": "document.title",
    "return_value": true
  }
}

📚 詳細文檔

項目結構

claude-browser-mcp/
├── src/
│   ├── __init__.py          # 包初始化
│   ├── server.py            # MCP服務器實現
│   ├── browser.py           # 瀏覽器管理
│   ├── actions.py           # 高級瀏覽器操作
│   └── utils.py             # 實用函數
├── requirements.txt         # Python依賴
├── setup.py                 # 包配置
└── README.md               # 本文件

架構

服務器 (server.py)

• 實現MCP服務器並註冊工具
• 請求路由和響應格式化
• 錯誤處理和日誌記錄
• 異步工具執行

瀏覽器管理器 (browser.py)

• 管理Playwright瀏覽器的生命週期
• 創建和配置上下文
• 資源清理和恢復
• 多瀏覽器支持

操作 (actions.py)

• 高級瀏覽器自動化方法
• 內容提取和處理
• 表單交互和驗證
• 截圖和JavaScript執行

實用工具 (utils.py)

• HTML清理和淨化
• URL驗證和規範化
• 圖像處理和編碼
• 數據格式化實用工具

🔧 技術細節

安全考慮

• HTML淨化：去除危險腳本和屬性
• URL驗證：防止惡意重定向
• 輸入驗證：對所有用戶提供的數據進行驗證
• 資源限制：防止過度使用內存
• 超時控制：防止操作掛起

Docker部署

使用Docker快速啟動

# 使用Docker Compose構建並運行
docker-compose up browser-mcp

# 或者手動構建
./scripts/docker-build.sh
./scripts/start-container.sh

生產部署

# 構建生產鏡像
docker build -t browser-mcp:latest .

# 使用優化設置運行
docker run -d \
  --name browser-mcp \
  --init --ipc=host --shm-size=1gb \
  --memory=2g --cpus=1.0 \
  -v $(pwd)/screenshots:/app/screenshots \
  -v $(pwd)/downloads:/app/downloads \
  browser-mcp:latest

使用Docker進行開發

# 帶有調試功能的開發容器
docker-compose --profile dev up browser-mcp-dev

# 進入容器
docker exec -it claude-browser-mcp-dev /bin/bash

容器管理

# 健康檢查
./scripts/health-check.sh

# 查看日誌
docker logs -f claude-browser-mcp

# 監控資源
docker stats claude-browser-mcp

錯誤處理

服務器提供詳細的錯誤響應，包括：

• 錯誤分類：（超時、驗證、執行）
• 上下文信息：（URL、選擇器、參數）
• 恢復建議：在適用的情況下
• 日誌記錄：用於調試和監控

響應格式

所有工具返回標準化的JSON響應：

{
  "success": true,
  "url": "https://example.com",
  "title": "頁面標題",
  "data": "...",
  "metadata": {
    "timestamp": "...",
    "execution_time": "..."
  }
}

錯誤響應包括：

{
  "success": false,
  "error": "詳細錯誤消息",
  "tool": "工具名稱",
  "arguments": {...},
  "timestamp": "..."
}

環境變量

📄 許可證

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

🙏 致謝

• Playwright：提供瀏覽器自動化功能
• MCP：提供協議規範
• Anthropic：進行Claude和MCP開發

📞 支持

• 問題反饋：在GitHub上報告錯誤和請求功能
• 文檔查閱：查看代碼內的文檔
• 社區交流：加入MCP社區討論

注意：這是一個基礎實現。根據具體用例，可以添加更多功能，如請求攔截、高級表單處理和性能優化。