agent-browser

mcp-server-agent-browser

状态：Beta — CLI 封装已通过单元测试和模拟浏览器 stdio 冒烟测试。真实 Chromium 重启后的 Cookie 恢复仍需手动验证。

让 LLM 驱动真实浏览器。此 MCP 服务封装了 agent-browser（Vercel Labs），因此任何 MCP 客户端都可以导航、填写表单、点击、快照无障碍树并截取屏幕截图。

它不是 Grok 的 web_search / open_page。那些工具会抓取文档，而这个工具会运行 Chromium。先用搜索找到 URL，然后调用 browser_navigate。

前置条件

cargo install agent-browser
agent-browser install

如果缺少任何内容，请调用 browser_doctor。

构建

cargo build --release

二进制文件：target/release/mcp-server-agent-browser

cargo test
./tests/test-stdio.sh

CI 不会测试真实 Chromium 的登录恢复。使用有头模式登录后，重启 MCP 进程，并确认下一次 browser_navigate 仍处于登录状态。

配置

MCP 客户端（stdio）：

{
  "mcpServers": {
    "agent-browser": {
      "command": "/path/to/mcp-server-agent-browser"
    }
  }
}

可选 TOML 文件：~/.config/mcp-server-agent-browser/config.toml（参见 config.example.toml）。文件不存在时使用默认值。使用 MCP_AGENT_BROWSER_CONFIG 覆盖路径。

设置	默认值	含义
headed	false	显示窗口。仅在启动时生效；如果无头守护进程已在运行，请先调用 browser_close。也可设置 AGENT_BROWSER_HEADED=1。
persist	true	使用 --session-name <namespace>-<session_id>（默认会话键为 default）。没有 --namespace CLI 标志，namespace 会并入该名称。
keep_daemon	false	如果为 false，MCP 退出时会运行 close，以保存恢复状态并避免 Chrome 残留。
namespace	mcp-server	--session-name 恢复键的前缀，将此 MCP 的恢复文件与直接使用 CLI 的用户隔离。
command_timeout_secs	120	封装层超时时间。Playwright 自身的 25s 操作超时保持不变（CLI IPC 约为 30s）。
idle_timeout	1h	设置 AGENT_BROWSER_IDLE_TIMEOUT_MS（仅限环境变量，没有 --idle-timeout CLI 标志）。与 keep_daemon = true 搭配时使用 "0"。
download_dir	~/Downloads	--download-path。会展开 ~。
profile	未设置	可选的持久化 Chrome 用户数据目录。不要使用日常 Chrome 配置文件。
encryption_key_file	未设置	设置 AGENT_BROWSER_ENCRYPTION_KEY。恢复文件包含凭据；未设置此项时会以明文保存。
AGENT_BROWSER_PATH	agent-browser	CLI 二进制文件。

allowed_domains 为可选项。除非你设置的列表排除了 localhost，否则默认允许 localhost。

功能

与之前相同的交互功能集（导航、点击、输入、快照、屏幕截图、Cookie、eval、CDP、会话），另有：

• browser_doctor — 检查 CLI、配置、持久化、有头模式 / DISPLAY 和守护进程状态猜测。不会启动 Chrome。
• browser_get_text pattern — 对页面文本使用正则表达式，并返回上下各两行内容。
• browser_wait — 除选择器外，还支持 load / url / text。

典型流程：

1. browser_navigate
2. browser_snapshot（交互式模式使用 -i）
3. 使用 @ref 调用 browser_click / browser_fill
4. 需要查看像素时调用 browser_screenshot

持久化

启用 persist = true（默认值）时，每个会话会在关闭时以及 CLI 自动保存间隔到达时保存 Cookie 和 localStorage。状态保存在 ~/.agent-browser/ 下，命名空间为 mcp-server。相互隔离的 session_id 不会共享恢复键。

使用有头模式登录一次，然后调用 browser_close 或退出 MCP，再重新启动。下一次导航应恢复该会话。

强制终止 MCP 进程可能会导致守护进程继续运行。browser_doctor 会报告这一情况。启用持久化时，闲置关闭仍会保存状态。

限制

• 使用 agent-browser（Playwright）运行 Chromium。不支持搜索。
• 现有守护进程关闭前，启用有头模式不会生效。
• Ubuntu 上的 Snap Chromium 可能无法公布其 DevTools 端口；建议使用 agent-browser install 安装的浏览器或 executable_path。
• 写入文件（截图、PDF、下载）时，路径必须是相对路径、位于 /tmp 下，或位于 download_dir 下。
• 元素截图接受 CSS 选择器或 @ref，后面可接 :has-text("...")。会先检查选择器，因此未匹配时会报错，而不会静默截取整个视口。不能与 full_page 组合使用。
• Playwright 操作超时为 25s，这是上游 CLI 的限制，不是此封装的限制。

许可证

MIT