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)#

ToolWhat it doesbrowser_navigateOpen a URLbrowser_backGo back in historybrowser_forwardGo forward in historybrowser_clickClick an element (selector, text, or coordinates)browser_typeType text into an elementbrowser_fill_formFill multiple form fields at oncebrowser_selectSelect dropdown optionbrowser_scrollScroll page or to elementbrowser_screenshotCapture page screenshot (PNG)browser_get_textGet visible text contentbrowser_get_htmlGet page HTMLbrowser_get_urlGet current URLbrowser_get_titleGet page titlebrowser_find_elementsFind elements by CSS selectorbrowser_evaluateRun JavaScript in pagebrowser_waitWait for element to appearbrowser_cookiesGet or set cookiesbrowser_list_tabsList open tabsbrowser_new_tabOpen new tabbrowser_switch_tabSwitch to tab by id/titlebrowser_close_tabClose a tabbrowser_extractExtract structured data (markdown, JSON, links)browser_crawlBFS crawl a domainbrowser_mapDiscover all URLs on a site

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:

bash

# 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}