BrowserDo

BrowserDo

为 AI Agent 打造，与人共享。

Embiody 是一款 Windows 浏览器，AI Agent 可在后台全速使用它，同时你可以继续使用电脑，并随时介入。BrowserDo 是将你的 Agent 连接到它的 MCP 服务。将它添加到 Claude Code、Claude Desktop、Codex、Cursor、VS Code 或 Gemini CLI 后，你的 Agent 就能浏览、点击、输入和读取页面，包括你已登录的网站。

为什么选择 BrowserDo

1. 在后台全速运行，把屏幕留给你

页面在后台标签页、后台窗口、最小化窗口和隐藏窗口中都能全速运行。你的 Agent 不需要让浏览器显示在你面前，因此它工作时你仍可使用电脑，而且它可以同时在十几个标签页中工作。

普通的 Chrome 会降低你未查看页面的运行速度。在我们的测试中，一个浏览器窗口被另一个窗口完全遮挡了 7 分钟：

	计时器	页面上的倒计时
Embiody，前台标签页	全程每秒 10 次	准时
Embiody，后台标签页	全程每秒 10 次	准时
Chrome，前台标签页	12 秒后开始变慢	延迟 355 秒

无需启动标志即可实现这一点。一个限制是：如果页面在窗口最小化时打开，恢复后可能没有截图；但页面文本和元素编号仍然可用。

2. 在机器人会被拦截的地方也能正常工作——因为它不是机器人

你的 Agent 代表你在自己的浏览器中工作，因此网站会像对待你一样对待它，并应用反机器人保护。

3. 查看完整页面并点击正确的元素

• 可以读取并点击其他网站的嵌入式框架中的内容，例如付款表单和登录框。
• 被弹窗或覆盖层遮挡的元素不会获得编号，因此 Agent 无法点击你看不到的内容。
• 长页面会完整读取，而不只是屏幕上显示的部分。
• 点击屏幕外的元素前，会先滚动到该元素所在位置。
• 在多台显示器和任何显示缩放设置下，点击都能准确落在目标位置。
• 每个元素编号都只属于一个快照。旧快照中的编号会在点击前被拒绝，不会误点后来占据该位置的元素。

4. 你可以查看 Agent 正在做什么

Agent 操作的标签页会显示虚拟鼠标指针、页面边框和标签页标记。你可以随时打开查看。

5. 你和 Agent 共用一个浏览器，互不干扰

如果你在 Agent 正在操作的标签页中点击或输入，系统会询问你是否要接管。Agent 在操作你的标签页前也会先询问。

6. 一次调用执行多个步骤

browser_batch 会依次执行多个操作（点击、输入、按键），并返回页面的最新快照，因此 Agent 需要更少的往返调用和更少的令牌。

7. 直接读取页面，而非摘要

browser_read_pages 会返回页面本身的文本（包括链接），既能读取由脚本生成的页面，也能读取你已登录网站的页面。它可以替代 Claude Code 的 WebFetch；后者返回的是由模型生成的简短摘要。在我们对 8 个页面的比较中，BrowserDo 读取了 WebFetch 无法获取的 BBC News 文章，并在约 20 秒内并行读取了全部 8 个页面。

8. 查看浏览器自身的弹窗

权限提示气泡、菜单、“另存为”对话框、“离开网站？”提示和警告信息都会出现在每个快照中，并附有相应的处理方式。

9. 使用当前引擎，发布经过签名的版本

基于 Chromium 156 构建。发布版本均经过签名，浏览器会自行更新，并检查每次更新的签名。

要求

• Windows 10 或 11，64 位（Embiody 目前仅支持 Windows）
• Node.js 20 或更高版本。使用 node -v 检查。若未安装，BrowserDo 将无法启动（Claude Code 会显示 “Failed to connect”）。使用 winget install OpenJS.NodeJS.LTS 安装，然后重启客户端。
• Embiody 浏览器，版本 0.9.0.3 或更高：BrowserDo 首次启动时会自动安装。下载内容约为 140 MB，需要几分钟；客户端可立即使用 BrowserDo，在浏览器准备就绪前，每个工具都会回复安装进度。若版本较旧，BrowserDo 会打开浏览器的更新页面，并提示你在更新完成后重启浏览器和 BrowserDo （详情）。

