usable-browser-agent

可用的浏览器 Agent（免费个人使用／评估版）

一个 MCP 服务加浏览器扩展，可让你的 AI Agent（Claude Code、Codex 或任何 MCP 客户端）操控你自己的真实浏览器，使用你所有已登录的会话，而不是一次性自动化 浏览器。你只需手动登录一次，之后 Agent 就会以你的身份操作。

此代码库提供免费版：与商业版相同的单会话 MCP 服务，授权用于个人非商业用途，以及购买前评估产品。 配套的 Firefox 扩展已发布在 Firefox Add-ons 上。商业用途（用于商业活动、付费客户项目，或商业产品或服务中）需要商业版许可证，可一次性支付 $39 购买，网址为 https://savvytechsphere.com/usable-browser-agent，其中也包含 Chrome 版。购买后 14 天内可无条件退款。两个版本都没有许可证密钥，也不会检查许可证；两者的区别仅在于授权范围和扩展身份。

你的密码不会交给 Agent。 Agent 帮你登录时，只会传递一个秘密 别名，而不会传递密码本身。凭据保存在本地保险库中，受域名限制（在错误的网站上会被拒绝），并且会从 Agent 读取的所有内容和屏幕截图中删除。请参阅 docs/CREDENTIAL-SAFETY.md。

工作原理

Claude Code / Codex / any MCP client
      |  MCP over stdio
      v
  MCP server (Node, this repo)  --hosts-->  WebSocket  ws://127.0.0.1:8876
      ^                                          ^
      | 53 browser_* tools                       | (extension connects out)
      +------------------------------------------+
                                       Firefox extension (from Firefox Add-ons)
                                       your real profile, your logins -> DOM actions on the active tab

Agent 通过无障碍／DOM 快照感知页面，其中每个可交互元素都有稳定的 [ref=eN] 句柄，然后按 ref 点击和输入。无需猜测坐标，也不需要视觉模型。一切都在你的设备上运行：MCP 通过 stdio 通信，扩展通过绑定到 127.0.0.1 的 WebSocket 与服务通信。任何内容都不会离开你的电脑。

Agent 始终操作当前激活的标签页。请将你希望它使用的标签页保持为焦点。

快速开始（约 2 分钟）

需要两部分：由 Agent 启动的 MCP 服务，以及只需安装一次的 Firefox 扩展。

1. 获取服务并运行安装程序

需要 Node.js 18 或更高版本，以及 Firefox 142 或更高版本（目前优先支持 macOS；请参阅 docs/INSTALL.md）。

npm install -g usable-browser-agent
uba-install

也可以从此代码库的检出目录运行：

git clone https://github.com/Savvy-Tech-Sphere/usable-browser-agent-free.git
cd usable-browser-agent-free
node bin/uba-install.mjs        # or: npm run setup

（更喜欢下载？从 Releases 页面下载 zip 文件，解压后在文件夹中运行相同的命令。）

安装程序会检查 Node 和端口、安装依赖项、使用此副本的绝对路径向 Claude Code 和／或 Codex 注册 MCP 服务、运行冒烟测试、可选保存你的首次登录信息，并显示 macOS 权限设置步骤。安装程序支持幂等操作；重新运行不会覆盖现有配置。传入 --non-interactive 可接受所有默认选项。

2. 安装 Firefox 扩展（一次性操作）

从 Firefox Add-ons 安装 Usable Browser Agent (free)： https://addons.mozilla.org/firefox/addon/usable-browser-agent-free/

工具栏徽标起初显示 off，扩展连接到 Agent 启动的 MCP 服务后会显示 ON。（安装程序也会显示这些步骤，以及适用于商业版套装的 .xpi 和 Chrome 步骤；免费版只需使用 Add-ons 上的扩展即可。）

3. 登录并开始使用

登录你希望 Agent 使用的网站，然后让 Agent 执行浏览器任务，例如：“在当前标签页中，打开我的通知，列出正在等待我处理的拉取请求。” Agent 会先获取页面快照，然后按 ref 操作。

