SurfAgent — 真实 Chrome 浏览器控制

为您的 AI Agent 提供一个真实、持久的 Chrome 浏览器实例。无需无头浏览器，不依赖云端服务，彻底规避机器人检测问题。

适用场景

• 需要浏览、爬取或与网站交互
• 需要填写表单、点击按钮或导航页面
• 需要从网页中提取结构化数据
• 需要对网站进行截图
• 需要保持登录会话（已登录目标网站）
• 需要绕过机器人检测机制（如 Cloudflare、hCaptcha 等）
• 需要对网站执行爬取或站点地图生成

前提条件

1. 已安装并运行 SurfAgent — 请从 surfagent.app 下载
2. 已连接 MCP 服务器 — 执行命令：hermes mcp add surfagent --command npx --args -y surfagent-mcp
3. 或直接通过 HTTP API 调用：http://localhost:7201

快速参考 — MCP 工具（共 24 个）

操作流程

基础导航

1. 使用 browser_navigate 打开目标 URL
2. 使用 browser_screenshot 查看页面渲染效果
3. 使用 browser_click 或 browser_type 进行交互操作
4. 使用 browser_get_text 读取页面文本内容

数据提取

1. 对目标 URL 调用 browser_extract，获取 Markdown 文本及链接列表
2. 添加 prompt 和 schema 字段，启用大语言模型驱动的结构化提取能力
3. 使用 browser_crawl 实现跨页面批量数据提取
4. 使用 browser_map 快速枚举站点内全部 URL

表单填写

1. 使用 browser_navigate 访问表单所在页面
2. 使用 browser_fill_form，传入字段标签/名称 → 值的映射关系完成批量填写
3. 也可分别使用 browser_click + browser_type 对单个字段操作
4. 对下拉框使用 browser_select

标签页管理

1. 使用 browser_list_tabs 查看当前所有打开的标签页
2. 使用 browser_new_tab 新建标签页
3. 使用 browser_switch_tab 切换焦点至目标标签页
4. 任务完成后务必使用 browser_close_tab 关闭标签页 —— 请始终及时清理资源

直连 HTTP API（备用方案）

若无法使用 MCP，可直接调用后台守护进程：

# 导航至页面
curl -X POST http://localhost:7201/browser/navigate 
  -H 'Content-Type: application/json' 
  -d '{"url": "https://example.com"}'

# 截图
curl -s http://localhost:7201/browser/screenshot --output screenshot.png

# 列出标签页
curl -s http://localhost:7201/browser/tabs

# 提取页面数据
curl -X POST http://localhost:7201/browser/extract 
  -H 'Content-Type: application/json' 
  -d '{"url": "https://example.com", "formats": ["markdown", "links"]}'

核心优势

• 真实 Chrome — 非无头模式，可完全通过各类机器人检测
• 持久化会话 — 仅需一次登录，即可长期保持登录状态
• 真实设备指纹 — 复用您本地安装的 Chrome，保留真实 Cookie 与配置
• 100% 本地运行 — 所有数据均保留在您的设备上，不上传任何信息
• 24 个 MCP 工具 — 提供全面、细粒度的浏览器控制能力
• 数据提取 + 网站爬取 — 功能对标 Firecrawl，零云服务成本

注意事项

• 务必及时关闭标签页 — 遗留未关闭的标签页将持续占用系统资源
• 注意动态内容加载延迟 — 单页应用（SPA）需配合 browser_wait 或在导航后加入适当延时
• 禁止并发执行浏览器指令 — 所有浏览器操作必须串行执行，不可并行发起
• 截图默认仅限视口区域 — 对于长页面，请启用 fullPage 参数以截取完整页面
• Cookie 同意横幅处理 — 守护进程可通过 /browser/resolve-blocker 接口自动识别并关闭常见合规提示

验证方法

• browser_get_url 在导航后返回预期的 URL
• browser_screenshot 显示符合预期的页面内容
• browser_get_text 返回包含预期文本的结果
• 健康检查：curl http://localhost:7201/health 应返回 {"ok": true}