surfsky-mcp

Chrome in the cloud for Claude, Cursor or any MCP client. Read pages a plain HTTP fetch cannot, then click through them, fill forms and take screenshots. Runs on Surfsky, an antidetect browser with residential proxies and human-like input.

Install

Requires Python 3.12+, uv, and a Surfsky account. Replace ... with your SURFSKY_API_TOKEN and SURFSKY_API_BASE_URL from the dashboard. Browser time and proxy traffic are billed.

uv downloads Python itself, so no separate Python install is needed.

Claude Code:

claude mcp add surfsky -e SURFSKY_API_TOKEN=... -e SURFSKY_API_BASE_URL=... -- uvx surfsky-mcp

Claude Desktop / Cursor:

{
  "mcpServers": {
    "surfsky": {
      "command": "uvx",
      "args": ["surfsky-mcp"],
      "env": { "SURFSKY_API_TOKEN": "...", "SURFSKY_API_BASE_URL": "..." }
    }
  }
}

On macOS the app does not read your shell profile, so "command": "uvx" fails to start. Use the absolute path that which uvx prints. Windows finds uvx on PATH.

After changing the config, quit Claude Desktop with Cmd+Q on macOS or from the tray on Windows, then start it again. Closing the window leaves the old server process running.

Codex (~/.codex/config.toml):

[mcp_servers.surfsky]
command = "uvx"
args = ["surfsky-mcp"]
env = { SURFSKY_API_TOKEN = "...", SURFSKY_API_BASE_URL = "..." }

Configuration

Set them in the MCP client's config, not in your shell.

Logs go to stderr; stdout carries JSON-RPC only.

What you can ask

Tools

Sessions

Browser tools share a default session unless you pass session_id. It starts on first use and stops after five minutes idle or on server shutdown. Call surfsky_session_stop to stop billing immediately.

Use surfsky_session_start for separate sessions, saved profiles or custom proxy and fingerprint settings. surfsky_scrape stops its browser automatically. Sessions can also be listed and stopped through the Surfsky CLI.

HTTP mode

uvx surfsky-mcp --http --host 0.0.0.0 --port 8000 --allowed-hosts mcp.example.com

Serves streamable HTTP at /mcp. Set the same credentials in the environment. There is no built-in authentication; use an authenticated proxy or private network. Set --allowed-hosts to the hostname clients use. Without it, non-localhost binds disable Host-header checks.

Clients sharing a server must use separate session_id values.

Troubleshooting

A page returns 200 but the text is short, or asks you to continue shopping or prove you are human. That is a bot challenge, not a bug. Each scrape gets a fresh browser and a different proxy exit, so a retry often gets through. If a site blocks every fresh browser, start a session with a saved profile_uuid, whose cookies survive between runs.

The result carries note: navigation did not reach 'load'. The document parsed, but a request stayed open past the timeout. The content and the status are there; anything that loads late may be missing. Pass wait_until: "domcontentloaded" and a wait_for selector for the element you need.

error [timeout]. The navigation committed no document at all. Retry with a longer timeout, or wait_until: "commit" to stop at the first response.

error [stale_ref]. The page moved under the @N references. Call surfsky_snapshot and pick the target again.

error [session_gone]. The cloud no longer has that session. Start another; page state is lost.

error [plan_full] or error [quota]. The plan's parallel sessions or its traffic are used up. surfsky_session_list shows what is running and surfsky_session_stop frees one. surfsky_status shows the limits. Do not retry in a loop.

error [auth]. The token or the base URL never reached the server process. Check the env block of the MCP client's config, not your shell.

A session keeps billing. The shared default session stops after five minutes idle and on server shutdown. surfsky_session_stop ends it now, and the Surfsky CLI can stop sessions this server does not know about.

Security and privacy

The server stores nothing. It sends the URLs and actions a tool call names to the Surfsky API, which runs the browser, and returns what the page said to your MCP client. The token is read from the environment and goes nowhere but that API.

Page content, snapshots, screenshots and JavaScript results arrive inside an <untrusted-page-content> block introduced as data rather than instructions. Invisible and bidirectional characters are stripped, and a page cannot close the block early. Filtering does not catch every prompt injection. Check what an action does before it submits a form or spends money.

A profile_uuid carries real logins. Pass one only when the user gave it to you. HTTP mode has no authentication of its own; see HTTP mode.

Development

uv sync --all-groups
uv run ruff check . && uv run ty check && uv run pytest -q
SURFSKY_LIVE_TESTS=1 uv run pytest tests/test_live.py   # billed

License

MIT