不使用安装程序，改为手动配置：

# Claude Code (user scope, works from anywhere afterward):
claude mcp add browser --scope user -e UBA_PORT=8876 -- node "$PWD/server/index.js"

# Codex: add to ~/.codex/config.toml (use the absolute path to your copy):
[mcp_servers.browser]
command = "node"
args = ["/ABSOLUTE/PATH/TO/usable-browser-agent-free/server/index.js"]

[mcp_servers.browser.env]
UBA_PORT = "8876"

获取帮助：docs/INSTALL.md、docs/TROUBLESHOOTING.md、 docs/UNINSTALL.md。

默认启用强化模式

除非你主动启用，否则 browser_eval（在页面中执行任意 JavaScript）处于关闭状态；密码字段附近也会阻止截图。对于 CAPTCHA、反机器人拦截页面和双重验证提示，系统会刻意避免自动处理：由于这是你屏幕上的浏览器，Agent 会请你介入。一次只能有一个活动标签页。

用法

1. 打开 Firefox 或 Chrome，登录你希望 Agent 使用的网站。
2. 确认扩展程序徽标显示 ON。
3. 让 Claude Code / Codex 执行某项操作，例如 “在活动标签页中搜索 X，并将第一个结果加入购物车。” 它会先截取页面快照，然后按引用执行操作。

工作流记忆

Usable Browser Agent 会保留本地工作流记忆，避免 Agent 每次都重新摸索不断变化的网站流程。这些记忆用于保存可复用的任务知识，例如“如何在 Google Play Console 中创建新应用”，包括当前页面名称、可见按钮标签、注意事项和已验证成功的步骤顺序。

默认文件：

~/.local/state/usable-browser-agent/workflow-memory.jsonl

使用 UBA_MEMORY_FILE=/path/to/workflow-memory.jsonl 覆盖默认设置。该文件为只追加的 JSONL 文件，创建权限为 0600。正常检索时，会忽略已被取代或已遗忘的记录。此记忆仅存储在你配置的本机和文件路径中；除非将多个 Agent 指向同一个受控文件，否则不会同步。

预期的 Agent 工作循环：

1. 在执行重复性或多步骤的网站任务之前，调用 browser_workflow_recall，并提供任务和／或网站。
2. 以匹配的记忆为起点，然后使用 browser_snapshot 根据当前页面进行核实。
3. 新路径或变更后的路径成功后，调用 browser_workflow_remember 保存持久有效的步骤。
4. 如果旧记忆有误，使用 supersedes: ["old_id"] 保存替代记录；如果应该从检索结果中移除，则调用 browser_workflow_forget。

当活动标签页的域名已有已保存的记忆时，browser_status、browser_info、browser_navigate 和 browser_snapshot 也会返回简短的工作流记忆提示。这些提示刻意保持简短；如需查看完整步骤，请调用 browser_workflow_recall。

不要保存密码、一次性验证码、不必要的原始账户标识符或临时的 [ref=eN] 句柄。记忆存储会拒绝包含临时引用的步骤，并通过删除查询字符串、替换路径中可能代表账户／应用／开发者 ID 的片段来清理已存储的 URL。请保存可见标签和页面／分区名称，因为每次快照后都会重新生成引用。

凭据代理

browser_login 和 browser_fill_secret 可让 Agent 触发登录，而无需接收凭据值。MCP 客户端只传递机密别名和元素引用。明文仅在以下环节流转：

secrets file -> MCP server -> local WebSocket -> browser extension -> DOM field

默认保险库文件为 ~/.config/usable-browser-agent/secrets.json；可通过 UBA_SECRETS_FILE=/path/to/secrets.json 覆盖。服务器会在需要时创建父目录，并在机密文件可被组用户或其他用户读取时发出警告；请将其权限设为 0600。

该文件是一个 JSON 数组：

