Getting started

Frankensurf is a Python package. You can use it three ways: from the command line, from Python, or from any AI app that supports MCP. It runs on Linux or on Windows through WSL.

Install

1. Get the code and install it.

   git clone https://github.com/yail259/frankensurf.git
   cd frankensurf
   python3 -m venv .venv
   .venv/bin/pip install -e '.[test,mcp]'
   .venv/bin/playwright install chromium

2. Start the two helpers: a browser server (Steel) and a search engine (SearXNG). Both run locally in Docker. Running the scripts again is safe.

   bash scripts/start-steel.sh
   bash scripts/start-search.sh
   export FRANKENSURF_STEEL_URL=http://127.0.0.1:3100

3. Optional: install the stealth browsers (Camoufox and Scrapling). They get their own environment so they don’t clash with the main install.

   bash scripts/install-public-providers.sh

4. Check it works.

   .venv/bin/pytest -q
   .venv/bin/frankensurf read https://example.com

You don’t need an account, an API key or a paid service for any of this.

Your first calls

Command line

# Fetch a page
.venv/bin/frankensurf read https://example.com

# Search
.venv/bin/frankensurf search 'Sydney used ebike' --source searxng

# Pull structured data and photos from a listing
.venv/bin/frankensurf extract https://www.gumtree.com.au/web/listing/lenses/1344434853 \
  --adapter gumtree_listing --images

Python

from pathlib import Path
from frankensurf import Runtime, WebPolicy

async with Runtime(Path("state"), steel_api_url="http://127.0.0.1:3100") as web:
    page = await web.read("https://example.com")
    item = await web.extract(url, "shopify_product", WebPolicy(include_images=True))
    hits = await web.search("Sydney used ebike", source="searxng",
                            engine_config={"base_url": "http://127.0.0.1:8088"})

MCP

FRANKENSURF_STATE="$PWD/state" \
FRANKENSURF_STEEL_URL=http://127.0.0.1:3100 \
FRANKENSURF_SEARCH_URL=http://127.0.0.1:8088 \
  .venv/bin/frankensurf-mcp

See MCP server for how to add it to your AI app.

Tip

Every result includes a trace_id. Run frankensurf trace <trace_id> to see exactly how that result was fetched.

Settings you can change

Variable	What it sets
FRANKENSURF_STATE	Where saved pages, cache and traces go (used by the MCP server)
FRANKENSURF_STEEL_URL	Address of your local Steel browser
FRANKENSURF_SEARCH_URL	Address of your local SearXNG
FRANKENSURF_IDENTITIES	Where your saved logins are registered (default ~/.frankensurf/identities.json)
FRANKENSURF_PROVIDER_PYTHON	The Python that runs the stealth browsers