mcp-firecrawl-licensed

Firecrawl Licensed MCP (Copyright.sh)

Open-source MCP server that wraps Firecrawl and adds Copyright.sh licensing, usage logging, and optional x402 licensed fetch. Tool names match Firecrawl’s OSS MCP server (firecrawl_*) so clients can drop this in without prompt changes.

Features

• License discovery via ai-license meta tags
• Usage logging for compensation and audit trails
• Optional x402 licensed fetch on 402 Payment Required
• Token estimation with tiktoken
• Graceful degradation when the ledger is unavailable

Quick Start

Install from source

git clone https://github.com/tymrtn/mcp-firecrawl-licensed.git
cd mcp-firecrawl-licensed
npm install
npm run build

Run via npx (if published)

npx @copyrightsh/firecrawl-licensed-mcp@latest

Configuration

Copy env.example to .env and set:

• FIRECRAWL_API_KEY (required unless using FIRECRAWL_API_URL)
• FIRECRAWL_API_URL (optional for self-hosted Firecrawl)
• COPYRIGHTSH_LEDGER_API_KEY (recommended for license acquire + usage logging)

MCP Config Example (npx)

{
  "mcpServers": {
    "firecrawl-licensed": {
      "command": "npx",
      "args": ["-y", "@copyrightsh/firecrawl-licensed-mcp@latest"],
      "env": {
        "FIRECRAWL_API_KEY": "fc-your-key-here",
        "COPYRIGHTSH_LEDGER_API": "https://ledger.copyright.sh",
        "COPYRIGHTSH_LEDGER_API_KEY": "cs-ledger-your-key-here"
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | | --- | --- | --- | --- | | FIRECRAWL_API_KEY | Yes* | - | Firecrawl API key | | FIRECRAWL_API_URL | No | - | Self-hosted Firecrawl base URL | | COPYRIGHTSH_LEDGER_API | No | https://ledger.copyright.sh | Ledger base URL | | COPYRIGHTSH_LEDGER_API_KEY | Recommended | - | API key for license discovery + usage logging | | ENABLE_LICENSE_TRACKING | No | true | Enable/disable licensing | | ENABLE_LICENSE_CACHE | No | false | Cache license results | | LICENSE_CACHE_TTL_SECONDS | No | 300 | Cache TTL for license lookups | | LICENSE_CHECK_TIMEOUT_MS | No | 5000 | License discovery timeout (ms) | | LICENSE_ACQUIRE_TIMEOUT_MS | No | 8000 | License acquisition timeout (ms) | | USAGE_LOG_TIMEOUT_MS | No | 3000 | Usage logging timeout (ms) | | FETCH_TIMEOUT_MS | No | 12000 | Direct fetch timeout (ms) |

*FIRECRAWL_API_KEY is required unless FIRECRAWL_API_URL is set.

Tools

• firecrawl_scrape
• firecrawl_map
• firecrawl_search
• firecrawl_crawl
• firecrawl_check_crawl_status
• firecrawl_extract
• firecrawl_agent
• firecrawl_agent_status

x402 Licensed Fetch

For tools that accept URLs (scrape, search, check_crawl_status), set:

• fetch: true
• stage: infer|embed|tune|train
• distribution: private|public
• estimated_tokens: number
• payment_method: account_balance|x402

When enabled, the server performs a direct fetch that handles 402 Payment Required + payment-required: x402 responses, acquires a license token from the ledger, and retries with the returned licensed_url.

Example: Licensed Scrape

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/article",
    "options": { "formats": ["markdown"], "onlyMainContent": true },
    "fetch": true,
    "stage": "infer",
    "distribution": "private",
    "estimated_tokens": 1500,
    "payment_method": "account_balance"
  }
}

CLI Helpers

node build/index.js --list-tools
node build/index.js --doctor

Notes on Paywalled Sources

This server only unlocks sources that implement the Copyright.sh x402 flow (402 + payment-required: x402). It does not bypass login/subscription paywalls.

Contributing

See CONTRIBUTING.md.

License

MIT