Firecrawl Licensed

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