DEV Community

Cover image for How to Use Firecrawl Local with Claude Code and Cursor (MCP)
Hassann
Hassann

Posted on Originally published at apidog.com

How to Use Firecrawl Local with Claude Code and Cursor (MCP)

To use Firecrawl Local, install it with cargo install firecrawl-local, run firecrawl-local init to register it as an MCP server in Claude Code and Cursor, then restart both tools. Your agent can now scrape, crawl and map sites on your own machine. For code, run firecrawl-local serve and point any Firecrawl SDK at http://localhost:3002.

Try Apidog today

This guide shows how to use Firecrawl Local step by step, with the real output from our test run on November 19, 2026 (Firecrawl Local 0.1.0 on an arm64 Mac), plus the prompts to give your agent and a way to let that agent test the local API with Apidog CLI.

What you need before you start

Firecrawl Local is one Rust binary from the Firecrawl repository. Before you install it, check you have:

  1. Rust and a C compiler. Get Rust from rustup.rs. On macOS run xcode-select --install; on Debian or Ubuntu install build-essential.
  2. Node.js 22 or newer if you want the MCP server. It runs the firecrawl-mcp npm package through npx.
  3. Chrome or Chromium (optional). Firecrawl Local uses the browser you already have for pages that need JavaScript. Static pages work without it.
  4. Claude Code, Cursor or another MCP client. init also knows Claude Desktop, Windsurf, Gemini CLI and Codex.

If you're new to Firecrawl itself, start with our Firecrawl web scraping guide and come back.

Step 1: Install Firecrawl Local

Install the crate from crates.io and confirm the version:

cargo install firecrawl-local
firecrawl-local --version
# firecrawl-local 0.1.0
Enter fullscreen mode Exit fullscreen mode

Cargo compiles it from source. On our Mac the release build finished in 6 minutes 54 seconds, and the binary landed in ~/.cargo/bin/firecrawl-local. Make sure that folder is on your PATH, or note the full path: you'll need it for manual MCP setup.

Step 2: Run your first scrape from the terminal

Before you wire anything into an agent, check that fetching works:

FIRECRAWL_CLOUD=off firecrawl-local scrape https://example.com --markdown
Enter fullscreen mode Exit fullscreen mode

It printed the page's main text as markdown in 1.2 seconds. Drop --markdown and you get the same JSON the Firecrawl API returns. --format markdown,links picks formats; the local choices are markdown, html, rawHtml and links.

Next, a crawl that writes one markdown file per page:

FIRECRAWL_CLOUD=off firecrawl-local crawl https://docs.firecrawl.dev --limit 20 --out ./pages
Enter fullscreen mode Exit fullscreen mode

This fetched 20 pages of the Firecrawl docs in 4.4 seconds and saved files named like 0005-docs.firecrawl.dev_advanced-scraping-guide.md. Useful crawl flags from firecrawl-local crawl --help:

