Browser Automation

@mindstone/mcp-server-browser-automation

可供观察的浏览器控制：打开页面、登录、浏览页面、填写表单、截取屏幕截图，并保留可重复使用的浏览器会话。

最适用于实用的网页任务：用户需要查看、批准或重复使用浏览器状态，而不是运行完整的浏览器测试套件。

状态

• 版本： 0.2.3 · npm
• 身份验证： 无（server.json）
• 工具： 21（导航、观察、交互、会话、文件）
• 功能范围： 浏览器自动化
• 机器可读： STATUS.json

为什么要开发它

Microsoft 的 Playwright MCP 是用于广泛浏览器自动化和测试的可靠选择。这个连接器有意保持精简，并提供更高的可见性。

当助手需要以便于用户跟进的方式处理普通网站时，可以使用它：打开真实浏览器，让用户完成登录，浏览管理界面、填写表单、截取屏幕截图，并在之后回到同一会话。它的重点是建立信任并满足日常使用需求，而不是提供所有浏览器测试功能。

交互示例

“打开 https://example.com，告诉我页面标题，并截取屏幕截图。”

主机调用的工具：

1. browser_navigate — 在配置的浏览器会话中打开 URL。
2. browser_get_page_info — 返回当前 URL 和页面标题。
3. browser_screenshot — 截取 PNG 屏幕截图。

响应（节选）：

{
  "ok": true,
  "url": "https://example.com/",
  "title": "Example Domain"
}

要求

• Node.js 20+
• npm
• PATH 中有 agent-browser CLI，或者可使用 npx，以便服务自动安装它。

一键安装

点击按钮后，主机将提示你填写：AGENT_BROWSER_SESSION_NAME、AGENT_BROWSER_SHOW_WINDOW。

{
  "mcpServers": {
    "Browser Automation": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-browser-automation"
      ],
      "env": {
        "AGENT_BROWSER_SESSION_NAME": "mcp",
        "AGENT_BROWSER_SHOW_WINDOW": "true"
      }
    }
  }
}

快速开始

npx

npx -y @mindstone/mcp-server-browser-automation

或者全局安装：

npm install -g @mindstone/mcp-server-browser-automation
mcp-server-browser-automation

此服务需要 agent-browser CLI 二进制文件来控制浏览器。

二进制文件解析

1. PATH 查找（首选）：如果 agent-browser 位于 PATH 中，则直接使用。
2. npx 回退：如果找不到该二进制文件，服务会自动回退到 npx -y [email protected]。

安装 agent-browser

npm install -g agent-browser

也可以让 npx 回退方案自动处理（首次使用时需要下载，因此速度较慢）。

配置

无需 API 密钥或凭据。服务通过 agent-browser CLI 与浏览器通信。

MCP 主机配置

{
  "mcpServers": {
    "browser-automation": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-browser-automation"]
    }
  }
}

可用工具（21 个）

导航

• browser_navigate — 导航至 URL
• browser_back — 在浏览器历史记录中后退
• browser_forward — 在浏览器历史记录中前进
• browser_wait — 等待元素出现或等待指定时间

查看

• browser_snapshot — 获取包含交互元素引用的页面无障碍树
• browser_screenshot — 截取当前页面
• browser_get_page_info — 获取当前页面的 URL 和标题
• browser_get_text — 获取页面或单个元素的文本内容
• browser_pdf — 将当前页面保存为 PDF 到工作区目录中（除非设置 overwrite: true，否则不会覆盖现有文件）

交互

• browser_click — 使用 @ref 或 CSS 选择器点击元素
• browser_fill — 清空字段并填入文本
• browser_type — 逐字符输入文本（真实按键）
• browser_press_key — 按下键盘按键
• browser_scroll — 朝指定方向滚动页面
• browser_select — 从下拉菜单中选择选项
• browser_hover — 将鼠标悬停在元素上
• browser_upload — 将工作区文件上传到文件输入框（仅限普通文件；上传前会在私有区域暂存）
• browser_evaluate — 在页面上下文中执行 JavaScript（默认启用；destructiveHint: true，因此主机可以要求确认 — 请参阅安全说明）

会话管理

• browser_tabs — 列出打开的标签页或切换到某个标签页
• browser_close — 关闭浏览器会话
• browser_authenticate — 打开可见浏览器以便手动登录

工作流

典型工作流使用无障碍快照来可靠地定位元素：

1. browser_navigate → 打开页面
2. browser_snapshot → 查看带有 @ref ID 的交互元素
3. browser_click / browser_fill → 使用 @ref 引用进行交互
4. browser_screenshot → 进行视觉验证

安全说明

浏览器自动化的攻击面很大：agent-browser CLI 会控制真实的无头浏览器，加载你传入的 URL，运行页面端 JavaScript，并在多次运行之间持久保存 Cookie 和会话状态。部署前请阅读本节。

browser_evaluate 默认运行——主机确认是安全关卡

browser_evaluate 允许模型在页面上下文中执行任意 JavaScript——这在安全层面相当于让模型在刚刚导航到的网站上获得 shell。该工具会无条件注册（能力优先）；安全保障由主机的工具审批层提供。该工具标记为 destructiveHint: true，因此 MCP 主机应要求用户在每次调用前明确确认。请勿将主机配置为自动批准此工具。

