Firecrawl Install & Auth

Overview

Install the Firecrawl SDK and configure API key authentication. Firecrawl turns any website into LLM-ready markdown or structured data. The SDK is published as @mendable/firecrawl-js on npm and firecrawl-py on PyPI.

Prerequisites

Node.js 18+ or Python 3.10+
Package manager (npm, pnpm, yarn, or pip)
Firecrawl API key from firecrawl.dev/app (free tier available)

Instructions

Step 1: Install the SDK

set -euo pipefail
# Node.js (official npm package)
npm install @mendable/firecrawl-js

# Python
pip install firecrawl-py

Step 2: Configure Your API Key

# Set the environment variable (SDK reads FIRECRAWL_API_KEY automatically)
export FIRECRAWL_API_KEY="fc-YOUR_API_KEY"

# Or add to .env file (use dotenv in your app)
echo 'FIRECRAWL_API_KEY=fc-YOUR_API_KEY' >> .env

All Firecrawl API keys start with fc-. Get yours at firecrawl.dev/app.

Step 3: Verify Connection — TypeScript

import FirecrawlApp from "@mendable/firecrawl-js";

const firecrawl = new FirecrawlApp({
  apiKey: process.env.FIRECRAWL_API_KEY!,
});

// Quick connection test: scrape a simple page
const result = await firecrawl.scrapeUrl("https://example.com", {
  formats: ["markdown"],
});

if (result.success) {
  console.log("Firecrawl connected. Page title:", result.metadata?.title);
  console.log("Content length:", result.markdown?.length, "chars");
} else {
  console.error("Firecrawl error:", result.error);
}

Step 4: Verify Connection — Python

from firecrawl import FirecrawlApp

firecrawl = FirecrawlApp(api_key="fc-YOUR_API_KEY")

# Quick connection test
result = firecrawl.scrape_url("https://example.com", params={
    "formats": ["markdown"]
})

print(f"Title: {result.get('metadata', {}).get('title')}")
print(f"Content: {len(result.get('markdown', ''))} chars")

Step 5: Self-Hosted Setup (Optional)

// Point to your own Firecrawl instance instead of api.firecrawl.dev
const firecrawl = new FirecrawlApp({
  apiKey: "any-key",  // required even for self-hosted
  apiUrl: "http://localhost:3002",  // self-hosted Firecrawl URL
});

Output

@mendable/firecrawl-js installed in node_modules/
FIRECRAWL_API_KEY environment variable configured
Successful scrape confirming API connectivity

Error Handling

Error	Cause	Solution
`401 Unauthorized`	Invalid or missing API key	Verify key starts with `fc-` and is set in env
`402 Payment Required`	Credits exhausted	Check balance at firecrawl.dev/app
`MODULE_NOT_FOUND`	Wrong package name	Use `@mendable/firecrawl-js` not `firecrawl-js`
`ECONNREFUSED`	Wrong API URL for self-hosted	Verify `apiUrl` and Docker container is running
`429 Too Many Requests`	Rate limit exceeded	Wait for `Retry-After` header duration

Examples

TypeScript with dotenv

import "dotenv/config";
import FirecrawlApp from "@mendable/firecrawl-js";

const firecrawl = new FirecrawlApp({
  apiKey: process.env.FIRECRAWL_API_KEY!,
});

Python with Environment Variable

import os
from firecrawl import FirecrawlApp

firecrawl = FirecrawlApp(api_key=os.environ["FIRECRAWL_API_KEY"])

Verify .gitignore Protects Secrets

set -euo pipefail
# Ensure .env files are gitignored
grep -q "^\.env" .gitignore 2>/dev/null || echo -e "\n.env\n.env.local\n.env.*.local" >> .gitignore

Resources

Next Steps

After successful auth, proceed to firecrawl-hello-world for your first real scrape.