# FrankenSurf

Reads any web page and searches the web through 28 tools. Tries free ones first, moves to paid APIs only when a site blocks, checks every page, and returns clean data with a receipt of every attempt.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 101
- Author: yail259
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/yail259/frankensurf
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/frankensurf

## What it does

FrankenSurf tries 41 ways to extract content: plain HTTP, Jina Reader, a local browser, stealth browsers, hosted services, and paid APIs — in order of rising cost. Every result is checked: a challenge page, a login wall, or empty search results count as failure. The `read()` call returns text or markdown, JSON-LD, images, and a detailed receipt showing which tools ran, how long they took, what they cost, and why they stopped.

Works as an MCP server for agents, a Python library (`fs.read(url)`, `fs.search()`, `fs.crawl()`), a Docker container, and a Firecrawl API drop-in for LangChain, n8n, Dify, and other systems. No Docker needed: `pip install "frankensurf[mcp]"`, then `frankensurf install` sets up browsers, stealth tools, and Crawl4AI locally. Requires Python 3.12+ on Linux, macOS, or WSL.

Benchmark across 150 sites: free tools read 88% correctly, FrankenSurf with paid fallbacks 96%, Zyte 86%, Firecrawl 85%. Cost per 1,000 correct pages with free tools: $0 in fees plus about $0.01 of server time; with paid fallbacks $0.22.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add frankensurf -- uvx frankensurf
```
uvx runs the command named after the package; if the README names another one, use uvx --from frankensurf <command>

### Codex

**Platform CLI**
```bash
codex mcp add frankensurf -- uvx frankensurf
```
uvx runs the command named after the package; if the README names another one, use uvx --from frankensurf <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "frankensurf": {
            "command": "uvx",
            "args": [
                "frankensurf"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from frankensurf <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "frankensurf": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "frankensurf"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from frankensurf <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add frankensurf uvx frankensurf
```
uvx runs the command named after the package; if the README names another one, use uvx --from frankensurf <command>

## When to use it
- read a page behind a CAPTCHA or anti-bot challenge
- search the web for fresh data from the past month or week
- try 41 ways to bypass blocks and return a detailed attempt receipt
- run search and content extraction from Python, Docker, or as an MCP server
- replace Firecrawl API in LangChain, n8n, or Dify

## Example prompts
- Read `https://www.walmart.com/search?q=air+fryer` and show the title
- Search for recent articles on "playwright python tutorial" from the past week
- Try every available tool on this page and show the attempt receipt

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md