LLM 애플리케이션에 웹 데이터가 필요한데, 현실은 이렇다: 페이지의 96%는 JS 렌더링이 필요하거나 봇 차단이 걸려 있다. Playwright로 시도하면 차단당하고, 프록시 풀은 불안정하고, 동적 콘텐츠는 누락되고, 추출한 텍스트엔 <div> 노이즈가 가득하다. 온갖 함정이 도사리고 있다.
Firecrawl은 이 모든 걸 하나의 API로 묶었다. URL을 넘기면 깔끔한 Markdown이나 구조화된 JSON이 나온다. GitHub에서 169,837 stars를 받았고, 메인 레포지토리는 TypeScript로 작성됐으며 AGPL-3.0 라이선스(SDK는 MIT)를 따른다. 공식 벤치마크 기준 P95 3.4초 지연 시간을 자랑하며, JS 위주의 SPA를 포함해 96%의 웹 페이지를 처리할 수 있다고 한다.
아래에서 사용법, 동작 원리, 장단점을 차근차근 뜯어본다.
해결하려는 문제
RAG나 Agent를 만드는 사람에게 가장 골치 아픈 건 데이터 소스다. LLM은 HTML을 받아들이지 못하고, 깔끔한 구조화된 텍스트를 원한다. 크롤러를 직접 작성하면 유지보수 비용이 천문학적이다.
- 봇 차단 지문 감지(Cloudflare, DataDome, PerimeterX)
- 주거용 IP 프록시 풀은 비용도 들고 로테이션 전략이 필요
- 지연 로딩은 스크롤과 대기 시뮬레이션 필수
- 로그인 벽, 쿠키, JS Challenge 처리
- 콘텐츠 정제: 광고, 네비게이션 바, 쿠키 배너를 걸러내야 함
Firecrawl은 이런 작업을 전부 떠안는다. URL만 넘기면 prompt에 바로 넣을 수 있는 Markdown을 돌려받을 수 있다.
사용법
Python SDK라면 몇 줄이면 끝이다:
from firecrawl import Firecrawl
app = Firecrawl(api_key="fc-YOUR_API_KEY")
# 1. 단일 페이지 scrape, 깨끗한 Markdown 반환
result = app.scrape("https://example.com", formats=["markdown"])
print(result.markdown[:500])
# 2. 사이트 전체 crawl, 최대 10 페이지
crawl_result = app.crawl("https://docs.example.com", limit=10)
for page in crawl_result.data:
print(page.metadata.url, "->", page.markdown[:100])
# 3. Actions: 클릭 시뮬레이션 후 크롤링
result = app.scrape(
"https://example.com/dashboard",
actions=[
{"type": "click", "selector": "button#load-more"},
{"type": "wait", "milliseconds": 2000},
],
formats=["markdown"]
)
print(result.markdown)
핵심 기능은 7가지다: scrape(단일 페이지), crawl(사이트 전체), search(전문 검색 포함), batch(비동기批量), map(URL 발견), agent(자율 네비게이션), interact(브라우저 인터랙션).
MCP 통합은 더 간단하다. 명령어 한 줄이면 Claude Desktop이나 Cursor에 붙는다:
claude mcp add firecrawl --env FIRECRAWL_API_KEY=fc-YOUR_API_KEY -- npx -y firecrawl-mcp-server
설치 후엔 대화에서 "이 페이지 내용 좀 가져와줘"라고만 말하면 된다. Agent 도구 생태계 쪽에서는 Firecrawl이 가장 네이티브한 축에 속한다.
배포 옵션은 두 가지다: Docker Compose로 셀프 호스팅하거나, 관리형 SaaS를 그대로 쓴다. 셀프 호스팅은 Postgres, Redis, Playwright 클러스터를 직접 굴려야 해서 리소스 소모가 적지 않고, 관리형은 운영 부담 없이 호출량 기반 과금이다.
동작 원리 (아키텍처)
3계층 파이프라인 구조다.
1. 인게스트 계층 — API Gateway + 작업 큐(BullMQ 같은 것). 요청이 들어오면 API key 검증, rate limit, 큐 적재까지 처리한다.
2. 스크래핑 계층 — 가장 무거운 부분이다. 세 가지 컴포넌트로 나뉜다.
- 프록시 로테이션 풀: 주거용 IP 프록시와 데이터센터 프록시를 섞어 쓰고, 대상 사이트별로 전략을 바꾼다
- Playwright/CDP 클러스터: headless Chromium 인스턴스 풀. browser context를 재사용해 기동 비용을 아낀다
- Actions 실행기: DSL로 클릭, 스크롤, 입력, 대기, 키 입력을 실행. CSS selector와 XPath 모두 지원
3. 추출 계층 — HTML은 여러 단계를 거쳐 Markdown으로 변환된다(Mozilla Readability를 개조한 버전 기반). PDF/DOCX는 전용 파서 경로(pdf-parse + mammoth)를 타며, LLM 기반 구조화 추출(schema 지정 → JSON 출력)도 옵션으로 제공한다.
주요 설계 포인트는 다음과 같다.
- 지능형 fallback: 먼저 일반 HTTP 요청을 시도하고(빠르다), 콘텐츠를 제대로 못 가져오면 headless 브라우저로 승격
- 콘텐츠 중복 제거: SimHash 기반. 페이지 간 비슷한 콘텐츠는 한 번만 남긴다
- 증분 crawl: sitemap + last-modified로 차분 업데이트
코드 측면에서 메인 레포는 TypeScript(firecrawl/firecrawl)이고, SDK는 별도 레포로 관리된다: Python, Node, Go, Rust 네 가지.
장점 / 단점
장점:
- 별도 설정 없이 5분 만에 동작
- 안정성 우수, 공식 벤치마크 P95 3.4초
- 커버리지 넓음, 96% 웹 페이지(JS-heavy 포함) 지원 주장
- PDF / DOCX / 이미지 OCR 지원
- Actions API로 복잡한 인터랙션 시뮬레이션 가능
- Agent / MCP 네이티브 친화적, 169k stars 커뮤니티 활발
단점:
- 관리형 가격 부담 있음 — 500 credits부터 시작이고, 복잡한 페이지(JS 렌더링 + Actions)는 한 번에 5~10 credits 소모
- 셀프 배포는 리소스 소모 큼. headless Chromium 클러스터 메모리 사용량이 만만치 않다
- 백만 단위 대규모 크롤링은 별도 튜닝 필요(큐, 동시성, 프록시 풀을 직접 손봐야 함)
- Crawl4ai 같은 순수 오픈소스 경량 솔루션보다 무거움
- AGPL-3.0 라이선스라 폐쇄 소스 상용화에 주의 필요
직접 써봤다
self-hosted Docker Compose를 받아 로컬에서 띄워봤다. Postgres + Redis + 여러 worker + Playwright까지 서비스가 한 무더기로 올라온다.
테스트 1: JS-heavy SPA 페이지(Twitter/X 게시물)를 크롤링했다. 반환된 Markdown이 깨끗하고 완전했다. 텍스트, 이미지 alt, 코드 블록이 모두 포함돼 있었다. 같은 URL을 requests로 시도하면 <div id="root"></div> 빈 껍데기만 돌아왔다.
테스트 2: Actions API로 "더 보기" 버튼을 클릭한 뒤 크롤링했다. 설정은 다음과 같다.
actions=[
{"type": "click", "selector": "button.load-more"},
{"type": "wait", "milliseconds": 2000},
{"type": "scroll", "direction": "down"},
]
지연 로딩된 리스트 콘텐츠를 정상적으로 가져왔다.
테스트 3: 100개 URL을 batch scrape했다. 평균 2.8초/페이지로 공식 P95 수치와 일치했다. 실패율은 2%(주로 로그인이 필요한 페이지)였고, 한 번 재시도하니 0%로 떨어졌다.
총평: 로컬 셀프 배포는 쓸 만하지만 묵직하다. 운영 환경이면 차라리 관리형을 쓰는 게 정신건강에 이롭다.
누가 써야 하나
적합한 대상:
- RAG용 웹 데이터 소스가 필요한 팀
- Agent 제품에 안정적인 웹 도구가 필요한 경우(특히 Claude/Cursor 연동)
- 산업 리서치, 경쟁사 모니터링
- 자체 지식 베이스를 만드는 1인 개발자
부적합한 대상:
- 정적 페이지 몇 개만 긁으면 되는 경량 시나리오 —
requests + BeautifulSoup이면 충분 - 순수 학술 크롤링 연구 — Firecrawl은 상용 제품이니 Scrapy로 직접 가는 게 낫다
- 예산이 zero이고 셀프 배포도 거부하는 경우 — Crawl4ai나 Jina Reader를 알아보는 게 좋다
Firecrawl은 사실상 Agent 제품의 기본 옵션 중 하나다. 직접 경쟁하는 제품으로는 Jina Reader(더 가볍고 무료 플랜 친화적)와 Crawl4ai(순수 오픈소스, 셀프 호스팅 친화적)가 있다. 리소스 제약과 Agent 통합 깊이를 보고 골라야 한다.
참고: