shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

browsercontrol

BrowserControl是一个为AI代理提供真实浏览器自动化能力的MCP服务器，采用视觉优先的方法，通过编号元素实现点击、输入等交互，无需CSS选择器或XPath。

article

README

🚀 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 配合使用。选择你使用的平台：

Claude Desktop

添加到你的 Claude 配置文件中：

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux：~/.config/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "browsercontrol": {
      "command": "browsercontrol"
    }
  }
}

重启 Claude Desktop，然后询问：

"访问 GitHub 并给 browsercontrol 仓库加星标"

✨ Gemini CLI / Google AI Studio

如果你使用支持 MCP 的 Gemini CLI 或 Google AI Studio：

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

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

对于 Google AI Studio，在 MCP 设置面板中进行配置。

🔧 Cline（VS Code 扩展）
  1. 安装 Cline 扩展
  2. 打开 Cline 设置（齿轮图标）
  3. 导航到 "MCP Servers"
  4. 添加新服务器：
{
  "browsercontrol": {
    "command": "browsercontrol"
  }
}
🤖 Continue.dev（VS Code/JetBrains）

添加到你的 Continue 配置文件（~/.continue/config.json）中：

{
  "mcpServers": [
    {
      "name": "browsercontrol",
      "command": "browsercontrol"
    }
  ]
}
🎯 Cursor IDE
  1. 打开 Cursor 设置
  2. 导航到 "Features" → "Model Context Protocol"
  3. 添加服务器配置：
{
  "browsercontrol": {
    "command": "browsercontrol"
  }
}
🔌 Zed Editor

添加到你的 Zed 设置文件（~/.config/zed/settings.json）中：

{
  "context_servers": {
    "browsercontrol": {
      "command": {
        "path": "browsercontrol"
      }
    }
  }
}
🐍 自定义 Python 集成

使用 MCP Python SDK 将 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"
        })
🚀 使用 uv 或 pipx 安装

如果你使用 uv 或 pipx 安装，请使用完整路径：

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

或者使用 pipx：

{
  "mcpServers": {
    "browsercontrol": {
      "command": "pipx",
      "args": ["run", "browsercontrol"]
    }
  }
}
🔧 高级配置

你可以通过传递环境变量来自定义 BrowserControl：

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

有关所有可用选项，请参阅 配置。

✨ 主要特性

与传统方法的对比

| 对比项 | 传统方法 | BrowserControl | | ---- | ---- | ---- | | 操作方式 | 解析复杂的 DOM 结构、猜测 CSS 选择器，如 "Find the button with class 'btn-primary' that contains 'Submit' and is inside form#contact-form..." | 查看带有编号元素的 渲染页面，直接说 "click 5" 或 "type in 3" | | JavaScript 支持 | 无 | 支持完整的 动态 JavaScript | | 登录持久化 | 无 | 跨重启保持 持久会话 | | 调试工具 | 无 | 可完全访问 开发者工具 |

核心优势

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. 真正的持久化

| 持久化项 | BrowserControl | 其他工具 | | ---- | ---- | ---- | | Cookies | ✅ | ❌ | | localStorage | ✅ | ❌ | | 会话令牌 | ✅ | ❌ | | 登录状态 | ✅ | ❌ | | 浏览器历史记录 | ✅ | ❌ |

结果：只需登录一次，即可跨会话保持登录状态。

🎯 工作原理：标记集（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）*

        "表单提交成功！"

📚 详细文档

可用工具

导航

| 工具 | 描述 | | ---- | ---- | | navigate_to(url) | 访问指定 URL | | go_back() | 后退 | | go_forward() | 前进 | | refresh_page() | 刷新页面 | | scroll(direction, amount) | 向上/下/左/右滚动 |

交互

| 工具 | 描述 | | ---- | ---- | | click(element_id) | 通过编号点击元素 | | click_at(x, y) | 点击指定坐标位置 | | type_text(element_id, text) | 在输入字段中输入文本 | | press_key(key) | 按下键盘按键（如 Enter、Tab 等） | | hover(element_id) | 悬停在元素上 | | scroll_to_element(element_id) | 将元素滚动到可见区域 | | upload_file(element_id, path) | 上传文件到输入框 | | wait(seconds) | 等待页面加载 |

标签管理

| 工具 | 描述 | | ---- | ---- | | create_tab(url) | 打开新的浏览器标签页 | | switch_tab(index) | 切换到指定索引的标签页 | | close_tab(index) | 关闭指定标签页 | | list_tabs() | 列出所有打开的标签页和 URL |

表单操作

| 工具 | 描述 | | ---- | ---- | | select_option(element_id, option) | 选择下拉选项 | | check_checkbox(element_id) | 切换复选框状态 | | upload_file(element_id, file_path) | 上传文件到输入框 |

内容提取

| 工具 | 描述 | | ---- | ---- | | get_page_content() | 获取页面的 Markdown 格式内容 | | get_text(element_id) | 获取元素的文本内容 | | get_page_info() | 获取页面的 URL 和标题 | | run_javascript(script) | 执行 JavaScript 代码 | | screenshot(annotate, full_page) | 截取屏幕截图 |

开发者工具

| 工具 | 描述 | | ---- | ---- | | get_console_logs() | 获取浏览器控制台输出 | | get_network_requests() | 获取 API 调用和响应 | | get_page_errors() | 获取 JavaScript 错误 | | run_in_console(code) | 在控制台执行 JavaScript 代码 | | inspect_element(id) | 检查元素的样式和属性 | | get_cookies() | 获取浏览器的 cookies 列表 | | set_cookie(name, value, ...) | 设置 cookie | | delete_cookie(name) | 删除 cookie | | clear_cookies() | 清除所有 cookies | | set_viewport(width, height) | 更改窗口大小 | | get_page_performance() | 获取页面加载时间和 Web 指标 |

录制功能

| 工具 | 描述 | | ---- | ---- | | start_recording() | 开始会话录制 | | stop_recording() | 保存录制内容 | | take_snapshot() | 保存屏幕截图和 HTML 内容 | | list_recordings() | 查看已保存的会话记录 |

配置

通过环境变量进行配置： | 变量 | 默认值 | 描述 | | ---- | ---- | ---- | | BROWSER_HEADLESS | true | 无界面运行浏览器 | | BROWSER_VIEWPORT_WIDTH | 1280 | 视口宽度（像素） | | BROWSER_VIEWPORT_HEIGHT | 720 | 视口高度（像素） | | BROWSER_TIMEOUT | 30000 | 导航超时时间（毫秒） | | BROWSER_USER_DATA_DIR | ~/.browsercontrol/user_data | 浏览器配置文件路径 | | BROWSER_EXTENSION_PATH | — | 浏览器扩展路径 | | LOG_LEVEL | INFO | 日志详细程度 |

示例：

# 以可见浏览器模式运行（用于调试）
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

🔧 故障排除

"Missing X server" 错误

设置 BROWSER_HEADLESS=true 或使用 xvfb 运行：

xvfb-run browsercontrol
浏览器无法启动

首次运行时会自动安装 Chromium，如果安装失败，请手动安装：

python -m playwright install chromium
会话无法持久化

检查 BROWSER_USER_DATA_DIR 是否可写：

ls -la ~/.browsercontrol/
连接被拒绝

确保没有其他实例正在运行：

pkill -f browsercontrol
browsercontrol
查看会话录制

在 Playwright 跟踪查看器中打开录制文件：

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

专为需要浏览网页的 AI 代理而构建。

⭐ 在 GitHub 上给项目加星 • 🐛 报告 Bug • 💡 请求新功能

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端