# Firecrawl-Compatible Stealth Web Scraper MCP Server

[![Run on Apify](https://apify.com/actor-badge?actor=neon_innovation_lab/firecrawl-stealth-mcp)](https://apify.com/neon_innovation_lab/firecrawl-stealth-mcp)

⚡ **Run directly on Apify Store**: [Firecrawl Alternative: WAF-Bypass Web Scraper](https://apify.com/neon_innovation_lab/firecrawl-stealth-mcp)

A lightweight, drop-in replacement for the core Firecrawl MCP tools (`firecrawl_scrape`, `firecrawl_crawl`, and `firecrawl_map`). Built for AI agents (Cursor, Claude Desktop, autonomous swarms) that need clean, LLM-ready markdown without paying for blocked requests or running into aggressive edge bot filters.

---

## What This Solves

1. **Strict Pay-Per-Success Billing**: Standard scraping APIs consume your credits even when a site returns HTTP 403 or times out. This server only charges when valid DOM content is extracted. If a request is blocked or unreachable, **you pay $0.00**.
2. **Resilient TLS Fingerprinting**: Direct HTTP clients (curl, python-requests, default node fetch) get blocked by modern edge firewalls before reaching the page. This engine emulates realistic browser TLS Client Hello signatures (JA3/JA4) and HTTP/2 frame ordering.
3. **Passive URL Mapping (Zero Target Probing)**: `firecrawl_map` queries passive threat intelligence indexes (AlienVault OTX) to discover indexed URLs and endpoints under a target domain without sending active HTTP probes to the target server.
4. **Dual Settlement Rails**: Connect either via Apify Pay-Per-Event ($0.005/scrape) or natively via Coinbase x402 micropayments ($0.01 USDC on Base).

---

## Supported Tools

### 1. `firecrawl_scrape`
Scrapes a single webpage and returns clean, LLM-ready Markdown.

**Parameters:**
- `url` (string, required): The target webpage URL.
- `formats` (array, optional): `["markdown", "html"]` (default: `["markdown"]`).
- `onlyMainContent` (boolean, optional): Strips navigation bars, footers, scripts, and cookie banners (default: `true`).
- `waitFor` (integer, optional): Milliseconds to wait for client-side JavaScript rendering (default: `0`).

**Response Shape:**
```json
{
  "success": true,
  "data": {
    "markdown": "# Page Title\n\nArticle content...",
    "metadata": {
      "title": "Page Title",
      "description": "Page meta description",
      "language": "en",
      "sourceURL": "https://example.com/article",
      "statusCode": 200,
      "wordCount": 420
    }
  }
}
```

### 2. `firecrawl_map`
Discovers URLs belonging to a domain using passive intelligence without active probing.

**Parameters:**
- `url` (string, required): Domain or URL to map (e.g. `example.com`).
- `limit` (integer, optional): Maximum URLs to return (default: `100`).

**Response Shape:**
```json
{
  "success": true,
  "links": [
    "https://example.com/pricing",
    "https://example.com/docs",
    "https://example.com/blog/post-1"
  ]
}
```

### 3. `firecrawl_crawl`
Crawls linked pages on a website up to a designated depth.

**Parameters:**
- `url` (string, required): Starting URL.
- `maxDepth` (integer, optional): Maximum link depth (default: `2`).
- `limit` (integer, optional): Maximum pages to scrape (default: `10`).

---

## Installation & Setup

### Claude Desktop

#### Option A: Native UI (Recommended)
1. Open Claude Desktop → **Settings** → **Connectors**
2. Click **Add custom connector**
3. Paste: `https://neon-innovation-lab--firecrawl-stealth-mcp.apify.actor/mcp`

#### Option B: Config File (`claude_desktop_config.json`)
Claude Desktop's config file runs local commands, so remote HTTPS servers connect via the official `mcp-remote` stdio bridge:
```json
{
  "mcpServers": {
    "firecrawl-stealth": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://neon-innovation-lab--firecrawl-stealth-mcp.apify.actor/mcp"]
    }
  }
}
```

### Cursor IDE
Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "firecrawl-stealth": {
      "type": "streamable-http",
      "url": "https://neon-innovation-lab--firecrawl-stealth-mcp.apify.actor/mcp"
    }
  }
}
```

### Autonomous Agent Integration (x402 Micropayments)
Autonomous agents calling this MCP server can pay dynamically using the x402 protocol:
1. Make unauthenticated tool call to `/mcp`.
2. Receive HTTP 402 challenge with payment parameters (`0.01 USDC` on Base `eip155:8453`).
3. Retry request with signed payload in `_meta["x402/payment"]`.
4. Settlement occurs only if extraction succeeds.

---

## Local Development & Docker

```bash
# Clone and install dependencies
npm install

# Build TypeScript
npm run build

# Start server locally on port 8080
npm start
```

Run via Docker:
```bash
docker build -t firecrawl-stealth-mcp .
docker run -p 8080:8080 firecrawl-stealth-mcp
```