无需 API 密钥。你的 Agent 使用自己的模型驱动浏览器。

安装

BrowserDo 以 npx -y browserdo-mcp 运行。选择你的客户端，只需按照对应部分操作；其他部分适用于其他客户端。

Claude Code

claude mcp add browserdo -- npx -y browserdo-mcp

添加 --scope project，即可通过 .mcp.json 与团队共享；或者添加 --scope user，即可在每个项目中使用。

Claude Desktop

编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "browserdo": {
      "command": "npx",
      "args": ["-y", "browserdo-mcp"]
    }
  }
}

Codex

codex mcp add browserdo -- npx -y browserdo-mcp

或者添加到 ~/.codex/config.toml：

[mcp_servers.browserdo]
command = "npx"
args = ["-y", "browserdo-mcp"]

Cursor

添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "browserdo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "browserdo-mcp"]
    }
  }
}

VS Code

从命令面板运行 MCP: Add Server，选择 Command (stdio)，并输入 npx -y browserdo-mcp。或者添加到 .vscode/mcp.json：

{
  "servers": {
    "browserdo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "browserdo-mcp"]
    }
  }
}

Gemini CLI

添加到 ~/.gemini/settings.json（所有项目）或 .gemini/settings.json（单个项目）：

{
  "mcpServers": {
    "browserdo": {
      "command": "npx",
      "args": ["-y", "browserdo-mcp"]
    }
  }
}

其他 MCP 客户端

在客户端设置中添加本地（stdio）MCP 服务，命令为 npx，参数为 -y browserdo-mcp。大多数客户端使用以下格式：

{
  "mcpServers": {
    "browserdo": {
      "command": "npx",
      "args": ["-y", "browserdo-mcp"]
    }
  }
}

然后让你的 Agent 在网上执行操作：

帮我查找下周三早上从悉尼直飞墨尔本的航班，并列出最便宜的三个选项。

工具

每个工具对应一个浏览器操作。windowId 和 tabId 均为可选参数；省略时将使用最前面的窗口和标签页。

工具	功能
browser_take_snapshot	将页面内容整理为逐元素的一行文本，每个可交互元素带有编号；同时提供页面位置、URL、标题、遮挡页面的弹窗，以及 snapshotId。如果页面是 PDF、错误页或崩溃的标签页，也会说明。includeImage 会添加带注释的截图；readWholePage 会读取屏幕以外的内容。
browser_read_pages	在后台标签页中一次读取最多 10 个页面，并获取页面文本，链接以脚注形式列出。
browser_batch	在一个标签页中依次执行多个操作，然后获取最新快照。遇到第一个失败操作或会更改页面的步骤后即停止。
browser_click、browser_input_text、browser_press_key、browser_select_editable_text、browser_scroll	根据元素编号及其对应的 snapshotId 对元素执行操作。browser_input_text 还可以在由周围文字指定的位置进行编辑。
browser_move、browser_drag	悬停；按下、拖动并释放。拖动适用于滑块、画布和可重新排序的列表。
browser_navigate、browser_go_back、browser_go_forward、browser_reload、browser_stop_loading、browser_wait	浏览页面。
browser_get_window_info、browser_new_window、browser_close_window、browser_show、browser_minimize	窗口操作。browser_get_window_info 会列出所有窗口和标签页及其 ID。
browser_new_tab、browser_select_tab、browser_close_tab、browser_set_audio_muted	标签页操作。
browser_close_popup_bubble	响应权限提示气泡或对话框。
browser_start_human_control、browser_stop_human_control	将标签页交给用户输入密码或完成验证码，然后收回控制权。
browser_status	查看浏览器是否就绪，或查看首次安装的进度。

设置

在客户端配置的 env 块中设置这些变量，或将它们放入配置文件（将 browserdo.config.example.yaml 复制到服务运行目录旁，并重命名为 browserdo.config.yaml，或传入 --config <path>）。环境变量的优先级高于配置文件。