URL 协议拒绝列表

browser_navigate 和 browser_authenticate 仅接受 http: 和 https: URL（以及特殊地址 about:blank）。在调用底层 agent-browser CLI 之前，其他 URL 协议都会被拒绝：

• file: — 可能会让页面读取本地文件系统路径
• chrome: 和 chrome-extension: — 浏览器内部页面和已安装的扩展
• javascript: — 等同于对当前文档调用 eval()
• data: — 内嵌由攻击者控制的 HTML/JS 载荷
• view-source: — 会绕过渲染内容的同源策略
• about: — 特权内部页面（about:config、about:cache、about:debugging，……）；仅允许 about:blank

Cookie 和会话持久化

连接器会通过 AGENT_BROWSER_SESSION_NAME（默认值：mcp）指示 agent-browser 使用具名持久会话。所有 Cookie、localStorage 数据，以及通过 browser_authenticate 完成的任何登录，都会以该会话名存储在磁盘上，并在后续运行中重复使用。任何能够读取会话存储的主体——本地用户、以相同用户身份运行的其他工具或备份——也都能使用这些已登录会话。

如需覆盖会话名（例如，为每个项目保留独立配置文件），请在主机的 MCP 服务配置中明确设置 AGENT_BROWSER_SESSION_NAME。如需清除状态，请通过 browser_close 关闭浏览器，并删除由 agent-browser 管理的会话目录。

推荐的部署方式

• 让连接器使用独立的浏览器配置文件——为每个 MCP 主机指定专用的 AGENT_BROWSER_SESSION_NAME。请勿重复使用日常浏览器配置文件：连接器会读取并覆盖其所指向配置文件中的 Cookie，而且恶意页面可能会借用你在任意网站上的现有登录会话。
• 要求主机确认 browser_evaluate——该工具默认运行；每次调用都会在页面上下文中执行任意 JavaScript。
• 要求主机确认 browser_authenticate 以及任何可能导航至已登录网站的流程——否则，抓取内容中的提示词注入可能会驱动浏览器访问用户已登录的网站。
• 返回的页面内容均封装为不可信内容——无障碍快照、页面文本、标题、URL、标签页列表以及 browser_evaluate 的输出都来自任意网站，可能包含提示词注入尝试。连接器会使用 <untrusted-content source="…"> 封装这些内容（并对闭合标签进行转义），以便主机和模型将其视为数据而非指令。请在你自己的处理流程中保留这种处理方式：不要移除这些封装，也不要仅凭页面文本触发不可逆操作。

文件工具的工作区沙箱

browser_pdf 写入 PDF 文件，browser_upload 读取文件，两者都受限于工作区目录：若设置了 MCP_WORKSPACE_PATH，则使用该路径；否则使用系统临时目录。使用前会对路径进行规范化，因此在 agent-browser CLI 运行前，会拒绝 .. 路径遍历、工作区外的绝对路径，以及指向工作区外的工作区内符号链接。显式设置 MCP_WORKSPACE_PATH，即可精确控制页面捕获文件的存放位置，以及模型可以附加到页面的文件。无法解析的 MCP_WORKSPACE_PATH 会触发安全失败：文件工具会拒绝运行，而不会退回到较弱的检查。

这两个工具都标记为 destructiveHint: true，因此宿主可以要求用户确认：对于文件输入发生变化时会立即提交的页面，browser_upload 可能触发即时远程上传；browser_pdf 则会写入本地文件。

其他加固措施：

• 暂存文件交接。 已验证的文件绝不会通过路径名重新打开。browser_upload 的源文件只打开一次（使用 O_NOFOLLOW + O_NONBLOCK，因此验证后替换叶节点符号链接会导致操作失败，预置的 FIFO 也无法卡住打开操作），并会验证其为常规文件（拒绝目录、设备和 FIFO），通过设备号和 inode 将其绑定到新的受限解析结果（验证后若中间目录被替换，解析路径会改变，操作将以 UPLOAD_SOURCE_CHANGED 错误被拒绝），然后将其复制到 CLI 使用的全新私有暂存目录。browser_pdf 会让 CLI 将文件写入全新的私有暂存目录，然后再将 PDF 安装到请求的路径：运行 CLI 前会固定目标目录的规范身份，并在安装前重新验证，因此若调用期间中间目录被替换为符号链接，操作将被拒绝；独占创建语义也会拒绝目标叶节点处已被植入的文件或符号链接，而不会通过它写入。
• 不会静默覆盖。 如果 file_path 已存在，browser_pdf 会返回 FILE_EXISTS 错误并拒绝操作，除非调用方显式传入 overwrite: true。即便如此，若目标是目录，也会被拒绝（DESTINATION_IS_DIRECTORY）——覆盖删除仅使用不递归的裸 unlink。
• 封装错误。 agent-browser CLI 的错误输出可能包含页面编写的文本；在发送给模型之前，会将其包裹在 <untrusted-content> 封装中（并对闭合标签进行转义以防止跳出封装），超时错误也不会回显命令的参数值。

许可证

FSL-1.1-MIT — Functional Source License，Version 1.1，未来转为 MIT 许可证。该软件将于 2030-04-08 转为 MIT 许可证。