SurfAgent — Real Chrome Browser Control
Give your AI agent a real, persistent Chrome browser. No headless browsers, no cloud, no bot detection issues.
When to Use
- - You need to browse, scrape, or interact with a website
- You need to fill forms, click buttons, or navigate pages
- You need to extract structured data from web pages
- You need to take screenshots of websites
- You need persistent login sessions (already logged into sites)
- You need to bypass bot detection (Cloudflare, hCaptcha, etc.)
- You need to crawl/map a website
Prerequisites
- 1. SurfAgent installed and running — download from surfagent.app
- MCP server connected — INLINECODE0
- Or use the HTTP API directly at INLINECODE1
Quick Reference — MCP Tools (24)
| Tool | What it does |
|---|
| INLINECODE2 | Open a URL |
| INLINECODE3 |
Go back in history |
|
browser_forward | Go forward in history |
|
browser_click | Click an element (selector, text, or coordinates) |
|
browser_type | Type text into an element |
|
browser_fill_form | Fill multiple form fields at once |
|
browser_select | Select dropdown option |
|
browser_scroll | Scroll page or to element |
|
browser_screenshot | Capture page screenshot (PNG) |
|
browser_get_text | Get visible text content |
|
browser_get_html | Get page HTML |
|
browser_get_url | Get current URL |
|
browser_get_title | Get page title |
|
browser_find_elements | Find elements by CSS selector |
|
browser_evaluate | Run JavaScript in page |
|
browser_wait | Wait for element to appear |
|
browser_cookies | Get or set cookies |
|
browser_list_tabs | List open tabs |
|
browser_new_tab | Open new tab |
|
browser_switch_tab | Switch to tab by id/title |
|
browser_close_tab | Close a tab |
|
browser_extract | Extract structured data (markdown, JSON, links) |
|
browser_crawl | BFS crawl a domain |
|
browser_map | Discover all URLs on a site |
Procedure
Basic Navigation
- 1. Use
browser_navigate to open a URL - Use
browser_screenshot to see the page - Use
browser_click or browser_type to interact - Use
browser_get_text to read content
Data Extraction
- 1. Use
browser_extract with a URL to get markdown + links - Add
prompt and schema fields for LLM-powered structured extraction - Use
browser_crawl for multi-page extraction - Use
browser_map for quick URL discovery
Form Filling
- 1. Use
browser_navigate to go to the form page - Use
browser_fill_form with field label/name → value mappings - Or use
browser_click + browser_type for individual fields - Use
browser_select for dropdowns
Tab Management
- 1. Use
browser_list_tabs to see what's open - Use
browser_new_tab to open a new tab - Use
browser_switch_tab to change focus - Use
browser_close_tab when done — always clean up tabs
Direct HTTP API (fallback)
If MCP isn't available, call the daemon directly:
CODEBLOCK0
Key Advantages
- - Real Chrome — not headless, passes all bot detection
- Persistent sessions — log in once, stay logged in forever
- Real fingerprint — your actual Chrome installation, real cookies
- 100% local — no data leaves your machine
- 24 MCP tools — comprehensive browser control
- Extract + Crawl — Firecrawl-equivalent features, zero cloud cost
Pitfalls
- - Always close tabs when done — leaving tabs open wastes resources
- Wait for dynamic content — SPAs need
browser_wait or a short delay after navigation - One operation at a time — don't fire multiple browser commands in parallel
- Screenshots are viewport-only by default — use the fullPage option for long pages
- Cookie consent banners — the daemon can auto-resolve them via INLINECODE46
Verification
- -
browser_get_url returns the expected URL after navigation - INLINECODE48 shows the expected page content
- INLINECODE49 contains the expected text
- Health check:
curl http://localhost:7201/health returns INLINECODE51
SurfAgent — 真实Chrome浏览器控制
为您的AI代理提供一个真实、持久的Chrome浏览器。无无头浏览器、无云端、无机器人检测问题。
适用场景
- - 需要浏览、抓取或与网站交互
- 需要填写表单、点击按钮或导航页面
- 需要从网页提取结构化数据
- 需要截取网站截图
- 需要持久登录会话（已登录网站）
- 需要绕过机器人检测（Cloudflare、hCaptcha等）
- 需要爬取/映射网站
前置条件
- 1. 安装并运行SurfAgent — 从surfagent.app下载
- 连接MCP服务器 — hermes mcp add surfagent --command npx --args -y surfagent-mcp
- 或直接使用HTTP API，地址为http://localhost:7201
快速参考 — MCP工具（24个）
| 工具 | 功能说明 |
|---|
| browsernavigate | 打开URL |
| browserback |
返回上一页 |
| browser_forward | 前进到下一页 |
| browser_click | 点击元素（选择器、文本或坐标） |
| browser_type | 在元素中输入文本 |
| browser
fillform | 一次性填写多个表单字段 |
| browser_select | 选择下拉选项 |
| browser_scroll | 滚动页面或滚动到元素 |
| browser_screenshot | 截取页面截图（PNG格式） |
| browser
gettext | 获取可见文本内容 |
| browser
gethtml | 获取页面HTML |
| browser
geturl | 获取当前URL |
| browser
gettitle | 获取页面标题 |
| browser
findelements | 通过CSS选择器查找元素 |
| browser_evaluate | 在页面中运行JavaScript |
| browser_wait | 等待元素出现 |
| browser_cookies | 获取或设置Cookie |
| browser
listtabs | 列出打开的标签页 |
| browser
newtab | 打开新标签页 |
| browser
switchtab | 按ID/标题切换标签页 |
| browser
closetab | 关闭标签页 |
| browser_extract | 提取结构化数据（Markdown、JSON、链接） |
| browser_crawl | BFS广度优先爬取域名 |
| browser_map | 发现网站上的所有URL |
操作流程
基本导航
- 1. 使用browsernavigate打开URL
- 使用browserscreenshot查看页面
- 使用browserclick或browsertype进行交互
- 使用browsergettext读取内容
数据提取
- 1. 使用browserextract配合URL获取Markdown+链接
- 添加prompt和schema字段实现LLM驱动的结构化提取
- 使用browsercrawl进行多页面提取
- 使用browser_map快速发现URL
表单填写
- 1. 使用browsernavigate跳转到表单页面
- 使用browserfillform配合字段标签/名称→值的映射
- 或对单个字段使用browserclick+browsertype
- 使用browserselect处理下拉框
标签页管理
- 1. 使用browserlisttabs查看已打开的标签页
- 使用browsernewtab打开新标签页
- 使用browserswitchtab切换焦点
- 使用browserclosetab完成操作后关闭标签页——始终清理标签页
直接HTTP API（备用方案）
如果MCP不可用，可直接调用守护进程：
bash
导航
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的功能，零云端成本
注意事项
- - 完成后始终关闭标签页 — 保留打开的标签页会浪费资源
- 等待动态内容 — 单页应用在导航后需要browser_wait或短暂延迟
- 一次只执行一个操作 — 不要并行发送多个浏览器命令
- 截图默认仅视口范围 — 对长页面使用fullPage选项
- Cookie同意横幅 — 守护进程可通过/browser/resolve-blocker自动处理
验证方法
- - browsergeturl返回导航后的预期URL
- browserscreenshot显示预期的页面内容
- browserget_text包含预期的文本
- 健康检查：curl http://localhost:7201/health返回{ok: true}