变量	作用
EMBIODY_TOOLS	browser（上述工具）、task（仅 browser_run_task）或 all（默认值）。
EMBIODY_SAVE_SNAPSHOTS	设置为 1 后，会将每个快照的屏幕截图和页面文本保存在 run/browser_data 下，方便调试。默认关闭。
EMBIODY_EXE_PATH	启动你自己的 Embiody 版本，并使用独立配置文件夹，而非已安装的版本。
EMBIODY_USER_DATA_DIR	为 Agent 指定独立的配置文件夹，而非使用你自己的 Embiody；随后 BrowserDo 会在该文件夹中启动自己的浏览器。
EMBIODY_VLLM_ENDPOINT、EMBIODY_VLLM_MODEL、EMBIODY_VLLM_API_KEY	browser_run_task 使用的模型（见下文）。

示例配置文件还说明了其余设置：备用模型、超时时间，以及页面等待稳定的时长。使用 --transport sse 时，MCP 将通过 HTTP 在 http://127.0.0.1:3000/sse 上提供服务；该服务仅响应本机请求。

隐私

BrowserDo 不会收集遥测数据、使用统计信息或错误报告。

• 下载：首次启动时，如果未安装 Embiody，它会从 GitHub 下载安装程序；如果无法访问 GitHub，则从镜像站点下载。
• 更新：客户端通过 npx 启动 BrowserDo 时，npm 会在启动 BrowserDo 时检查 npm 注册表中的最新版本。该请求由 npm 发出，而非 BrowserDo。
• 你的模型：只有 browser_run_task 会向模型发送内容，而且只会发送到你配置的端点。浏览器工具会将页面返回给你自己的 Agent。
• 在你的计算机上：调试日志保存在 %LOCALAPPDATA%\Embiody\BrowserDo\logs，记录访问过的网址和执行过的步骤，不记录页面内容或你的任务。日志最多保留 3 个 5 MB 的文件。除非设置 EMBIODY_SAVE_SNAPSHOTS=1，否则不会保存快照。
• 你的配置文件夹：Agent 会在你自己的 Embiody 的 Default 配置文件中工作，因此可以使用你在其中登录过的网站。不会使用其他 Embiody 配置文件，也不会使用计算机上的其他浏览器，例如 Chrome 或 Edge。若要将 Agent 与你自己的环境隔离，请将 EMBIODY_USER_DATA_DIR 设置为专用文件夹。

请参阅隐私政策和 Embiody 最终用户许可协议。

可选：browser_run_task

如果你希望直接交由它处理完整任务，而不是逐步操作浏览器，browser_run_task 会使用你选择的视觉模型（任何兼容 OpenAI 的端点）在 BrowserDo 中执行任务，并避免将屏幕截图放入 Agent 的上下文中。

"env": {
  "EMBIODY_VLLM_ENDPOINT": "<your-openai-compatible-endpoint>",
  "EMBIODY_VLLM_MODEL": "<your-vision-model>",
  "EMBIODY_VLLM_API_KEY": "<your-api-key>"
}

参数	说明
task	必填。 用自然语言描述的任务。
windowId、tabId	传入这两个参数，即可在同一标签页中继续之前的任务。
maxRounds	默认值为 12。
closeTabWhenDone、closeBrowserWindowWhenDone	默认值为 false。
humanReply	当客户端无法在任务过程中向你提问时，提供你对上次运行暂停时所提问题的回答。

需要你介入时，任务会向你提出请求。对于只有你才能完成的步骤（例如输入密码或你收到的验证码），任务会先将标签页交给你；你表示完成后，它便会继续。在支持任务过程中提问的客户端中（例如 Claude Code 的 tasks.requests.elicitation.create），问题会显示在对话中；在其他客户端中，任务会以问题结束，你可以再次调用它并传入 humanReply 作答。

browser_stop_task 会在当前步骤结束时停止正在运行的任务。

请勿将 API 密钥放入会提交到版本库的文件中。 如果客户端支持在配置中展开环境变量，请使用此功能；否则，请将密钥保存在版本库之外的配置文件中，并使用 --config 指定该文件。

说明

• Claude Code 会在对话中保留旧的工具定义。 升级 BrowserDo 后，请开始新对话， 以查看新的工具和参数。
• BrowserDo 使用 MCP 协议版本 2025-11-25，并会协商降级至较旧版本。

开发

npm install
npm run build
npm test          # 902 tests
npm run test:fast # unit and module tests only

测试布局请参阅 test/README.md。

许可证

BrowserDo 采用 Apache License 2.0 许可；请参阅 LICENSE。其安装的 Embiody 浏览器受 Embiody EULA 约束。