Firecrawl Local은 웹사이트를 스크래핑하고 크롤링하며, 사이트맵을 매핑해 깔끔한 마크다운으로 변환하는 단일 Rust 바이너리입니다. 모두 여러분의 컴퓨터에서 실행됩니다. 설치는 cargo install firecrawl-local 한 줄이면 되고, API 키도, 데이터베이스도, 큐도, 컨테이너도 없이 localhost:3002에서 Firecrawl v2 API를 제공할 수 있습니다. 검색과 몇 가지 기능은 여전히 Firecrawl Cloud로 요청이 나가지만, 이 역시 꺼둘 수 있습니다.
아래 내용은 내 노트북에서 실행되는 것과 클라우드로 가는 것, 설치 방법, 제공되는 API 라우트, 제약 사항, 그리고 코딩 에이전트가 Apidog CLI로 로컬 API를 테스트하게 만드는 방법을 다룹니다.
Firecrawl Local이란?
Firecrawl Local은 Firecrawl의 오픈소스 온디바이스 에디션입니다. 단일 바이너리로 웹 페이지를 가져오고, 호스팅형 Firecrawl API가 사용하는 것과 동일한 HTML 정리 코드로 가공한 뒤 마크다운, HTML 또는 링크를 반환합니다. CLI로도, AI 에이전트용 MCP 서버로도, Firecrawl v2 API의 로컬 복제본으로도 실행할 수 있습니다.
Firecrawl은 2026년 11월 18일 X의 런칭 게시물에서 이를 공개했으며, 코드는 Firecrawl 저장소의 apps/local 폴더에 있습니다. 패키지는 crates.io에 firecrawl-local이라는 이름으로 게시되어 있고, 저장소는 AGPL-3.0 라이선스입니다.
Firecrawl은 셀프 호스팅 Firecrawl보다 37배 빠르고 메모리는 230분의 1(대기 시 11MB)만 쓴다고 주장합니다. README에는 벤치마크 방법이 공개되어 있지 않으므로, 이는 벤더 주장으로 받아들이는 게 좋습니다.
호스팅형 API나 Firecrawl CLI를 알고 있다면 개념은 간단합니다. 똑같은 호출을, 여러분의 컴퓨터가 처리하는 것입니다.
Firecrawl Local의 동작 방식: 하나의 바이너리, 열 개의 명령어
모든 기능은 firecrawl-local의 서브커맨드 뒤에 있습니다. README에 실린 전체 목록은 다음과 같습니다.
| 명령어 | 하는 일 | 실행 위치 |
|---|---|---|
scrape <urls...> |
하나 이상의 URL 스크래핑 | 내 컴퓨터 |
crawl <url> |
시작 URL부터 링크를 따라 이동 | 내 컴퓨터 |
map <url> |
사이트맵과 시작 페이지에서 사이트의 URL 목록 추출 | 내 컴퓨터 |
serve |
localhost에서 Firecrawl v2 API 실행 | 내 컴퓨터 |
mcp |
stdio 기반으로 Firecrawl MCP 서버 실행 | 내 컴퓨터, 일부 도구는 클라우드 |
init |
이 컴퓨터의 AI 도구에 MCP 서버 등록 | 내 컴퓨터 |
search <query> |
웹 검색 | Firecrawl Cloud |
find-tools <query> |
Alexandria 데이터 프로바이더 찾기 | Firecrawl Cloud, 로그인 필요 |
data <provider> <capability> |
Alexandria 데이터 프로바이더 실행 | Firecrawl Cloud, 로그인 필요 |
login |
브라우저에서 Firecrawl 로그인 | Firecrawl Cloud |
일상적인 작업 대부분은 세 명령어로 해결됩니다.
# Print one page as markdown
firecrawl-local scrape https://example.com --markdown
# Crawl up to 50 pages and save one markdown file per page
firecrawl-local crawl https://docs.firecrawl.dev --limit 50 --out ./pages
# List every URL on a site
firecrawl-local map https://firecrawl.dev
--markdown 없이 scrape를 실행하면 Firecrawl API의 JSON을 출력합니다. --format에는 markdown, html, rawHtml, links를 지정할 수 있습니다. PDF와 Office 문서도 로컬에서 파싱됩니다.
자바스크립트 페이지의 경우, 이미 설치된 Chrome이나 Chromium을 구동합니다. 브라우저가 없어도 정적 페이지는 작동하며, 브라우저가 필요한 페이지는 경고를 반환합니다. Chrome 사용 여부는 --browser auto|never|always로 결정됩니다.
로컬에서 실행되는 것 vs Firecrawl Cloud로 가는 것
스크래핑, 크롤링, 매핑, 문서 파싱은 여러분의 컴퓨터에서 실행되며 Firecrawl에 아무것도 전송하지 않습니다. 다음 세 가지 기능은 노트북에 해당 인덱스나 네트워크, 데이터가 없기 때문에 Firecrawl Cloud로 전달됩니다.
- 검색. 로컬에는 검색 인덱스가 없습니다. 키 없이도 검색은 되지만 속도 제한이 있습니다.
- 내 컴퓨터를 거부하는 페이지. 사이트가 일반 fetch와 로컬 브라우저 모두를 차단한 경우, Firecrawl Cloud가 대신 가져옵니다. 계정은 필요 없습니다.
- Alexandria 데이터 프로바이더. Firecrawl Cloud에서 실행되며 무료 계정이 필요합니다. 이 기능이 무엇인지는 Firecrawl Alexandria 설명 글에서 다룹니다.

