Firecrawl

1. What is Firecrawl?

Firecrawl pulls the content out of web pages and hands it back as clean text (Markdown or structured data), without menus, ads and clutter. You give it a link; it returns the main text of the page. It can also search the web, crawl an entire site, or list every link on a site. Its main purpose is feeding web data to AI assistants.

Firecrawl comes in two forms. The cloud service at firecrawl.dev: sign up and use it, billed in "credits", with a free tier. The open-source version (AGPL-3.0 license): run it yourself with Docker on your own machine or server, with no service fee but without some cloud features.

To be direct: Firecrawl is a tool for developers and people who work with AI. Even so, a non-technical person can try it on the web without installing anything.

A good fit if:

• You want to turn articles or documentation into tidy text to give to ChatGPT, Claude or another AI tool.
• You use Claude Code, Cursor or Codex and want your assistant to read the web by itself.
• You are building a product that needs web data and do not want to write your own scraper.

Not a good fit if:

• You only need to save a page or two: copy and paste is quicker.
• You want a desktop app with windows and buttons. Firecrawl has no such edition.
• You plan to collect personal data or content a site forbids. The project states that users are solely responsible for respecting each site's policies.

2. What do you need first?

It depends on how you use it:

Way of using it	What you need	Does it cost money?
Try it on the web (Playground)	A browser; possibly a Firecrawl account	Free tier
Command line (CLI)	A computer and Node.js	Free within limits; a free key raises them
Inside an AI assistant	Node.js and an assistant such as Claude Code, Cursor, Codex or OpenCode	Credits on your Firecrawl account
Self-hosting	Git, Docker and a reasonably capable machine	No service fee; you run the hardware

What those programs are:

• Node.js: the runtime for JavaScript programs; it brings the npm and npx commands. Download from https://nodejs.org/.
• Git: downloads source code. Download from https://git-scm.com/downloads.
• Docker Desktop: runs software in isolated "containers". Download from https://www.docker.com/.

API key: sign up at https://firecrawl.dev to get a key, which starts with fc-. According to the billing page the free plan includes 1,000 credits per month (unused credits do not roll over; when they run out, requests fail until the next cycle). For scale: scraping one page costs 1 credit; a search costs 2 credits per 10 results. Paid plan prices change over time, so check https://www.firecrawl.dev/pricing.

3. Step-by-step installation

Step 1: Try it on the web (easiest, nothing to install)

1. Open https://firecrawl.dev and create a free account if the site asks for one.
2. Open https://firecrawl.dev/playground.
3. Paste the link to an article into the input box and run it.

What success looks like: the page returns the article as Markdown text (headings marked with #, lists with -), with the menus and ads gone.

If you only need the text of a few pages now and then, you can stop here.

Step 2: Install the command-line tool (CLI)

Install Node.js first, then run:

npm install -g firecrawl-cli

Check it:

firecrawl --status

What success looks like: it prints "firecrawl cli" with a version number and your authentication status.

Step 3: Log in

firecrawl login

This opens a browser for you to sign in, or asks for an API key. If you already have a key you can log in directly (use your real key):

firecrawl login --api-key fc-YOUR-API-KEY

What success looks like: firecrawl --status now shows an "Authenticated" line and your remaining credits.

Note: According to the documentation, some commands such as scrape and search also work without logging in, but with a daily cap per network address.

Step 4 (optional): Connect Firecrawl to your AI assistant

If you use Claude Code, Cursor, Codex or OpenCode, this one command installs the Firecrawl skills for every assistant it detects and opens a browser to authenticate:

npx -y firecrawl-cli@latest init --all --browser

Then restart the assistant. What success looks like: you ask the assistant "use Firecrawl to read this page for me" and it does.

For apps that speak MCP (the standard that lets AI assistants call outside tools), add this block to the app's MCP config file, replacing the key with your own:

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "fc-YOUR_API_KEY"
      }
    }
  }
}

Step 5 (advanced): Self-host Firecrawl with Docker

Do this only if you truly need control over the infrastructure. The official documentation recommends the cloud service if you just want to get going. The self-hosting guide was verified against release v2.11.162.

Download the source and switch to that exact release:

git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl
git checkout v2.11.162

Create a file named .env in the root firecrawl folder with these four lines. Replace the password with a random string of at least 32 characters:

USE_DB_AUTHENTICATION=false
POSTGRES_USER=postgres
POSTGRES_PASSWORD=replace-with-at-least-32-random-characters
POSTGRES_DB=postgres

Start Docker Desktop, then build and launch:

docker compose up --build -d
docker compose ps --all

Warnings about unset optional variables are expected. Check that the service is up:

curl --fail --silent --show-error --max-time 5 http://localhost:3002/v0/health/readiness

