MCP 智能体接入

Sa2web MCP Server 将远程浏览器封装为标准 MCP 工具，使 Claude Code、Claude Desktop、Cursor、Windsurf、VS Code Copilot、Cline、Roo Code、opencode、Gemini CLI、Zed、Hermes Agent 和 OpenClaw 等客户端能够读取并操作网页。

MCP 项目已开源到 sa2web/sa2web-mcp，并以 @sa2web/mcp 发布到 npm。正常使用时请安装 npm 包；只有开发或调试时才需要克隆源码。

需要从终端直接操作远程浏览器时，请参阅远程浏览器 CLI。

目标网站显示在 iframe#rbi-frame 中。Server 通过 Playwright 控制该 iframe；智能体不会直接访问目标网站。

使用前准备

Node.js 18 或更高版本。
已全局安装 @sa2web/mcp，或为了开发而克隆了源码 checkout。
可用的远程浏览器智能体登录 URL。它通常包含 clientId 和 clientSecret，必须按密钥处理。
智能体账号已被授予所需 SaaS 站点、工作空间、内部站点和代理访问权限。

安装

全局安装已发布的 npm 包。安装后 sa2、sa2-browser 和 sa2-mcp 会出现在 PATH 中：

bash

npm install @sa2web/mcp -g
npx playwright install --with-deps

sa2-mcp 是 MCP 客户端使用的 stdio server 入口。sa2 和 sa2-browser 是用于终端调试和自动化的 CLI 入口。

源码开发时，请使用开源仓库：

bash

git clone https://github.com/sa2web/sa2web-mcp.git
cd sa2web-mcp
npm install
npx playwright install --with-deps
npm run build

源码构建会生成 dist/server.js。可运行 npm start 检查 server 是否能启动。MCP 使用 stdio，因此不会出现交互式界面。

配置 MCP 客户端

大多数客户端都支持下面的 mcpServers 格式。使用全局 npm 包时，直接调用 sa2-mcp：

json

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "sa2-mcp",
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

如果客户端无法解析全局命令，请使用 sa2-mcp 的完整路径，或指向源码构建产物：

json

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "node",
      "args": ["/absolute/path/to/sa2web-mcp/dist/server.js"],
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

Windows 应使用绝对路径，并在 JSON 中转义反斜杠，例如 E:\\sa2web-mcp\\dist\\server.js。

客户端	配置说明
Claude Code、Claude Desktop、Cursor、Windsurf、Cline、Roo Code	使用 `mcpServers`
VS Code Copilot	根字段是 `servers`
opencode	根字段是 `mcp`
Zed	根字段是 `context_servers`
Gemini CLI	添加到 Gemini CLI 的 `settings.json`
Hermes Agent	合并到 `~/.hermes/config.yaml` 的 `mcp_servers`
OpenClaw	合并到 Gateway 的 `mcp.servers`；启用 sandbox 时需放行 MCP 工具

保存后重启客户端。工具列表中出现 sa2_help、sa2_open_target 和 browser_snapshot 时，表示连接成功。

密钥安全

不要把真实 clientSecret 提交到 Git，也不要贴进文档。生产环境应通过 MCP 客户端或部署平台注入密钥；任何泄露的凭据都应立即轮换。

主要环境变量

变量	默认值	用途
`SA2_LOGIN_URL`	无	必填的智能体登录 URL；远程浏览器 origin 会从它推导
`SA2_LOGIN_REDIRECT_PATH`	`/app/login`	登录后的预期路径
`SA2_AUTO_LOGIN_BEFORE_NAVIGATE`	`true`	打开目标前自动登录
`SA2_HEADLESS`	`false`	是否以 headless 模式运行本地 Playwright 浏览器
`SA2_BROWSER`	`chromium`	`chromium`、`firefox` 或 `webkit`
`SA2_IGNORE_HTTPS_ERRORS`	`true`	是否忽略 HTTPS 证书错误；设为 `false` 时要求证书有效
`SA2_RBI_FRAME_SELECTOR`	`#rbi-frame`	目标页面 iframe selector
`SA2_RBI_FRAME_CONTENT_WAIT_MS`	`15000`	等待目标 iframe 内容的时间
`SA2_NAVIGATION_TIMEOUT_MS`	`45000`	导航超时
`SA2_ACTION_TIMEOUT_MS`	`15000`	操作和元素超时
`SA2_LOG_LEVEL`	`info`	`trace`、`debug`、`info`、`warn`、`error`、`fatal` 或 `off`
`SA2_LOG_STDERR`	`true`	将日志写入 stderr，把 stdout 留给 MCP stdio
`SA2_LOG_FILE`	无	可选的追加日志文件

不要配置已废弃的 SA2_REMOTE_BROWSER_PREFIX 或 SA2_REMOTE_BROWSER_BASE_URL。日志会自动脱敏密钥、密码、Cookie、Token 和 Authorization 字段。

工具分类

