Surfagent

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
2. MCP server connected — hermes mcp add surfagent --command npx --args -y surfagent-mcp
3. Or use the HTTP API directly at http://localhost:7201

Quick Reference — MCP Tools (24)

Procedure

Basic Navigation

1. Use browser_navigate to open a URL
2. Use browser_screenshot to see the page
3. Use browser_click or browser_type to interact
4. Use browser_get_text to read content

Data Extraction

1. Use browser_extract with a URL to get markdown + links
2. Add prompt and schema fields for LLM-powered structured extraction
3. Use browser_crawl for multi-page extraction
4. Use browser_map for quick URL discovery

Form Filling

1. Use browser_navigate to go to the form page
2. Use browser_fill_form with field label/name → value mappings
3. Or use browser_click + browser_type for individual fields
4. Use browser_select for dropdowns

Tab Management

1. Use browser_list_tabs to see what's open
2. Use browser_new_tab to open a new tab
3. Use browser_switch_tab to change focus
4. Use browser_close_tab when done — always clean up tabs

Direct HTTP API (fallback)

If MCP isn't available, call the daemon directly:

# Navigate
curl -X POST http://localhost:7201/browser/navigate \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com"}'

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

# List tabs
curl -s http://localhost:7201/browser/tabs

# Extract page data
curl -X POST http://localhost:7201/browser/extract \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com", "formats": ["markdown", "links"]}'

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 /browser/resolve-blocker

Verification

• browser_get_url returns the expected URL after navigation
• browser_screenshot shows the expected page content
• browser_get_text contains the expected text
• Health check: curl http://localhost:7201/health returns {"ok": true}