FrankenSurf — Claude Code MCP server: what it does, how to install
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.
claude mcp add frankensurf -- uvx frankensurfWhat FrankenSurf 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.
What it helps with
- 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 for the agent
- Read
https://www.walmart.com/search?q=air+fryerand 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
How to install FrankenSurf
Platform CLI
claude mcp add frankensurf -- uvx frankensurfuvx runs the command named after the package; if the README names another one, use uvx --from frankensurf <command>
Platform CLI
codex mcp add frankensurf -- uvx frankensurfuvx runs the command named after the package; if the README names another one, use uvx --from frankensurf <command>
Config file
{
"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>
Config file
{
"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>
Platform CLI
gemini mcp add frankensurf uvx frankensurfuvx runs the command named after the package; if the README names another one, use uvx --from frankensurf <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about FrankenSurf
How to install FrankenSurf in Claude Code?
Run claude mcp add frankensurf -- uvx frankensurf. The command adds the MCP server to your Claude Code config and starts it through uvx.
What does FrankenSurf do?
Reads web pages and searches the internet through 28 tools — from plain HTTP to paid APIs. Tries the cheapest first, checks every page for CAPTCHAs and empty results, moves to the next tool only when blocked. Returns text, markdown, JSON, and a receipt showing which tools ran, what they cost, and why they stopped.
What dependencies does FrankenSurf need?
Python 3.12 or higher on Linux, macOS, or Windows through WSL. After pip install "frankensurf[mcp]", run frankensurf install to set up browsers, stealth tools, and Crawl4AI locally. Paid fallbacks need API keys, but they're optional.
