Browsercontrol

🚀 BrowserControl

BrowserControl 是一個 MCP 服務器，它以 視覺優先 的方式讓你的 AI 代理全面訪問瀏覽器，無需使用 CSS 選擇器、XPath，也無需猜測，只需指向編號元素即可操作。

🚀 快速開始

安裝

# 使用 pip
pip install browsercontrol

# 或者使用 uv（推薦，安裝速度更快）
uv add browsercontrol

# 首次運行時會自動安裝 Chromium，無需額外步驟！

運行服務器

# 使用 CLI
browsercontrol

# 或者作為 Python 模塊運行
python -m browsercontrol

# 或者使用 FastMCP
fastmcp run browsercontrol.server:mcp

連接到你的 AI 代理

BrowserControl 可與任何兼容 MCP 的 AI 代理或 IDE 配合使用。選擇你使用的平臺：

{
  "mcpServers": {
    "browsercontrol": {
      "command": "browsercontrol"
    }
  }
}

# 設置 MCP 配置
export MCP_SERVERS='{"browsercontrol": {"command": "browsercontrol"}}'

# 或者添加到你的 Gemini 配置文件中

{
  "browsercontrol": {
    "command": "browsercontrol"
  }
}

{
  "mcpServers": [
    {
      "name": "browsercontrol",
      "command": "browsercontrol"
    }
  ]
}

{
  "browsercontrol": {
    "command": "browsercontrol"
  }
}