[
  {
    "alias": "github",
    "domains": ["github.com"],
    "username": "[email protected]",
    "password": "replace-with-real-secret"
  }
]

domains 是允许的主机名。允许精确匹配和子域名匹配，因此 github.com 可匹配 gist.github.com，但不能匹配 evilgithub.com。

登录时，建议先获取快照，再使用原子化的填充并提交工具：

browser_login({
  "secret": "github",
  "username_ref": "e12",
  "password_ref": "e13",
  "submit_ref": "e14"
})

如果提供了 username_ref 且机密包含用户名，browser_login 会填充用户名，填充密码，然后通过一次扩展操作提交。如果省略 submit_ref，则会提交密码字段所属的表单；如果失败，则按 Enter 键作为后备方案。该工具只返回状态字符串，例如 logged in via [e14] 或 submitted form。

browser_fill_secret 仍可用于非登录流程：

browser_fill_secret({ "ref": "e12", "secret": "github", "field": "username" })
browser_fill_secret({ "ref": "e13", "secret": "github", "field": "password" })

该工具有意不提供 value 参数。如果当前标签页的主机不允许使用该别名，服务器会拒绝填充，且不会将值发送到浏览器。

读取回显和屏幕截图通过多层机制保护：

• 快照和 browser_get_value 会对密码字段以及由凭据代理填充的字段进行脱敏。
• 在代理填充或登录过程中、存在已填充的密码字段时，或者任意字段被标记为已填入机密时，browser_screenshot 都会被阻止。登录导航移除凭据字段后，即可再次截图。
• 服务器会按需加载保险库，并从所有出站工具结果中清除已配置的机密值，包括 browser_read_text 和 browser_eval 的结果。

强化模式默认开启：browser_eval（任意 JavaScript 逃生口）处于禁用状态；只要存在密码字段，即使字段为空，也会阻止截图。如果需要使用 browser_eval 逃生口，可在服务器环境中设置 UBA_STRICT_SECRETS=0 以退出强化模式。 对于 Claude Code，browser 已注册，而 claude mcp add 会拒绝已存在的名称，因此请移除并重新添加，同时将 UBA_PORT 保持为安装时使用的端口（在安装目录中运行）：

claude mcp remove browser --scope user && \
claude mcp add browser --scope user -e UBA_PORT=8876 -e UBA_STRICT_SECRETS=0 -- node "$PWD/server/index.js"

如果安装时设置了 UBA_SECRETS_FILE，还需在该命令中添加 -e UBA_SECRETS_FILE=<absolute path>，否则服务器会退回到默认保险库，导致已保存的登录凭据无法解析。重新运行安装程序会输出适用于你的安装的准确命令。

对于 Codex，请在 [mcp_servers.browser.env] 下添加 UBA_STRICT_SECRETS = "0"。重启 Agent，使服务器应用该设置。

截图阻止属于时间／状态保护机制。在其他内容仍会返回的图像中屏蔽凭据字段区域，是可能在 v2 中实现的功能，目前尚未实现。

工具（53）