分类	工具
推荐入口	`sa2_help`、`sa2_list_available_targets`、`sa2_open_target`
读取	`browser_snapshot`、`browser_extract_text`
交互	`browser_click`、`browser_type`、`browser_press`、`browser_wait`、`browser_scroll`
表单与指针	`browser_fill_form`、`browser_select_option`、`browser_check`、`browser_uncheck`、`browser_hover`、`browser_drag`
文件与剪贴板	`browser_file_upload`、`browser_paste`
浏览器控制	`browser_navigate_back`、`browser_navigate_forward`、`browser_reload`、`browser_resize`、`browser_list_devices`、`browser_toggle_device`、`browser_handle_dialog`
输出与调试	`browser_screenshot`、`browser_take_screenshot`、`browser_evaluate`、`browser_run_code`、`browser_close`
高级兼容	`browser_open_login`、`browser_navigate`、`browser_list_proxies`、`browser_list_`、`browser_enter_`

完整工具参考

下表覆盖当前 server 注册的全部工具。参数均指 MCP arguments 对象。

工具	用途、关键参数和结果
`sa2_help`	无参数。返回推荐工作流、示例和兼容工具列表。适合作为智能体第一次调用。
`sa2_list_available_targets`	无参数。列出可访问代理、SaaS 站点、工作空间账号和内部站点，并返回稳定 `targetId`。
`sa2_open_target`	首选导航工具。用 `type=cloud`、`url`、可选 `surf` 打开公网 URL；或用 `targetId`、类型加 `id`/`name`、可选 `waitUntil` 打开已保存目标。返回匹配目标和加载/登录状态。
`browser_open_login`	打开 `SA2_LOGIN_URL`；可选 `waitUntil`。用于登录诊断，因为 `sa2_open_target` 通常会自动登录。
`browser_navigate`	兼容用公网 URL 导航。必填 `url`；接受 `surf` 和 `waitUntil`；返回远程 URL、所选代理和 frame/login 状态。
`browser_navigate_back`	无参数。点击远程浏览器工具栏后退按钮。之后应重新获取 snapshot。
`browser_navigate_forward`	无参数。点击工具栏前进按钮。之后应重新获取 snapshot。
`browser_reload`	无参数。通过工具栏刷新。旧 snapshot refs 必须丢弃。
`browser_list_proxies`	无参数。返回 free-browse 设置、原始代理数据和包含 `direct` 的 options。
`browser_list_saas_sites`	无参数。返回原始 SaaS 分类和扁平化 `sites` 列表。日常使用优先 `sa2_list_available_targets`。
`browser_enter_saas_site`	按可选 `id` 或 `name` 打开 SaaS 站点，可传 `waitUntil`。返回匹配站点和打开结果。
`browser_list_workspaces`	无参数。返回原始工作空间数据和账号级扁平 targets。
`browser_enter_workspace`	按 `accountId` 打开账号，或按 `siteId` 加 `username` 打开；可选 `waitUntil`。返回匹配账号。
`browser_list_inner_sites`	无参数。返回当前账号可访问的内部站点。
`browser_enter_inner_site`	按 `id` 或 `name` 打开内部站点；可选 `waitUntil`。返回匹配站点。
`browser_snapshot`	可选真实 CSS `filter`。返回目标 iframe 树的扁平语义快照。使用可操作 `ref=eN`；`id=tN` 和 `context=[tN]` 仅为文本引用。原始 URL 会被省略。
`browser_extract_text`	可选真实 CSS `selector`。从目标 iframe 树返回可见文本。Snapshot 文本 ID 不是 selectors。
`browser_click`	按 `ref`、CSS `selector`、`role`/`name`、可见 `text` 或成对 `x`/`y` 坐标点击。可能报告待处理 JavaScript dialog。
`browser_type`	必填 `text`；可按 `ref`、`selector` 或 textbox/searchbox/combobox 的 `role` 和 `name` 定位，否则使用当前聚焦编辑器。`append` 保留已有内容；`pressEnter` 输入后提交。
`browser_press`	必填 Playwright `key`，例如 `Enter`、`Escape`、`Tab` 或 `Control+A`。
`browser_press_key`	`browser_press` 的兼容别名，参数和行为相同。
`browser_wait`	按 `selector`、`text`、`urlIncludes` 或正数 `ms` 等待，默认 1000。条件按该优先级检查。
`browser_scroll`	滚动根页面或已定位元素。支持 `mode=by/to/intoView`、方向、距离、坐标、smooth 行为和对齐方式。无参数时向下滚动 600 px。
`browser_hover`	悬停到按 `ref`、`selector`、`role`/`name` 或 `text` 定位的元素。
`browser_drag`	从 `startRef`/`startSelector` 拖到 `endRef`/`endSelector`；起点和终点都必填。
`browser_fill_form`	必填 `fields` 数组。每个 field 包含定位信息和必填 `value`；按顺序填充并替换已有值。
`browser_select_option`	按 `ref` 或 `selector` 定位 `<select>`，再按 `values`、`value`、`label` 或从 0 开始的 `index` 选择。返回实际选中值。
`browser_check`	勾选按 `ref`、`selector`、`role`/`name` 或 `text` 定位的 checkbox 或 radio。
`browser_uncheck`	用相同定位方式取消勾选 checkbox；radio 不支持取消勾选。
`browser_file_upload`	按 `ref` 或 `selector` 定位文件 input；提供单个 `path` 或多个 `paths`。路径必须能被 MCP server 所在机器读取。
`browser_paste`	向已定位/聚焦目标粘贴 `text`、`html`、`rtf`、`path` 或 `paths` 的任意组合。文件 input 使用直接上传模式。返回 paste mode、types 和文件数。
`browser_handle_dialog`	接受或取消当前/待处理 alert、confirm 或 prompt。`accept` 默认 true；可选 `promptText` 和 `timeoutMs`。返回 dialog 详情。
`browser_resize`	必填正整数 `width` 和 `height`。调整桌面 viewport，或在当前设备模拟下用新尺寸重新应用模拟。
`browser_list_devices`	无参数且不会打开页面。列出 `Desktop` 和所有 Playwright 设备预设，包括 viewport、screen、DPR、mobile/touch flags 和默认浏览器类型。
`browser_toggle_device`	在不重建 context 的情况下切换设备模拟。接受 `enabled`、Playwright `device`、尺寸、`deviceScaleFactor`、`hasTouch`、`userAgent`、`orientation` 和 `reload`。`Desktop` 恢复桌面模式。返回预期 state、外层 `observed`、iframe `targetObserved` 和 warnings。
`browser_screenshot`	可选 `fullPage`，默认 `false`。以 MCP image content 返回 base64 PNG。
`browser_take_screenshot`	截图兼容别名；与上一个工具不同，`fullPage` 默认 `true`。
`browser_evaluate`	在 `iframe#rbi-frame` 中执行 `expression`，可传可序列化 `arg`，返回 JSON。权限较高；常规任务优先使用专用工具。
`browser_run_code`	使用 Playwright `page`、`rootFrame` 和 locator helpers 运行异步 JavaScript。必填 `code`；返回其 JSON 结果或 `null`。仅运行可信代码。
`browser_close`	无参数。关闭浏览器/context，并清空 refs、登录、dialog、CDP 和设备模拟状态。