{
  "context_servers": {
    "browsercontrol": {
      "command": {
        "path": "browsercontrol"
      }
    }
  }
}

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# 連接到 BrowserControl
server_params = StdioServerParameters(
    command="browsercontrol",
    args=[],
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # 初始化
        await session.initialize()

        # 列出可用工具
        tools = await session.list_tools()

        # 調用工具
        result = await session.call_tool("navigate_to", {
            "url": "https://github.com"
        })

{
  "mcpServers": {
    "browsercontrol": {
      "command": "uvx",
      "args": ["browsercontrol"]
    }
  }
}

{
  "mcpServers": {
    "browsercontrol": {
      "command": "pipx",
      "args": ["run", "browsercontrol"]
    }
  }
}

{
  "mcpServers": {
    "browsercontrol": {
      "command": "browsercontrol",
      "env": {
        "BROWSER_HEADLESS": "false",
        "BROWSER_VIEWPORT_WIDTH": "1920",
        "BROWSER_VIEWPORT_HEIGHT": "1080",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

✨ 主要特性

與傳統方法的對比

核心優勢

1. 多標籤管理

與其他工具在新窗口打開時容易“迷失”不同，BrowserControl 提供以下功能：

• list_tabs() — 查看每個打開頁面的標題和 URL
• switch_tab(index) — 在不同網站之間進行多任務處理
• create_tab(url) — 打開參考頁面或並行工作流

2. 會話和 cookie 管理

無需再為登錄表單煩惱，可直接注入或檢查會話狀態：

• set_cookie() — 通過注入認證令牌立即登錄
• get_cookies() — 調試會話問題或導出狀態
• clear_cookies() — 無需清除整個配置文件即可重新開始

3. 可靠的文件上傳

大多數 AI 代理在遇到 <input type="file"> 時會失敗，而 BrowserControl 使用原生瀏覽器引擎鉤子：

• upload_file(id, path) — 只需指向按鈕和本地文件即可上傳

4. 開發者工具套件

使用其他工具沒有提供的工具進行專業調試：

get_console_logs()      # 查看瀏覽器錯誤
get_network_requests()  # 監控 API 調用
get_page_errors()       # 捕獲 JavaScript 異常
run_in_console(code)    # 即時調試
inspect_element(5)      # 獲取計算樣式
get_page_performance()  # 核心 Web 指標

5. 會話錄製

start_recording()  →  瀏覽頁面  →  stop_recording()
                                              ↓
                               session_20260202.zip
                         (使用 Playwright 跟蹤查看器查看)

6. 動態視口控制

即時測試響應式設計或模擬移動屏幕：

• set_viewport(width, height) — 無需重啟即可更改分辨率

7. 真正的持久化

結果：只需登錄一次，即可跨會話保持登錄狀態。

🎯 工作原理：標記集（SoM）

每個屏幕截圖都會在交互式元素上標註 編號的紅色框：

Found 15 interactive elements:
  [1] button - Sign In
  [2] input - Search...
  [3] a - Products
  [4] a - Pricing
  [5] button - Get Started

你的代理看到這些編號後，只需調用 click(1) 即可登錄。無需 CSS 選擇器，無需 XPath，無需猜測。

詳細工作流程

1. AI 發送命令 — click(5)
2. 服務器查找元素 — 從最後一張截圖中查找編號為 5 的元素
3. 瀏覽器執行操作 — 點擊該元素的座標位置
4. 捕獲狀態 — 拍攝新的屏幕截圖，檢測元素
5. 標註 — 在交互式元素上繪製編號框
6. 返回給 AI — 發送標註後的圖像和元素列表

📦 安裝指南

# 使用 pip
pip install browsercontrol

# 或者使用 uv（推薦，安裝速度更快）
uv add browsercontrol

# 首次運行時會自動安裝 Chromium，無需額外步驟！

💻 使用示例

網頁研究

你："訪問維基百科，瞭解 Python 是何時創建的"

Claude：*導航到 wikipedia.org*
        *在搜索框中輸入 "Python programming language"*
        *點擊搜索結果*
        *閱讀頁面內容*

        "Python 由 Guido van Rossum 創建，並於 1991 年首次發佈。"

調試 Web 應用

你："訪問本地運行在 localhost:3000 的應用，並檢查是否有錯誤"

Claude：*導航到 localhost:3000*
        *調用 get_console_logs()*

        "我發現了 2 個錯誤：
         [ERROR] Uncaught TypeError: Cannot read property 'map' of undefined
         [ERROR] Failed to load resource: 404 /api/users"

        *調用 get_network_requests()*

        "/api/users 端點返回 404，請檢查你的 API 路由。"

帶錄製功能的自動化測試

你："測試我網站上的登錄流程，並開始錄製"

Claude：*調用 start_recording()*
        *導航到網站*
        *在元素 3 中輸入電子郵件*
        *在元素 4 中輸入密碼*
        *點擊登錄按鈕（元素 5）*
        *驗證是否成功重定向*
        *調用 stop_recording()*

        "登錄測試通過！錄製已保存為 session_20260202.zip"

表單自動化

你："填寫 example.com 上的聯繫表單"

Claude：*導航到 example.com/contact*
        *在元素 2 中輸入姓名*
        *在元素 3 中輸入電子郵件*
        *在元素 4 中輸入消息*
        *點擊提交按鈕（元素 5）*

        "表單提交成功！"

📚 詳細文檔

可用工具

導航

交互

標籤管理

表單操作

內容提取

開發者工具

錄製功能

配置

通過環境變量進行配置：

示例：

# 以可見瀏覽器模式運行（用於調試）
BROWSER_HEADLESS=false browsercontrol

# 模擬移動視口
BROWSER_VIEWPORT_WIDTH=375 BROWSER_VIEWPORT_HEIGHT=812 browsercontrol

# 詳細日誌記錄
LOG_LEVEL=DEBUG browsercontrol

🔧 技術細節

架構

┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│   AI Agent      │────▶│  BrowserControl  │────▶│   Browser   │
│ (Claude/Gemini) │◀────│   MCP Server     │◀────│ (Chromium)  │
└─────────────────┘     └──────────────────┘     └─────────────┘
        │                        │                      │
        │   "click(5)"           │   mouse.click()      │
        │◀───────────────────────│◀─────────────────────│
        │   [annotated           │   [screenshot +      │
        │    screenshot]         │    element map]      │

項目結構

browsercontrol/
├── __init__.py          # 包導出
├── __main__.py          # CLI 入口點
├── server.py            # MCP 服務器設置
├── browser.py           # 帶有 SoM 的瀏覽器管理器
├── config.py            # 環境配置
└── tools/
    ├── navigation.py    # 導航工具
    ├── interaction.py   # 點擊、輸入、懸停工具
    ├── forms.py         # 表單處理工具
    ├── content.py       # 內容提取工具
    ├── devtools.py      # 開發者工具
    ├── recording.py     # 會話錄製工具
    └── tabs.py          # 標籤管理工具

📄 許可證

本項目採用 MIT 許可證，你可以根據需要自由使用。

🤝 貢獻

歡迎貢獻代碼！請查看我們的 貢獻指南 瞭解詳細信息。

貢獻想法：

• [ ] 支持 Firefox/WebKit
• [ ] DOM 差異檢測（檢測變化）
• [ ] 可訪問性審計工具
• [ ] 移動模擬預設
• [ ] Cookie 導入/導出文件

# 克隆並安裝
git clone https://github.com/adityasasidhar/browsercontrol
cd browsercontrol
uv sync

# 運行測試
uv run pytest

# 在開發環境中運行
uv run fastmcp dev browsercontrol/server.py

🔧 故障排除

xvfb-run browsercontrol

python -m playwright install chromium

ls -la ~/.browsercontrol/

pkill -f browsercontrol
browsercontrol

npx playwright show-trace ~/.browsercontrol/recordings/session.zip

專為需要瀏覽網頁的 AI 代理而構建。

⭐ 在 GitHub 上給項目加星 • 🐛 報告 Bug • 💡 請求新功能