FIRECRAWL_CLOUD 환경 변수가 클라우드 전환을 제어합니다.
| 값 | 효과 |
|---|---|
auto (기본값) |
검색, 차단된 페이지 폴백, Alexandria 모두 작동 |
search |
검색만 Firecrawl Cloud로 전달 |
off |
Firecrawl Cloud로 아무것도 전달하지 않음 |
인식할 수 없는 값은 off로 처리됩니다. 클라우드에서 가져온 결과에는 "source": "firecrawl-cloud"가 붙으며, 클라우드마저 실패하면 "blocked": true를 받게 됩니다.
클라우드 호출에는 무작위 설치 ID와 호출 도구의 이름이 함께 전달되며, Firecrawl은 이를 활용해 설치 수를 집계합니다.
Firecrawl Local 설치 방법
Rust와 C 컴파일러가 필요합니다. 그다음은 다음과 같습니다.
- 빌드 도구를 설치합니다. macOS에서는
xcode-select --install을 실행합니다. Debian이나 Ubuntu에서는build-essential을 설치합니다. - Chrome 또는 Chromium을 추가합니다 (선택). 자바스크립트로 렌더링되는 페이지나 스크린샷이 필요할 때 사용합니다.
- Node.js 22 이상을 추가합니다 (선택). MCP 서버를 쓰려면 필요하며,
npx로firecrawl-mcpnpm 패키지를 실행합니다. - 로그인합니다 (선택). Alexandria 프로바이더를 쓰려면
firecrawl-local login을 실행합니다.
crates.io에서 바이너리를 설치하세요.
cargo install firecrawl-local
firecrawl-local --version
최신 코드를 직접 빌드하려면 저장소를 클론한 뒤 apps/local에서 cargo build --release를 실행합니다.
Firecrawl Local API: localhost:3002에서 제공되는 v2 라우트
firecrawl-local serve는 3002 포트에서 Firecrawl v2 API를 제공합니다. 로컬 라우트에는 API 키가 필요 없습니다.
firecrawl-local serve
# in another terminal
curl -s http://localhost:3002/v2/scrape \
-H 'content-type: application/json' \
-d '{"url":"https://example.com","formats":["markdown"]}'
다음 라우트들이 여러분의 컴퓨터에서 실행됩니다.
| 라우트 | 하는 일 |
|---|---|
POST /v2/scrape |
URL 하나 스크래핑 |
POST /v2/map |
사이트의 URL 목록 추출 |
POST /v2/crawl, GET 및 DELETE /v2/crawl/{id} |
크롤 시작, 상태 확인, 취소 |
POST /v2/batch/scrape, GET 및 DELETE /v2/batch/scrape/{id} |
배치 스크래핑 시작, 상태 확인, 취소 |
GET /health |
상태 확인 |
그 밖의 /v2 라우트(예: /v2/search)는 FIRECRAWL_CLOUD 설정이 다르지 않은 한 Firecrawl Cloud로 포워딩됩니다. v0, v1 라우트는 제공되지 않습니다.
기존 코드는 설정 한 줄만 바꾸면 됩니다. 어떤 Firecrawl SDK든 API URL을 http://localhost:3002로 지정하면 됩니다. 스크래퍼나 RAG 파이프라인의 코드는 그대로 두고, 반복 작업을 하는 동안 클라우드 크레딧을 쓰지 않아도 됩니다. 스크래핑 파이프라인 전반에 대해 알고 싶다면 Firecrawl 웹 스크래핑 가이드를 참고하세요.
AI 에이전트용 MCP 서버로 쓰는 Firecrawl Local
firecrawl-local init은 발견한 모든 AI 도구에 Firecrawl Local을 Model Context Protocol 서버로 등록합니다. Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Codex를 지원하며, 각 설정 파일을 먼저 백업하고, --dry-run으로 변경 미리보기를 하거나 --agent cursor로 특정 도구만 설정할 수 있습니다.
에이전트는 표준 Firecrawl MCP 도구를 사용하게 됩니다. 스크래핑, 크롤링, 매핑, 배치 스크래핑은 로컬에서 실행되고, 나머지는 Firecrawl Cloud로 갑니다.
에이전트가 신뢰할 수 없는 사이트를 탐색해야 한다면 firecrawl-local mcp --public-only로 등록하세요. 그렇지 않으면 숨겨진 지시 사항이 있는 페이지에 의해 에이전트가 내부 네트워크의 URL을 열도록 조종될 수 있습니다.
Firecrawl Local의 제약 사항
Firecrawl Local은 전체 Firecrawl 서버가 아닙니다. README에 빠져 있는 기능은 다음과 같습니다.
- 로컬에서
json,summary포맷 미지원. 모델이 필요하기 때문에 로컬 스크래핑에서는 경고와 함께 건너뜁니다. - 브라우저
actions미지원. 클릭, 스크롤, 입력 등의 단계는 무시됩니다. - 스크린샷은 Chrome 필요.
- 작업은 메모리에 저장. 크롤 및 배치 작업은 시작 후 1시간이 지나면 만료되며,
serve가 중지되면 사라집니다. - v0, v1 API 라우트 미제공.
큐, 워커, 모든 포맷이 필요하다면 apps/api의 전체 서버가 여전히 존재하며, Firecrawl의 셀프 호스팅 가이드에서 다룹니다.
알아두어야 할 기본 보안 설정
serve는 다른 프로그램의 요청을 받기 때문에 명령어에 따라 기본값이 다릅니다.
scrape,crawl,map,mcp는 키보드 앞의 사용자를 위해 실행되므로localhost와 사설 네트워크에 접근할 수 있습니다.scrape,crawl,mcp는--public-only를 지정해 이런 주소를 거부할 수 있습니다.serve는127.0.0.1에 바인딩되며,--allow-private를 넘기지 않는 한 localhost와 사설 대상을 거부합니다.--host로 다른 주소에 바인딩하려면--token이 필수입니다.- 링크 로컬 주소와 클라우드 메타데이터 주소는 항상 차단됩니다. 리다이렉트와 DNS 해석 이후에도 마찬가지입니다.
Chrome은 헤드리스 및 샌드박스 모드로 일회용 프로필을 사용해 실행됩니다. 크롤링 시 Firecrawl Local은 Robots Exclusion Protocol에 따라 robots.txt를 읽으며, 사이트 소유자는 FirecrawlLocal라는 이름으로 이를 지정할 수 있습니다.
Firecrawl Local이 필요한 사람
- 스크래퍼나 RAG 파이프라인을 만드는 개발자. 클라우드 사용량으로 비용을 내기 전에 무료로 빠르게 반복 작업을 하고 싶을 때 적합합니다.
- 코딩 에이전트 사용자. 모든 페이지를 제3자를 거치지 않고 Claude Code, Cursor, Codex 안에서 웹을 읽고 싶을 때 적합합니다.
- 데이터 규칙이 있는 팀.
FIRECRAWL_CLOUD=off를 사용해 가져온 콘텐츠가 컴퓨터 밖으로 나가지 않도록 해야 할 때 적합합니다.
json 추출, 브라우저 액션, 장기 크롤 작업에 의존한다면 적합도가 떨어집니다. 에이전트 검색만 필요하다면 Claude용 오픈소스 웹 검색 모음 글을 참고하세요.
코딩 에이전트가 Apidog CLI로 로컬 API를 테스트하게 하기
serve가 실행되면 localhost:3002에 실제 HTTP API가 생깁니다. 파이프라인을 여기에 연결하기 전에, 코드가 기대하는 방식으로 라우트가 응답하는지 확인해 보세요. 요청을 일일이 클릭해서 보내는 대신, 코딩 에이전트에게 Apidog CLI를 쥐여주고 프롬프트 하나를 주면 됩니다.
다음과 같이 한 번만 설정하세요.
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
그다음 에이전트에게 요청하세요.
Start firecrawl-local serve in the background. Write an OpenAPI 3 file for its
local routes (POST /v2/scrape, POST /v2/map, GET /health) and import it into
Apidog project <id>. Create an environment pointing at http://localhost:3002,
add test cases that assert /health returns 200 and /v2/scrape returns
success: true with non-empty data.markdown for https://example.com, then run
them and summarize any failures.

