🐝 FlyCrawl Model Context Protocol (MCP) Server

Official Model Context Protocol (MCP) server for FlyCrawl — the high-performance Web-to-Markdown engine and AI crawling API. Directly connects Claude Desktop, Cursor AI, Windsurf, and autonomous LLM agents to the live web with zero token bloat and automatic anti-bot bypass.

⚡ Quick Start

1. Cursor IDE Setup

In Cursor: Settings -> Features -> MCP Servers -> + Add New MCP Server:

• Name: flycrawl
• Type: command
• Command: npx -y flycrawl-mcp
• Environment Variables: FLYCRAWL_API_KEY=fc_live_YOUR_API_KEY

2. Claude Desktop Setup

Add this block to your claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "flycrawl": {
      "command": "npx",
      "args": ["-y", "flycrawl-mcp"],
      "env": {
        "FLYCRAWL_API_KEY": "fc_live_YOUR_API_KEY"
      }
    }
  }
}

🛠️ TDQS 5/5 Behavioral Disclosures & Tool Spec

Every FlyCrawl tool is certified with explicit behavioral disclosures, rate limits, side-effect boundaries, dynamic JS rendering specs, and zero-risk billing guarantees.

| Tool Name | Behavior & Idempotency | Dynamic JS / Anti-bot | Auth Required | Billing & Fair Guarantee | Scope & Difference | | :--- | :--- | :--- | :--- | :--- | :--- | | flycrawl_scrape | Read-only, idempotent | Auto Playwright rendering + stealth residential proxies | FLYCRAWL_API_KEY | 1 credit/page. 0 credits on 4xx/5xx failures. | Converts full page body to clean Fit-Markdown (90% token saving). | | flycrawl_crawl | Read-only web traversal | Dynamic JS per page + domain boundary check | FLYCRAWL_API_KEY | 1 credit/page. 0 credits on failed pages. | Traverses sub-pages recursively up to configured depth/limit. | | flycrawl_map | Read-only reconnaissance | Headless sitemap + SPA route parsing | FLYCRAWL_API_KEY | 1 credit per domain mapping | Discovers URL structure in < 2s without downloading full page bodies. | | flycrawl_search | Read-only web search | Real-time index without search engine ads | FLYCRAWL_API_KEY | 1 credit per search query | Searches live web and returns scraped top results in 1 atomic call. | | flycrawl_extract | Read-only, idempotent | Dynamic JS rendering + schema validation | FLYCRAWL_API_KEY | 1 credit/call. 0 credits on failure. | Extracts validated JSON conforming to your prompt and JSON schema. |

🛡️ Fair Billing Guarantee

• 0-Credit Deduction on Failures: If an upstream target returns 404 Not Found, 403 Forbidden, 500 Server Error, or times out, exactly 0 credits are billed.
• Structured Error Schema: Failures return standard JSON indicating { isError: true, status: <CODE>, billed_credits: 0, retryable: boolean }.
• Free Credits: Claim 100 free credits on sign up at https://flycrawl.net.

📦 Canonical Package Ecosystem

• TypeScript / Node.js SDK: npm install flycrawl
• MCP Server (npx): npx -y flycrawl-mcp
• Python SDK: pip install flycrawl
• Official Documentation: https://flycrawl.net/docs

📄 License

MIT © FlyCrawl Core Team.