工具	用途
browser_workflow_recall	开始重复性任务或涉及网站变更的任务前，搜索本地工作流记忆
browser_workflow_remember	保存已验证、可复用的工作流步骤、注意事项和持久的 UI 线索
browser_workflow_forget	将过时、敏感或不正确的工作流记忆标记为删除
browser_snapshot	包含 [ref=eN] 句柄的无障碍/DOM 树 — 主要的感知工具
browser_navigate / browser_back / browser_forward / browser_reload	导航
browser_click	按 ref 点击 — 支持右键/中键、双击以及 ctrl/shift/alt/meta 修饰键
browser_drag	将一个元素拖到另一个元素上（看板、可排序列表、滑块）
browser_type	按 ref 在字段中输入（可选的 submit = 按 Enter）
browser_fill_form	一次调用填写多个字段 [{ref,text}]
browser_fill_secret	使用服务端密钥别名填写用户名/密码
browser_login	使用服务端密钥别名原子化地填写用户名/密码并提交
browser_select	按标签/值选择一个 <select> 选项
browser_hover / browser_press_key / browser_scroll	指针和键盘操作（滚动窗口或特定容器；无限滚动时使用 to:'bottom'）
browser_upload_file	将本地文件附加到文件输入框或拖放区 — 无需使用操作系统文件选择器
browser_paste	从文本或剪贴板向元素发送真实粘贴事件（富文本编辑器）
browser_clipboard_read / browser_clipboard_write	读取/写入剪贴板文本
browser_clipboard_read_image / browser_clipboard_write_image	读取/写入剪贴板图片
browser_set_dialog_policy / browser_dialogs	自动响应 alert/confirm/prompt（绝不阻塞）；查看页面发出的请求
browser_mock_geolocation	让 navigator.geolocation 返回固定位置（跳过权限提示）
browser_download / browser_downloads_list	将 URL 下载到磁盘（无保存对话框），并获取本地路径
browser_save_pdf	将当前标签页保存为 PDF 到下载文件夹
browser_network_log	检查最近的网络请求（方法、URL、状态、错误）
browser_http_auth / browser_clear_http_auth	使用密钥别名响应原生 HTTP 基本身份验证提示
browser_read_text / browser_get_value	读取页面/元素内容
browser_wait / browser_wait_for_text	等待
browser_list_tabs / browser_select_tab / browser_new_tab / browser_close_tab	标签页
browser_status / browser_info / browser_screenshot	诊断和视觉备用方案
browser_native_status	报告操作系统级输入是否可用以及所需的任何设置
browser_os_type / browser_os_key	真实的操作系统可信按键输入（用于检查 isTrusted 的页面）；macOS
browser_os_click / browser_os_click_ref	真实的操作系统可信鼠标点击（按屏幕坐标或元素 ref）；macOS + cliclick
browser_native_dialog	检查/操作原生浏览器对话框（文件选择器、打印、基本身份验证、“离开页面？”）；macOS
browser_focus_browser	将 Firefox 切换到前台，以便进行操作系统级输入；macOS
browser_request_human_help	遇到 CAPTCHA / 反机器人墙 / 2FA 时转交给人工处理
browser_eval	在页面沙盒中运行 JS；在强化模式（默认）下禁用，可通过 UBA_STRICT_SECRETS=0 选择启用

覆盖范围

这套工具旨在让 Agent 能完成人类可以完成的任何浏览器任务：

1. 页面内交互（点击，包括右键、双击和修饰键点击，拖放、输入、对话框、容器滚动、剪贴板）——完全在页面内处理。
2. 浏览器级功能（无需保存对话框即可下载、另存为 PDF、HTTP 基本身份验证、网络检查、地理位置）——通过 WebExtension API 处理。
3. 最后一公里——原生浏览器界面（文件选择器、打印／身份验证对话框）以及要求操作系统信任的输入（event.isTrusted）的页面。MCP 服务运行在你的 Mac 上，因此 browser_os_* 和 browser_native_dialog 可操控真实键盘／鼠标和原生对话框。请参阅操作系统级输入。
4. 交由人工处理——我们不会自动处理 CAPTCHA 和反机器人拦截页面；browser_request_human_help 会通知你介入，因为这是你屏幕上的真实浏览器。

备注与限制

