Browser Control

BrowserControl

一个 MCP 服务，为你的 Agent 提供可视化浏览器。

_{一次真实会话，12 项操作，没有任何摆拍——导航、滚动、输入、选择、勾选、点击。注意这些编号：每次操作之后都会从头生成，因此 Agent 每次都要重新读取它们。}

核心思路

大多数浏览器工具会把 DOM 树交给模型，并寄希望于它能写出可用的选择器。 BrowserControl 则交给它一张图片。

每项操作都会返回一张新的屏幕截图，其中交互元素上绘有带编号的红框，并附上相同内容的文本列表。Agent 根据编号执行操作：

click(5)
type_text(3, "hello world")
upload_file(7, "/path/to/resume.pdf")

无需猜测选择器，也不用担心下一次改版就让选择器失效。这就是 标记集 模式：它作为主要交互界面，而非备用方案。

快速开始

uv add browsercontrol      # or: pip install browsercontrol

Chromium 会在首次运行时自行安装。如果安装失败，请运行一次 python -m playwright install chromium。

将客户端指向 browsercontrol 命令：

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

各客户端中该文件的位置

客户端	位置
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json（macOS） · ~/.config/Claude/claude_desktop_config.json（Linux） · %APPDATA%\Claude\claude_desktop_config.json（Windows）
Claude Code	claude mcp add browsercontrol -- browsercontrol
Cursor	设置 → Model Context Protocol
Cline	设置 → MCP Servers
Continue.dev	~/.continue/config.json，位于 mcpServers 下
Zed	~/.config/zed/settings.json，在 context_servers 下配置为 {"command": {"path": "browsercontrol"}}

如果愿意，也可以完全不安装："command": "uvx", "args": ["browsercontrol"]。

重启客户端，然后让它执行一项任务：

“打开 Hacker News，告诉我头条是什么。”

完整指南：入门。

唯一规则

元素编号在每次操作后都会失效。 每次点击、输入、滚动、导航和截图后，元素映射都会从头重新构建——点击前的元素 7，点击后几乎不会还是元素 7。

因此，Agent 不应根据一张截图规划两次点击。它应先操作、读取新截图、重新找到目标，再次操作。几乎所有值得排查的故障都与此有关。

由此可得两点：

• 只有视口内的内容才会标记。 通常没有编号就表示“在首屏以下”——先滚动，再查看。
• 跨源 iframe 永远不会被标记。 会遍历并编号开放的 Shadow Root 和同源 frame；第三方支付字段和嵌入式小组件则无法处理。这是浏览器的边界，并非 Bug。

工具

七个类别共 39 个工具。所有会操作页面的工具都会返回带注释的截图和元素映射。

类别		工具
导航	5	navigate_to go_back go_forward refresh_page scroll
交互	7	click click_at type_text press_key hover scroll_to_element wait
表单	3	select_option check_checkbox upload_file
内容	5	get_page_content get_text get_page_info run_javascript screenshot
标签页	4	create_tab switch_tab close_tab list_tabs
开发者工具	11	get_console_logs get_network_requests get_page_errors run_in_console inspect_element get_page_performance get_cookies set_cookie delete_cookie clear_cookies set_viewport
录制	4	start_recording stop_recording take_snapshot list_recordings

一些从名称中不容易看出的行为：

• type_text 使用 Playwright 的 fill()——它会替换字段内容，不会追加。
• click 会定位标记中心最上层的元素，因此，覆盖目标的 Cookie 横幅会拦截点击。请先关闭遮罩层。
• upload_file 使用 set_input_files，在无法通过操作文件选择器上传的站点上也能正常使用。
• screenshot(annotate=True, full_page=True) 会返回一张干净的图片——整页截图无法标记。
• get_page_content 会返回 Markdown，内容上限为 30 KB。
• 录制内容是 Playwright 跟踪文件。使用 npx playwright show-trace ~/.browsercontrol/recordings/<name>.zip 打开。

教会你的 Agent 如何更好地使用它

连接服务会告诉 Agent 存在哪些工具。随附的 Agent 技能会告诉它如何更好地使用这些工具—— 数字会过期，横幅会拦截点击，缺少数字则表示需要滚动。

mkdir -p ~/.claude/skills/browsercontrol
curl -fsSL https://raw.githubusercontent.com/adityasasidhar/browsercontrol/main/skills/browsercontrol/SKILL.md \
  -o ~/.claude/skills/browsercontrol/SKILL.md

只有任务确实涉及浏览器时才会加载，因此其他时候只占用一行上下文。想直接阅读文档的 Agent 可以从 llms.txt 开始。

配置

启动时读取一次的环境变量。

变量	默认值
BROWSER_HEADLESS	true	设置为 false 可观察浏览器运行情况
BROWSER_VIEWPORT_WIDTH	1280
BROWSER_VIEWPORT_HEIGHT	720
BROWSER_TIMEOUT	30000	导航超时时间，单位：毫秒
BROWSER_USER_DATA_DIR	~/.browsercontrol/user_data	配置文件目录
BROWSER_EXTENSION_PATH	—	启动时加载的已解压扩展
BROWSER_EXECUTABLE_PATH	—	要驱动的 Chromium 二进制文件，适用于 Playwright 未提供当前平台构建版本的情况
BROWSER_RECORDINGS_DIR	与配置文件同目录	保存跟踪记录的位置
BROWSER_SNAPSHOTS_DIR	与配置文件同目录	保存快照的位置
LOG_LEVEL	INFO

BROWSER_HEADLESS=false BROWSER_VIEWPORT_WIDTH=390 BROWSER_VIEWPORT_HEIGHT=844 browsercontrol

为什么选择它

会话使用真实的 Chromium 配置文件（launch_persistent_context），因此 Cookie、 localStorage 和登录状态会在重启后保留——登录一次，Agent 就能一直保持登录状态。DevTools 是一等功能：控制台、网络计时、未捕获的异常、性能和计算样式都是工具，而非事后补充。而且它完全在你的设备上运行——不需要大模型 API 密钥，不经过云端往返，没有单次操作费用，也没有任何内容离开本机。

客观来说：如果你愿意操作无障碍树，Playwright MCP 非常出色。如果你想让大模型为你规划交互，可以看看 Stagehand 或 Browser-Use。BrowserControl 专注于视觉优先、完全本地运行且内置 DevTools 的浏览器控制。更详细的比较请参阅 文档。

开发

git clone https://github.com/adityasasidhar/browsercontrol
cd browsercontrol
uv sync
uv run playwright install chromium --with-deps

uv run pytest                                  # tests (Playwright is mocked — no real browser)
uv run ruff check . && uv run ruff format .    # lint + format
uv run fastmcp dev browsercontrol/server.py    # dev server with the MCP inspector

browsercontrol/
├── server.py     # FastMCP instance, lifespan, tool registration
├── browser.py    # BrowserManager: Playwright lifecycle, element detection, SoM rendering
├── config.py     # env-var config
└── tools/        # one module per category, each exporting register_*_tools(mcp)

CI 会在 Ubuntu、Windows 和 macOS 上使用 ruff、mypy --strict、 bandit 和 pytest 运行测试套件。

贡献

欢迎提交问题和 PR——请参阅 CONTRIBUTING.md。新增工具应同时为正常路径和错误路径编写测试；现有的 tests/test_*.py 文件展示了相应模式。

如果你在寻找入手方向，可以考虑：支持 Firefox 和 WebKit、移动设备预设、网络模拟、快照间的 DOM 差异比较，以及无障碍审计。

许可证

MIT。基于 FastMCP 和 Playwright 构建。