设备切换示例

选择设备前先列出预设：

json

{ "name": "browser_list_devices", "arguments": {} }

启用预设且不丢失 Cookie 或登录状态：

json

{
  "name": "browser_toggle_device",
  "arguments": {
    "device": "Pixel 7",
    "orientation": "portrait"
  }
}

当后续请求必须携带新的 user agent 时，使用 reload: true。Chromium 会通过 CDP 覆盖 viewport、screen、DPR、touch、orientation 和 user-agent。Firefox 和 WebKit 只能动态调整 viewport，并会在 warnings 中说明限制。observed 和 targetObserved 可用于比较外层 shell 与目标 iframe。用 { "device": "Desktop" } 恢复之前的桌面 viewport；每次切换后都应重新获取 snapshot。

建议的智能体指令

text

Use the sa2-remote-browser MCP whenever web access is required.
For a public URL, call sa2_open_target with {"type":"cloud","url":"https://example.com"}.
For SaaS, workspace, or internal targets, call sa2_list_available_targets first and pass its targetId to sa2_open_target.
After opening, call browser_snapshot or browser_extract_text. Prefer snapshot refs for clicks and typing.
Obtain explicit user confirmation before publishing, submitting, deleting, purchasing, authorizing, transferring money, or sending messages.

排障

现象	解决方法
看不到 MCP 工具	构建项目；检查 `node` 和 `dist/server.js` 的绝对路径；重启客户端
登录失败	检查 `SA2_LOGIN_URL`、凭据和账号状态；必要时调用一次 `browser_open_login`
只看到工具栏	调用 `browser_wait`，或增大 `SA2_RBI_FRAME_CONTENT_WAIT_MS` 和 `SA2_LOGIN_SETTLE_MS`
找不到已保存目标	检查智能体账号的分组、站点、工作空间、内部站点和代理权限
操作找不到元素	重新获取 snapshot 并使用最新 `ref=eN`；不要把 `tN` 当 selector
stdio 连接错误	stdout 保留给 MCP；日志写到 stderr 或 `SA2_LOG_FILE`

MCP 智能体接入 ​

使用前准备 ​

安装 ​

配置 MCP 客户端 ​

主要环境变量 ​

推荐工作流 ​

工具分类 ​

完整工具参考 ​

设备切换示例 ​

建议的智能体指令 ​

排障 ​

MCP 智能体接入

使用前准备

安装

配置 MCP 客户端

主要环境变量

推荐工作流

工具分类

完整工具参考

设备切换示例

建议的智能体指令

排障