surfsky-mcp

MCP server for Surfsky, a cloud-based antidetect browser.

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.

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": "..." }
    }
  }
}

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

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

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.

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