에이전트는 스키마를 읽고, 페이로드를 검증한 뒤, 다음과 같은 명령어를 실행합니다.
firecrawl-local serve &
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-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file ./case.json
apidog run --test-case <caseId> --project <id> -e <envId> -r cli,json
Apidog CLI는 여러분의 컴퓨터에서 요청을 보내므로 localhost:3002에 접근할 수 있습니다. -r cli,json을 -r junit로 바꾸면 같은 실행 결과가 CI에 그대로 들어갑니다. 설정 방법은 Apidog CLI CI/CD 가이드에서, 에이전트 쪽은 Claude Code에서 Apidog CLI 사용하기에서 자세히 볼 수 있습니다. Apidog의 Free 플랜은 최대 4명 규모 팀까지 지원합니다.
FAQ
Firecrawl Local은 무료인가요? 바이너리는 AGPL-3.0으로 오픈소스이며, 로컬 스크래핑, 크롤링, 매핑에는 API 키가 필요 없습니다. 검색, 차단된 페이지 폴백, Alexandria는 Firecrawl Cloud로 가며, Alexandria는 무료 계정이 필요합니다.
기존 Firecrawl SDK 코드를 Firecrawl Local과 함께 사용할 수 있나요? 네, 로컬 라우트에 한해서 가능합니다. SDK의 API URL을 http://localhost:3002로 설정하세요. 스크래핑, 매핑, 크롤링, 배치 스크래핑은 로컬에서 실행되며, v0와 v1 라우트는 제공되지 않습니다.
Firecrawl Local이 클라우드를 호출하지 않게 하려면 어떻게 하나요? FIRECRAWL_CLOUD=off를 설정하세요. 검색과 차단된 페이지 폴백이 작동을 멈추고, 명시적인 login을 제외하면 아무것도 여러분의 컴퓨터를 떠나지 않습니다.
Firecrawl Local은 셀프 호스팅 Firecrawl과 무엇이 다른가요? 셀프 호스팅 Firecrawl은 apps/api의 전체 서버로, 큐와 워커, 모든 포맷을 갖추고 있습니다. Firecrawl Local은 json과 summary 포맷, 브라우저 액션, 영구 작업을 제거한 더 가벼운 단일 바이너리입니다.
