surfagent-mcp

MCP server for SurfAgent — gives AI agents a real managed Chrome browser.

What it does

SurfAgent runs a dedicated Chrome instance on your machine with a persistent profile and remote debugging port. This MCP server connects to that browser via CDP and exposes browser control as tools that any MCP-compatible AI agent can use.

Navigate. Open URLs, go back/forward, reload, manage tabs. Interact. Click elements, type text, fill forms, select options. Observe. Take screenshots, inspect DOM elements, read page content. Manage. Handle cookies, evaluate JavaScript, wait for conditions.

Quick Start

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "surfagent": {
      "command": "npx",
      "args": ["-y", "surfagent-mcp"]
    }
  }
}

With Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "surfagent": {
      "command": "npx",
      "args": ["-y", "surfagent-mcp"]
    }
  }
}

With OpenClaw

skills:
  - surfagent-mcp

Prerequisites

• SurfAgent running on your machine (manages Chrome on port 9222)
• Node.js 20+

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CDP_HOST | 127.0.0.1 | Chrome DevTools Protocol host | | CDP_PORT | 9222 | Chrome DevTools Protocol port |

Available Tools

Navigation

• navigate — Go to a URL
• go_back / go_forward — Browser history navigation
• reload — Reload the current page

Interaction

• click — Click an element by CSS selector
• type — Type text into an element
• fill_form — Fill multiple form fields at once
• select_option — Select dropdown option
• press_key — Press a keyboard key

Observation

• screenshot — Capture the current page as PNG
• inspect — Get element properties and text content
• get_page_content — Extract page text/HTML
• evaluate — Run JavaScript in the page

Tab Management

• list_tabs — Show all open tabs
• new_tab — Open a new tab
• switch_tab — Switch to a tab by ID
• close_tab — Close a tab

Cookies

• get_cookies — Read cookies for the current page
• set_cookie — Set a cookie
• clear_cookies — Clear cookies

Wait

• wait_for_element — Wait until an element appears
• wait_for_navigation — Wait for page navigation to complete

How it works

AI Agent ←→ MCP Protocol ←→ surfagent-mcp ←→ CDP ←→ Chrome (managed by SurfAgent)

SurfAgent handles the hard parts: launching Chrome with the right flags, maintaining a persistent profile, health monitoring, crash recovery. This MCP server just connects to the already-running browser and translates MCP tool calls into CDP commands.

License

MIT — SurfAgent