浏览器控制GUI 自动化AI Agent人工智能MCP 服务AI 技能【免费下载链接】browser-harnessBrowser Harness | Self-healing harness that enables LLMs to complete any task.项目地址https://gitcode.com/gh_mirrors/br/browser-harness点击查看免费下载browser-harness-mcp是 Browser Harness 项目提供的一个 MCPModel Context Protocol服务器入口它把browser_harness.helpers中的浏览器控制函数直接暴露为 MCP 工具让 Claude Code、Devin、Cursor、OpenClaw 等任何支持 MCP 的客户端都能通过标准 stdio 协议驱动真实的 Chrome/Chromium 浏览器。读完本文你将掌握 MCP 服务器的启动方式、全部browser_工具的参数与返回结构、四种主流客户端Claude Code / Devin / Cursor 等 / MCP Inspector的配置写法以及它如何复用既有 daemon 与 CDP 通道完成从开标签页到录屏的完整自动化闭环。本指南以 docs/MCP.md 为骨架并结合仓库源码src/mcp_server.py、src/browser_harness/helpers.py、tests/unit/test_mcp_server.py补充底层实现细节。一、架构定位只复用 helper 层零重复实现MCP 服务器的核心设计哲学在文档第一段就写得很清楚它只是把browser_harness.helpers暴露为 MCP 工具复用既有 helper 层——不引入第二套 CDP 实现也不改动src/browser_harness/内部任何代码。从源码结构看这条复用路线体现在三层入口层pyproject.toml 将browser-harness-mcp browser_harness.mcp_cli:main注册为 console scriptCLI 层src/browser_harness/mcp_cli.py 是一个极薄的转发器负责动态导入真正的服务器模块mcp_server。值得注意的错误处理如果mcp依赖缺失它会提示安装pip install browser-harness[mcp]并退出——这正是 tests/unit/test_mcp_cli.py 中验证的行为服务器层src/mcp_server.py 导入browser_harness.helpers中的 22 个函数用_tool装饰器逐个包装成 MCP 工具。MCP 工具集的 Python 依赖通过 optional dependency 引入mcp [mcp2.1.1]见 pyproject.toml。这也是为什么安装时要用[mcp]extra。需要明确的前提本地浏览器的控制仍然依赖 daemon 连接本地 Chrome 的 CDP 端点9222/9223 端口这与browser-harnessCLI 的本地模式完全一致。二、启动服务器一条命令从任意目录运行MCP 服务器走 stdio 协议可以从任意目录直接启动uvx --from browser-harness[mcp] browser-harness-mcp这条命令做了三件事用uvx临时拉取browser-harness[mcp]含 MCP 可选依赖并执行其中的browser-harness-mcp入口服务器在stdio上与客户端通信即标准的 MCP stdio transportJSON-RPC 消息走标准输入输出首次调用任意工具时daemon 会自动启动连接到与browser-harnessCLI 相同的本地 Chrome CDP 端点9222/9223。如果你正在本仓库的开发检出中工作可以用等价的本地命令运行同一个打包入口针对当前源码uv run --extra mcp browser-harness-mcp也可以直接以模块方式运行uv run python -m mcp_server后者对应 src/mcp_server.py 中的main()构造SERVER并调用SERVER.run()。关于 MCP 协议通道的两个实现细节从 src/mcp_server.py 的_stderr_stdout上下文管理器可以看到部分 helper如start_recording、stop_recording会向 stdout 打印状态信息。在 MCP stdio 模式下任何非 JSON-RPC 的 stdout 输出都会破坏线协议因此服务器在执行 helper 期间会把 stdout 重定向到 stderr让这些状态信息进入客户端日志而不污染协议通道。另外src/mcp_server.py 的_normalize与_json_default组合保证了任何 helper 返回值都能被安全地序列化为 JSON 文本非有限浮点数NaN/Infinity被归一化为nullbytes按 UTF-8 解码、datetime转 ISO 格式、Decimal转 float、Path转字符串。这样browser_js等工具返回的 JS 值无论多奇怪都不会让 JSON-RPC 响应序列化崩溃。三、完整工具清单23 个browser_前缀工具browser_harness.helpers中的浏览器控制函数全部被暴露为带browser_前缀的 MCP 工具共 23 个工具名参数默认值返回值要点browser_new_taburlabout:blank{targetId: ...}browser_gotourl导航结果browser_page_info—url、title、viewport/滚动/页面尺寸browser_clickx,y,buttonleft,clicks1{ok: true}browser_typetext{ok: true}browser_fillselector,text,clear_firstTrue{ok: true}browser_presskey,modifiers0{ok: true}browser_scrollx,y,dy-300,dx0{ok: true}browser_screenshotpathNone,fullFalse,max_dimNonepath、width、height、size_bytesbrowser_list_tabs—标签页列表browser_current_tab—当前targetId、url、titlebrowser_switch_tabtarget{sessionId: ...}browser_close_tabtargetNone{ok: true}browser_ensure_real_tab—真实标签页信息browser_waitseconds1.0{ok: true}browser_wait_for_loadtimeout15.0{ok: bool}browser_wait_for_elementselector,timeout10.0,visibleFalse{ok: bool}browser_jsexpression,target_idNoneJS 求值结果browser_cdpmethod,paramsNone原始 CDP 返回browser_upload_fileselector,path{ok: true}browser_http_geturl,timeout20.0,headersNone{text: ...}browser_start_recordingnameNone,titleNone{recording_dir: ...}browser_stop_recording—{recording_dir: ...}错误约定每个工具都返回 JSON 文本出错时响应为{error: ...}且服务器进程保持运行不会因单个工具失败而退出。测试 tests/unit/test_mcp_server.py 从另一个角度验证了这一点当 helper 内部抛错如RuntimeError服务器会通过 MCP 的tool-error 通道上报Error executing tool browser_page_info: 原因客户端可通过is_error标志感知失败。逐组解读工具参数结合源码导航与页面browser_new_tab对应new_tab(url)。源码 helpers.py 显示若当前附加标签页还是空白页about:blank、chrome://newtab等会直接复用并在其上导航否则先Target.createTarget创建后台空白页再附加。browser_goto对应goto_url(url)Page.navigate。设置BH_DOMAIN_SKILLS1时导航后还会附带返回该站点最多 10 个领域技能文件名。browser_page_info返回{url, title, w, h, sx, sy, pw, ph}——即 viewport 宽高、滚动偏移与页面完整宽高。若页面弹出了原生对话框alert/confirm 等则返回{dialog: ...}结构见 helpers.py。输入browser_click(x, y, button, clicks)在视口坐标上派发mousePressedmouseReleased两次 CDP 事件。设置BH_DEBUG_CLICKS1时会在点击前截屏并叠加红色十字标记便于调试坐标。browser_type(text)走Input.insertText插入到当前聚焦元素。browser_fill(selector, text, clear_firstTrue)专门处理 React/Vue/Ember 等框架受控输入聚焦 → 全选清除 → 真实按键输入 → 最后派发合成inputchange事件让框架状态同步见 helpers.py。browser_press(key, modifiers)的modifiers是位掩码1Alt2Ctrl4Meta(Cmd)8Shift。支持 Enter/Tab/Backspace/方向键等命名键也支持可打印字符自动补 Shift 修饰。视觉browser_screenshot(path, full, max_dim)省略path时写入临时文件fullTrue用captureBeyondViewport截整页max_dim会把超过该尺寸的长边等比缩小对 2× 高分屏建议 1800可把文件控制在部分视觉 LLM 的 2000px 限制内。返回path、width、height、size_bytes四项。标签页管理browser_switch_tab(target)接受targetId或 URL 子串返回附加后的sessionId。注意默认只是附加到该标签页不会改变 Chrome 可见的当前标签activateTrue才可见切换且切换时会把标签标记移动到新附加标签。browser_ensure_real_tab()用于当前标签是chrome://等内部页或已失效时自动切到第一个真实用户标签。等待browser_wait_for_load(timeout)轮询document.readyState completebrowser_wait_for_element(selector, timeout, visible)轮询querySelector是否出现visibleTrue时额外用checkVisibility含祖先链、display:none/visibility:hidden/opacity:0判断要求元素真正渲染可见。高级browser_js(expression, target_id)在当前标签或通过iframe_target()定位的 iframe执行 JSawaitPromiseTrue若顶层return非法会自动包一层函数重试。browser_cdp(method, params)任意原始 CDP 方法params以 kwargs 传入如browser_cdp(Emulation.setFocusEmulationEnabled, params{enabled: True})。browser_upload_file(selector, path)通过DOM.setFileInputFiles为文件输入设置本地文件path需为绝对路径。browser_http_get(url, timeout, headers)不走浏览器的纯 HTTP GET设置了BROWSER_USE_API_KEY时自动走 fetch-use 代理含反爬、住宅代理与重试否则回退本地urllib。四、典型调用流程示例文档给出的标准流程三步即可完成开页 → 等加载 → 取证1. browser_new_tab(urlhttps://example.com) 2. browser_wait_for_load() 3. browser_screenshot() → 返回 path、width、height、size_bytes 4. browser_page_info() → 返回 url、title、viewport/scroll/page size一个完整的驱动真实浏览器会话可以这样组织开页browser_new_tab(urlhttps://example.com)—— 首次导航必须用new_tab而非goto因为 daemon 跨 CLI 调用保持附加标签页状态等待browser_wait_for_load(timeout15.0)SPA 场景补充browser_wait_for_element(selector..., visibleTrue)交互browser_fill(selector#search, textbrowser harness)→browser_press(keyEnter)验证与取证browser_screenshot()拿截图路径与尺寸browser_page_info()拿 url/title/滚动位置收尾browser_close_tab()关闭任务创建的标签页。五、客户端配置Claude Code / Devin / Cursor 等 / MCP InspectorClaude Codeclaude mcp add browser-harness \ uvx --from browser-harness[mcp] browser-harness-mcpDevindevin mcp add -s project browser-harness -- \ uvx --from browser-harness[mcp] browser-harness-mcpCursor / OpenClaw 及其他 MCP 客户端这些客户端通常读取 JSON 格式的 MCP 配置写入对应客户端的 MCP 配置文件即可{ mcpServers: { browser-harness: { command: uvx, args: [ --from, browser-harness[mcp], browser-harness-mcp ] } } }MCP Inspector调试/浏览工具清单MCP Inspector 是官方交互式调试器可以浏览已注册的工具、查看 schema 并手动调用npx modelcontextprotocol/inspector \ uvx --from browser-harness[mcp] browser-harness-mcp仓库检出模式在仓库检出目录中uv run --extra mcp browser-harness-mcp会用当前源码运行同一个打包入口——适合二次开发或验证未发布的改动。六、工作原理与工程实践要点一次连接、处处复用MCP 服务器与browser-harnessCLI 共享同一套 daemon 与 CDP 通道。本地模式下连接的是同一个 Chrome 实例9222/9223 端点daemon 在第一次工具调用时自动拉起——这意味着你已经打开并授权过的浏览器会话、登录状态、扩展都能被 MCP 工具直接使用。单文件服务器整个服务器实现集中在 src/mcp_server.py约 300 行。_tool装饰器L116-L135是核心抽象每次调用先ensure_daemon()保证 daemon 存活再执行 helper任何异常包括 daemon 启动失败都转成 MCP 的ToolError让浏览器故障以标准 MCP 错误语义到达客户端。无状态且健壮工具参数通过functools.wraps保留原始函数签名因此客户端看到的工具 schema 与 Python 函数参数注解一一对应返回一律 JSON 文本失败不会杀死服务器进程。何时不该用浏览器browser_http_get之外的纯 HTTP 抓取场景公开 API、静态页优先考虑browser_http_get或直接curl不要把 MCP 服务器当作通用抓取器使用只有需要点击、输入、登录会话、JS 渲染或反爬页面时才动用浏览器工具参见 SKILL.md 的 When Not to Use 说明。七、故障排查速查入口提示安装 mcp说明当前环境没有browser-harness[mcp]的 MCP 依赖按提示执行pip install browser-harness[mcp]或改用uvx --from browser-harness[mcp]。工具调用报错先看返回的{error: ...}或客户端 tool-error 内容多数浏览器级错误daemon 连不上、CDP 超时、元素未找到都能从错误文本直接定位。连不上本地 Chrome确认chrome://inspect/#remote-debugging已勾选允许远程调试或用browser-harness --doctor走一遍连接诊断详见 install.md 的两种连接方式。记录功能若browser_start_recording/browser_stop_recording异常注意 fresh install 默认不记录需先用browser-harness recordings enable开启详见 SKILL.md。八、从 MCP 看 Browser Harness 的整体设计MCP 服务器是一个可编辑 CDP 通道直连 LLM 与真实浏览器理念的自然延伸CLI 模式用 heredoc 内嵌 Python 调用 helper见 SKILL.mdMCP 模式则把同一批 helper 标准化为 JSON-RPC 工具。两条路径共享browser_harness.helperssrc/browser_harness/helpers.py与 daemon 层因此没有第二套浏览器控制实现需要维护——这是文档明确强调、源码完整印证的核心约束。进一步阅读完整技能说明见 SKILL.md本地 Chrome / 远程浏览器 / 页面工作流 / 录屏等细节可参考 src/browser_harness/SKILL.md 与 interaction-skills 目录下的专项文档MCP 相关测试见 tests/unit/test_mcp_server.py 与 tests/unit/test_mcp_cli.py。赞分享浏览器控制GUI 自动化AI Agent人工智能MCP 服务AI 技能【免费下载链接】browser-harnessBrowser Harness | Self-healing harness that enables LLMs to complete any task.项目地址https://gitcode.com/gh_mirrors/br/browser-harness点击查看免费下载相关推荐QMD MCP Server 完整配置指南让 Claude、OpenClaw 与任意 MCP 客户端接入本地文档搜索引擎QMD MCP Server 完整配置指南让 Claude、OpenClaw 与任意 MCP 客户端接入本地文档搜索引擎 导读 QMDQuick Markd人工智能大模型RAG搜索引擎本地部署MCP 服务CLIPuter MCP Connector 实战指南用 Cloudflare Workers 把个人 Puter 账号接入任意 MCP 客户端Puter MCP Connector 实战指南用 Cloudflare Workers 把个人 Puter 账号接入任意 MCP 客户端 Puter MCP后端前端云原生A2UI over MCP 完整实战指南用 MCP 工具与资源为任意客户端提供可交互 A2UI 界面A2UI over MCP 完整实战指南用 MCP 工具与资源为任意客户端提供可交互 A2UI 界面 本篇指南以 A2UI 仓库中的官方教程 docs/pub人工智能AI AgentAI 应用前端UI组件上一篇从毫秒到万级TPSSeaTunnel Connector性能基准测试全解析下一篇如何快速上手鲁班H510分钟搭建专业级移动页面的终极教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