• 跨源 iframe：只要 Firefox 能将扩展内容脚本注入框架中，就可以支持；子框架中的引用会在内部添加前缀，并路由回对应框架。快照和操作也支持开放式 Shadow DOM。
• 特权页面（about:、addons.mozilla.org、PDF 查看器、view-source）无法由扩展脚本化，这是 Firefox 的设计限制。不过，操作系统级辅助进程（见下文）仍可在需要时于这些页面中输入／点击。
• 原生操作系统对话框（文件选择器、打印、基本身份验证提示）有三种处理方式：文件选择器无需打开（browser_upload_file 会直接设置输入框，而 browser_click 会拒绝文件输入框）；基本身份验证由 browser_http_auth 处理；其他情况可在 macOS 上通过 browser_native_dialog 操控。
• CAPTCHA／反机器人拦截页面不会自动处理。使用 browser_request_human_help 将操作交由你自己处理——这是你屏幕上的真实浏览器。
• 端口为 8876（UBA_PORT）。已发布的扩展会连接到此端口，因此免费版请保留默认值。
• 同一时间只能有一个浏览器／扩展连接；最新的扩展 hello 会生效（包括重新加载的情况）。端口上的裸套接字会被忽略，直到它们表明自己是扩展。
• UBA_BROWSER_APP_NAME（macOS，可选）：覆盖操作系统级输入工具在执行可信点击前要聚焦的应用程序。默认根据所连接的扩展版本，在 Firefox 或 Google Chrome 之间选择；对于非标准安装（Chromium、Chrome for Testing），请设置此项。如果无法聚焦显式指定的应用程序，操作系统级点击会明确报错，而不会点击当前最前面的窗口。
• MCP 服务本身不会接触 Cookie 或网络——它只会将结构化命令转发给扩展，由扩展在你的浏览器内执行。

操作系统级输入（macOS）

对于最后一公里——原生浏览器界面，以及通过检查 event.isTrusted 拒绝合成输入的页面——MCP 服务可以操控真实键盘和鼠标，因为它运行在你的 Mac 上（而不是扩展沙盒内）。这些工具包括 browser_os_type、browser_os_key、browser_os_click、browser_os_click_ref、browser_native_dialog 和 browser_focus_browser。

优先使用页面内工具（browser_click、browser_type 等）——它们更快、更可靠。只有在这些工具确实无法使用时，才使用操作系统级工具。

一次性设置：

1. 辅助功能权限（可信按键输入和原生对话框控制所需）： 系统设置 → 隐私与安全性 → 辅助功能 → 启用运行 MCP 服务的应用（终端、iTerm 或 IDE）。没有此权限，System Events 的按键输入会悄无声息地失效。
2. cliclick（仅原始坐标点击所需——browser_os_click*）：

   brew install cliclick
   

运行 browser_native_status（或 npm run native）查看可用功能。授予辅助功能权限后，可信按键输入和原生对话框控制即可使用；原始点击还需要 cliclick。

验证是否正常

npm run smoke    # MCP server boots, lists tools, bridge listens (no Firefox needed)
npm test         # credential-safety claims + workflow-memory unit tests (no Firefox needed)

安全

此工具可让 AI Agent 代表你在已登录的任何网站上执行实际操作。**仅登录你已批准用于此用途的低风险网站。**请将活动标签页视为实时环境：Agent 在其中能做的任何操作，都可能会执行。使用此工具时，请退出任何敏感账户（或不要打开相关网站）。

关于如何防止 Agent 获取凭据（仅使用别名登录、域名锁定、脱敏、强化模式），以及这些措施无法防范的风险，请参阅 docs/CREDENTIAL-SAFETY.md。

许可证与法律声明

Usable Browser Agent 是 Savvy Tech Sphere, LLC 的专有软件。此免费层受 LICENSE.txt 约束（供个人非商业使用和评估）。商业许可证一次性购买，价格为 39 美元，网址为 https://savvytechsphere.com/usable-browser-agent（记录销售方：Lemon Squeezy）；按现状出售，可自行购买，提供 14 天退款期，不提供个人支持。各层级所含内容的详情请见：docs/FREE-TIER.md。

• legal/ACCEPTABLE-USE.md：仅自动化你自己的账户；遵守各网站的条款
• legal/PRIVACY.md：此软件不收集任何信息；完全在你的计算机上运行

如有疑问，请通过 https://savvytechsphere.com/#contact 上的联系表单咨询。