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 • 💡 请求新功能