Flag What it does
-l, --limit Maximum pages (default 100)
--max-depth How many links deep to follow
--include, --exclude Path regex to keep or skip, repeatable
--entire-domain Follow links outside the start path
-c, --concurrency Pages fetched at once
--ignore-robots Skip robots.txt (it's read by default)

firecrawl-local map https://firecrawl.dev returns every URL it finds from the sitemaps and start page, as one JSON line.

Step 3: Add Firecrawl Local to Claude Code and Cursor with init

init finds the AI tools on your machine and adds Firecrawl Local to each one's MCP config. Preview it first:

firecrawl-local init --dry-run
Enter fullscreen mode Exit fullscreen mode

On our Mac it listed every tool it would touch:

Firecrawl MCP server:
  Claude Code: would be added in ~/.claude.json
  Claude desktop: would be added in ~/Library/Application Support/Claude/claude_desktop_config.json
  Cursor: would be added in ~/.cursor/mcp.json
  Gemini CLI: would be added in ~/.gemini/settings.json
  Codex: would be added in ~/.codex/config.toml
Enter fullscreen mode Exit fullscreen mode

The dry run also prints what goes to Firecrawl Cloud: search queries, the URL of a page that blocked your machine, Alexandria calls once you sign in, and a random install ID plus your AI tool's name. Pages that load fine locally are never sent.

To set up only the two tools this guide covers, repeat --agent:

firecrawl-local init --agent claude-code --agent cursor
Enter fullscreen mode Exit fullscreen mode

The valid names are claude-code, claude-desktop, cursor, windsurf, gemini and codex. init backs up each config file before it writes. Restart Claude Code and Cursor afterwards so they load the new server.

Claude Code and Cursor talk to firecrawl-local mcp over stdio; it scrapes, crawls and maps on your machine and only sends search and blocked pages to Firecrawl Cloud unless FIRECRAWL_CLOUD=off

Firecrawl Local in Claude Code by hand

If you'd rather not let a tool edit your configs, add the stdio server yourself with the Claude Code MCP command:

claude mcp add firecrawl -e FIRECRAWL_CLOUD=off -- ~/.cargo/bin/firecrawl-local mcp --public-only
Enter fullscreen mode Exit fullscreen mode

Run /mcp inside Claude Code to confirm the server is connected.

Firecrawl Local in Cursor by hand

Cursor reads MCP servers from ~/.cursor/mcp.json (global) or .cursor/mcp.json (one project). Use the full path to the binary:

{
  "mcpServers": {
    "firecrawl": {
      "command": "/Users/you/.cargo/bin/firecrawl-local",
      "args": ["mcp", "--public-only"],
      "env": { "FIRECRAWL_CLOUD": "off" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

--public-only makes the server refuse localhost and private-network addresses. Keep it on when your agent reads pages you don't trust: hidden instructions on a page could otherwise steer the agent toward an internal URL.

Step 4: Prompts to give your agent

firecrawl-local mcp starts the local API on a loopback port and runs the firecrawl-mcp package against it. Your agent sees the standard Firecrawl MCP tools; scrape, crawl, map and batch scrape run on your machine. If you've used the hosted Firecrawl MCP server, the tool names are the same.

Prompts that fit the local tools well:

Map https://docs.example.com, then crawl only the /api/ pages (limit 40)
and write a summary of every endpoint into docs/vendor-api.md.
Enter fullscreen mode Exit fullscreen mode
Scrape the changelog at https://example.com/changelog as markdown and list
every breaking change from the last three releases.
Enter fullscreen mode Exit fullscreen mode
Batch scrape these five pricing pages and build a comparison table of
plan names and limits. Quote only what the pages say.
Enter fullscreen mode Exit fullscreen mode

Skip prompts that need search: with FIRECRAWL_CLOUD=off that tool goes nowhere. For a fully local search setup, see our open-source web search for Claude guide.

Step 5: Run the Firecrawl Local API and point your SDK at it

For scripts and pipelines, run the API server:

FIRECRAWL_CLOUD=off firecrawl-local serve
Enter fullscreen mode Exit fullscreen mode

It listens on 127.0.0.1:3002. The health check answers right away:

curl -s localhost:3002/health
# {"status":"ok","engine":"firecrawl-local","version":"0.1.0"}
Enter fullscreen mode Exit fullscreen mode

A scrape returns the familiar v2 shape, with two local markers in it: "engine": "local-fetch" and "source": "local", and creditsUsed: 0.

curl -s localhost:3002/v2/scrape -H 'content-type: application/json' \
  -d '{"url":"https://example.com","formats":["markdown","links"]}'
Enter fullscreen mode Exit fullscreen mode

Point the Firecrawl SDKs at it with no API key. Python:

from firecrawl import Firecrawl

app = Firecrawl(api_url="http://localhost:3002")
print(app.scrape("https://example.com").markdown)
Enter fullscreen mode Exit fullscreen mode

Node:

import { Firecrawl } from "firecrawl";

const app = new Firecrawl({ apiUrl: "http://localhost:3002" });
const doc = await app.scrape("https://example.com");
console.log(doc.markdown);
Enter fullscreen mode Exit fullscreen mode

init suggests a shortcut too: set FIRECRAWL_API_URL=http://127.0.0.1:3002 and your existing Firecrawl code runs locally. The Firecrawl CLI shares its saved login with Firecrawl Local, so either tool's login works for both.

Crawls are async. POST /v2/crawl returned a job ID at once, and GET /v2/crawl/{id} reported status: completed, total: 10, creditsUsed: 0 and expiresInSeconds: 3587 a few seconds later. Jobs live in memory, expire an hour after they start and vanish when serve stops, so save results as soon as a crawl completes.

The server process sat at about 10 MB resident memory idle and 43 MB right after that 10-page crawl, measured with ps. Firecrawl's launch post claims 37x faster and 230x less memory than self-hosted Firecrawl; the README publishes no method, so treat those as Firecrawl's figures.

Keep Firecrawl Local fully local with FIRECRAWL_CLOUD

By default (auto), three things go to Firecrawl Cloud: search, pages that block your machine, and Alexandria data providers (which need a free account via firecrawl-local login). FIRECRAWL_CLOUD controls the hand-off:

Value Effect
auto (default) Search, blocked-page fallback and Alexandria all work
search Only search goes to Firecrawl Cloud
off Nothing goes to Firecrawl Cloud

An unrecognized value counts as off. With the cloud off, POST /v2/search answers "code":"CLOUD_ONLY" with a message telling you to set FIRECRAWL_API_KEY or FIRECRAWL_CLOUD=auto. A page the cloud fetched for you carries "source": "firecrawl-cloud", so you can always tell where a result came from.

serve refuses localhost and private targets unless you pass --allow-private, and binding a non-loopback --host requires --token. Cloud metadata and link-local addresses are blocked in every mode.

Let your coding agent test the Firecrawl Local API with Apidog CLI

The crawl endpoint is the one most likely to break a pipeline: it's async, the job expires, and a stopped server loses it. Instead of polling by hand, let your coding agent build and run a test with Apidog CLI.

Set it up once:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
Enter fullscreen mode Exit fullscreen mode

Then give Claude Code or Cursor one prompt:

firecrawl-local serve is running on http://localhost:3002. In Apidog project <id>,
import an OpenAPI file for POST /v2/scrape, POST /v2/crawl and GET /v2/crawl/{id},
create an environment for that base URL, and build a test scenario that starts a
crawl of https://docs.firecrawl.dev with limit 10, saves the returned id, polls
GET /v2/crawl/{id} until status is "completed", and asserts total equals completed
and every page has non-empty markdown. Run it and summarize any failures.
Enter fullscreen mode Exit fullscreen mode

Sequence of the agent-built test: Apidog CLI posts /v2/crawl to firecrawl-local serve, polls GET /v2/crawl/{id} until completed, checks the assertions and writes a cli, json or junit report

The agent reads each payload schema, validates it and runs commands like these, all taken from apidog <cmd> --help in CLI 2.2.12:

apidog import --project <id> --format openapi --file ./firecrawl-local-v2.yaml
apidog environment create firecrawl-local --project <id> --base-url http://localhost:3002
apidog cli-schema get test-scenario-create
apidog cli-schema validate test-scenario-create --file scenario.json
apidog test-scenario create --project <id> --file ./scenario.json
apidog run -t <scenarioId> --project <id> -e <envId> -r cli,json
Enter fullscreen mode Exit fullscreen mode

Apidog CLI sends requests from your machine, so localhost:3002 is reachable. Switch to -r junit to drop the same run into CI; our Apidog CLI in Claude Code and Apidog CLI in Cursor guides cover the agent side. Apidog's Free plan covers teams of up to 4 users.

Troubleshooting Firecrawl Local

Symptom Fix
404 with NOT_FOUND on /v1/scrape Only v2 is served; switch your client to /v2/...
CLOUD_ONLY on /v2/search Expected with FIRECRAWL_CLOUD=off; use auto or search
Agent doesn't list Firecrawl tools Restart the tool after init; check Node.js 22+
JavaScript page comes back thin Install Chrome, or set --browser always
json or summary format missing Not supported locally; you get a warning instead
Crawl ID not found The job expired after an hour or serve restarted

FAQ

Is Firecrawl Local free? Local scraping, crawling and mapping send nothing to Firecrawl and used 0 credits in our tests. The code is AGPL-3.0; the SDKs are MIT. Search and Alexandria go through Firecrawl Cloud.

Do I need an API key to use Firecrawl Local? No, not for local routes. You only need a key, via firecrawl-local login or FIRECRAWL_API_KEY, for Alexandria data providers.

Does Firecrawl Local work with Windsurf, Codex and Gemini CLI? Yes. init knows windsurf, codex and gemini as well as Claude Code, Claude Desktop and Cursor.

Can my existing Firecrawl code run against it unchanged? For v2 scrape, map, crawl and batch scrape, yes: change the API URL to http://localhost:3002. v0 and v1 routes aren't served, and browser actions are ignored.

Does Firecrawl Local respect robots.txt? Yes. It reads robots.txt when crawling and identifies itself in its User-Agent, so site owners can address it as FirecrawlLocal. --ignore-robots turns that off; use it only on sites you own.

Top comments (0)