What success looks like: the reply is {"status":"ok"}. Then point the CLI at your own instance and scrape one page:

firecrawl --api-url http://localhost:3002 scrape https://example.com

Note: This configuration turns authentication off, so anyone who can reach port 3002 can use it. Run it only on a network you trust and never expose it to the internet.

4. First use

With the CLI installed, try these three things.

Fetch the main content of a page and save it to a file:

firecrawl https://example.com --only-main-content -o output.md

What success looks like: a file named output.md appears in the current folder. Open it in Notepad and you will see the text of the page.

Search the web and get five results:

firecrawl search "firecrawl" --limit 5

Take a screenshot of a page:

firecrawl https://example.com --screenshot

Firecrawl's main capabilities:

Name	What it does
Scrape	Turns one link into Markdown, HTML, a screenshot or structured data
Search	Searches the web and returns the content of the results
Crawl	Fetches every page of a website from a single request
Map	Lists every link on a website
Interact	Fetches a page and then acts on it (click, type) from a prompt or code
Agent	You describe the data you want and an AI agent finds and gathers it

Note: Crawl can burn through credits quickly, because every page costs one. Always set a page limit when crawling a whole site.

5. Common problems and fixes

npm, npx or firecrawl is not recognised

• Symptom: "command not found" or "is not recognized".
• Cause: Node.js is not installed, or the terminal was opened before installing it.
• Fix: install Node.js, close and reopen the terminal, then repeat Step 2.

Requests are rejected with 429

• Symptom: a request returns error 429.
• Cause: you passed your plan's requests-per-minute or parallel-job limit; or you are using it without a key and the daily allowance is spent.
• Fix: wait and retry more slowly. Log in with a free key for higher limits.

Out of credits while crawling (402)

• Symptom: a crawl is refused with status 402.
• Cause: your remaining credits do not cover the request.
• Fix: check your balance with firecrawl --status, lower the page limit, or upgrade the plan.

The AI assistant cannot see Firecrawl after installing

• Symptom: you ran the init command but the assistant says it has no such tool.
• Cause: the assistant has not been restarted.
• Fix: quit it completely and open it again. For MCP, check that the key in the env block is filled in correctly.

Self-hosted: containers will not start or port 3002 does not answer

• Symptom: docker compose ps --all shows services that have exited, or the check in Step 5 fails.
• Cause: Docker is short of CPU, memory or disk; the .env file has a syntax error; another program is using port 3002.
• Fix: read the logs with the command below. Give Docker more resources, keep POSTGRES_DB=postgres, and stop whatever occupies port 3002.

docker compose logs --tail=200

Self-hosted: no screenshots, no Agent

• Symptom: commands that work on the cloud service do nothing on your own instance.
• Cause: the documentation states that the default self-hosted stack has no screenshots, page actions, Agent or Interact.
• Fix: use the cloud service for those features.

6. Uninstalling and updating

CLI:

• Log out to clear stored credentials:

firecrawl logout

• Remove it with npm's standard command:

npm uninstall -g firecrawl-cli

• Update: run the install command from Step 2 again. If you call it through npx ... firecrawl-cli@latest, every run already fetches the newest version.

Self-hosted:

• Stop and remove the containers:

docker compose down

• Delete the firecrawl folder to remove the source completely.
• Update: the documentation says to review the new release's docker-compose.yaml and self-hosting notes first, because the configuration can change between releases. Then git checkout the newer tag and rebuild.

Versions: the GitHub Releases page lists v2.11.0 (19 June 2026) as the latest release; the repository keeps tagging smaller builds after that, and the official self-hosting guide uses tag v2.11.162.

Account: if you stop using it, sign in at firecrawl.dev and manage your API keys from your account pages.

7. Frequently asked questions

Does it cost anything? There is a free tier: the free plan includes 1,000 credits per month, and some commands even work without a key under a low daily cap. Heavier use means a paid plan. Self-hosting has no service fee, but you provide the machine.

Do I need an internet connection? Yes. Firecrawl fetches data from the internet; even a self-hosted instance has to reach out to load pages.

Is my data sent anywhere? With the cloud service and the CLI, the links you submit and the content fetched pass through Firecrawl's servers. With self-hosting, processing happens on your machine, though it still sends requests to the sites being fetched.

Is scraping like this legal? It depends on the site and on what you do with the data. The project states that end users are solely responsible for respecting websites' policies, and that by default Firecrawl follows robots.txt (the file a site uses to say what crawlers may not touch).

Will it run on a weak computer? The cloud service and CLI are light, because the heavy work happens on Firecrawl's servers. Self-hosting builds and runs several services at once; Firecrawl does not publish a minimum machine size for it.