firecrawl/firecrawl — AI 에이전트를
위한 "웹 컨텍스트" API

123k 스타·7.5k 포크·5,475 커밋의 LLM 시대 웹 스크래핑 인프라. 어떤 URL이든 app.scrape() 한 줄이면 JS가 무거운 SPA·PDF·DOCX·이미지까지 깨끗한 마크다운으로 변환해 준다. 단일 페이지 스크래핑부터 전체 사이트 크롤, MCP/Agent Skill 통합, "URL 모르고 결과만 묘사하면 알아서 찾아오는" Agent 엔드포인트까지 한 API에 묶었다. AGPL-3.0 오픈소스 + Mendable사 클라우드 호스팅 듀얼 모델.

1한 줄 요약

Eric Ciarla, Nicolas Camara, Caleb Peffer 세 공동창업자가 Mendable.ai에서 만든 사내 도구를 2024년 오픈소스로 풀었다. 2026년 5월 기준 v2.10까지 34번 릴리즈했고, GitHub 스타 123k로 같은 카테고리의 Scrapling(52k)·crawl4ai(40k급)을 모두 따돌렸다.

2왜 지금 주목받는가

1) RAG·에이전트 시대의 "마지막 1마일"

2024~2026년 LLM 앱 개발의 가장 큰 병목은 "학습 데이터 → 모델"이 아니라, "현재 웹 정보 → 컨텍스트 윈도우"다. ChatGPT가 똑똑해도 어제 발표된 가격 정책을 모르면 무용지물이다.

전통적으로 이 문제는 BeautifulSoup + requests로 직접 짜거나, Selenium/Playwright로 브라우저를 띄워서 해결했다. 둘 다 사이트가 디자인을 바꾸면 깨지고, JS 무거운 SPA는 빈 HTML만 받고, Cloudflare가 막으면 끝. Firecrawl은 이 모든 걸 API 한 통으로 추상화한다.

2) P95 3.4초 · 96% 커버리지의 벤치마크

회사 블로그 글 "The world's best web data API"에 따르면, 수백만 페이지 기준 P95 지연시간 3.4초, 웹 커버리지 96%. 이는 단순 HTTP fetch가 아니라 JS 렌더링 포함 수치다.

경쟁 서비스(Apify, ScrapingBee, Bright Data)는 "성공률 90%대" 광고를 하지만 보통 정적 페이지 기준이거나 Cloudflare 같은 봇 차단 페이지를 제외한 수치. Firecrawl은 "마크다운까지 만들어서 반환"하는 풀-파이프라인의 성공률로 발표한다.

3) MCP + Agent Skill 양쪽 다 1급 지원

2024년 11월 Anthropic이 발표한 MCP(Model Context Protocol)와 Agent Skills 표준을, Firecrawl은 발표 직후부터 공식 지원한다.

# MCP — Claude Desktop, Cursor, Windsurf에 한 줄로 연결
{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": { "FIRECRAWL_API_KEY": "fc-..." }
    }
  }
}

# Agent Skill — Claude Code, Antigravity, OpenCode에 한 줄로 설치
npx -y firecrawl-cli@latest init --all --browser

레포 안에 firecrawl-skills/, firecrawl-cli-skills/, firecrawl-workflows/ 폴더를 따로 두고 운영. 자사 API를 단순 SDK가 아닌 "AI 에이전트의 도구 호출 표준에 정합한 모듈"로 패키징한다.

4) "URL 모르고 결과만 묘사" — /agent 엔드포인트

2026년 들어서 Firecrawl이 새로 추가한 가장 야심찬 기능. 기존에는 /extract로 "이 URL에서 이런 필드 뽑아줘"였다면, /agent는 "이런 정보 찾아줘"만 주면 알아서 검색·탐색·추출한다.

app.agent(prompt="Find the founders of Stripe")
# → 알아서 stripe.com 도달, About 페이지 탐색, 창업자 이름 추출

app.agent(
    prompt="Compare enterprise features across Firecrawl, Apify, and ScrapingBee",
    model="spark-1-pro"
)
# spark-1-pro = 비싸지만 정확한 모델 / spark-1-mini = 60% 저렴한 기본값

이건 사실상 "인터넷을 알아서 도는 에이전트를 API 1회 호출로 빌리는" 가격 모델이다. 일종의 "에이전트 as a Service".

5) AGPL-3.0 + 클라우드 듀얼 라이선스

코어는 AGPL-3.0이라 자기 회사 인프라에 통합해서 비공개 SaaS로 팔려면 라이선스 충돌이 난다. 그래서 "진심으로 셀프호스팅할 사람만 셀프호스팅, 나머지는 firecrawl.dev로 결제"가 자연스럽게 유도된다. 이는 Plausible Analytics, Sentry, Posthog와 동일한 OSS 비즈니스 모델.

3기술 스택 전체 지도

코어 런타임 — TypeScript 모노레포

큐 + 워커 시스템 — 분산 작업 처리의 핵심

스크래핑 엔진 — 4종 백엔드 선택지

AI/LLM 통합 — 9개 벤더 어댑터

Firecrawl이 /extract·/agent·"마크다운에서 JSON 추출" 같은 기능에 LLM을 쓰는데, 사용자가 모델을 자유롭게 고를 수 있도록 Vercel AI SDK v6의 9개 프로바이더를 다 의존성에 포함한다.

덕분에 자체 호스팅 시 OLLAMA_BASE_URL=http://localhost:11434/api + MODEL_NAME=deepseek-r1:7b만 박으면 완전 로컬 LLM 추출도 가능.

마크다운 파이프라인

인프라 + 결제 + 관측

다국어 SDK — 9개 언어 공식 지원

4아키텍처 심화 분석

전체 시스템 구조

핵심 설계 패턴 1 — "두 단계 큐"의 의도된 복잡성

처음 보면 "왜 BullMQ랑 NUQ 둘 다 쓰지?" 싶다. 이유는 작업 성격이 완전히 다르기 때문:

여기에 queue-worker가 같은 컨테이너 안에서 함께 도는 "harness" 패턴이 더해진다. node dist/src/harness.js --start-docker 한 명령으로 API 서버 + 4종 워커가 동시에 뜨도록 했다.

핵심 설계 패턴 2 — Playwright 서비스 격리

브라우저 자동화는 "폭주하면 OOM(out-of-memory)으로 전체 서비스를 죽이는" 가장 위험한 컴포넌트다. Firecrawl은 이걸 별도 컨테이너로 분리해서:

• 리소스 격리: cpus: 2.0, mem_limit: 4G로 자원 상한 박음. OOM되어도 API는 안 죽음.
• tmpfs 캐시: /tmp/.cache를 1GB 메모리 디스크로 마운트(tmpfs:size=1g,noexec,nosuid). 디스크 I/O 회피.
• 동시 페이지 제한: MAX_CONCURRENT_PAGES=10으로 브라우저 인스턴스가 폭주하지 않게.
• 로컬 webhook 차단: ALLOW_LOCAL_WEBHOOKS=false가 기본 — 스크래퍼가 내부망(10.x, 192.168.x)을 찌르지 못하게 SSRF 방어.

핵심 설계 패턴 3 — Rust로 핫패스 격리

@mendable/firecrawl-rs는 회사가 직접 짠 Rust 모듈을 napi-rs(N-API)로 Node.js에서 호출한다. 별도로 Go로 짠 HTML→마크다운 공유 라이브러리(go-html-to-md)는 koffi FFI로 호출한다. 왜 Rust인가?

• HTML → 마크다운 변환은 토큰 수 만~수십만의 텍스트를 정규식·셀렉터로 처리. Node의 V8 GC가 자주 일시 정지해 P95 지연이 튄다.
• Rust로 짜면 메모리 할당이 명시적이라 GC 일시 정지가 0. P95 3.4초 같은 SLA를 지키는 비결.
• 전체 코드의 5.1%만 Rust지만, 처리 시간의 30% 이상을 책임지는 핫패스로 추정.

핵심 설계 패턴 4 — "공개 코어 + 폐쇄 fire-engine" 듀얼

SELF_HOST.md에 명시되어 있다: "Fire-engine은 셀프호스팅에서 사용 불가". Fire-engine은 회사가 운영하는 비공개 엔진이고, IP 로테이션·CAPTCHA 풀이·고급 봇 우회 같은 "운영 노하우"가 담겨 있다.

오픈소스 코어는 Playwright만으로 충분히 동작하지만, "진짜 어려운 사이트(Amazon, LinkedIn, X 등)는 fire-engine으로만 통과"되도록 분리. 이게 클라우드 결제 동기 부여.

5디렉토리 구조 해부

가장 먼저 읽어야 할 파일 3개

6학습 포인트 (기술별)

1) TypeScript 모노레포 운영 노하우

2) BullMQ + RabbitMQ 하이브리드 큐 시스템

3) Playwright 마이크로서비스화

4) Vercel AI SDK로 LLM 멀티-벤더 추상화

5) Rust FFI로 핫패스 격리

6) MCP 서버 + Agent Skill 양쪽 다 지원하기

7) x402 마이크로페이먼트 — "에이전트가 직접 결제"

7하드웨어/시스템 요구사항

최소 사양 (개인 학습용)

운영 권장 사양

10초 설치 체크리스트

# 1. .env 생성 (SELF_HOST.md 템플릿 복사)
PORT=3002
HOST=0.0.0.0
USE_DB_AUTHENTICATION=false
BULL_AUTH_KEY=<강한_랜덤_문자열>
POSTGRES_USER=firecrawl
POSTGRES_PASSWORD=<강한_비번>
POSTGRES_DB=firecrawl
OPENAI_API_KEY=sk-...     # 또는 OLLAMA_BASE_URL=http://localhost:11434/api

# 2. 빌드 + 실행
docker compose build
docker compose up

# 3. 검증
curl -X POST http://localhost:3002/v1/scrape \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com"}'

# 4. 큐 어드민 UI
# http://localhost:3002/admin/<BULL_AUTH_KEY>/queues

8직접 해볼 수 있는 실습 과제

🟢 LV1 (30분): 클라우드 무료 티어로 첫 호출

pip install firecrawl-py
python -c "
from firecrawl import Firecrawl
app = Firecrawl(api_key='fc-YOUR_KEY')
print(app.scrape('https://news.ycombinator.com').markdown[:500])
"

🟢 LV2 (1시간): Claude Desktop에 MCP 등록

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": { "FIRECRAWL_API_KEY": "fc-..." }
    }
  }
}

🟡 LV3 (반나절): 셀프호스팅 + Ollama로 완전 로컬 추출

🟡 LV4 (1주일): 자기 블로그 RAG 챗봇

🔴 LV5 (한 달): Agent 엔드포인트 직접 모방하기

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

공식 자료

• github.com/firecrawl/firecrawl — 메인 레포
• firecrawl.dev — 클라우드 서비스
• docs.firecrawl.dev — 공식 문서
• API Reference — 모든 엔드포인트 명세
• firecrawl.dev/playground — 가입 없이 즉시 테스트
• SELF_HOST.md — 셀프호스팅 가이드
• CLAUDE.md — AI 에이전트용 컨텍스트

커뮤니티 & 통합

• Discord 커뮤니티
• firecrawl-mcp-server — MCP 서버 별도 레포
• firecrawl-cli — CLI + Agent Skill 패키지
• firecrawl-workflows — n8n/Zapier 스타일 워크플로
• 통합 목록 — Lovable, Zapier, n8n 등

레퍼런스 글 (회사 블로그)

• The world's best web data API v2.5 — 96% 커버리지 벤치마크 출처
• /agent 엔드포인트 설계 — Spark 모델 설명

경쟁 / 비교 학습용

• D4Vinci/Scrapling — 파이썬, 적응형 셀렉터
• microsoft/markitdown — 파일 → 마크다운 (Firecrawl이 PDF/DOCX 변환할 때 이런 도구 씀)
• unclecode/crawl4ai — 같은 카테고리 오픈소스 (파이썬)
• apify/apify-sdk-js — Firecrawl의 상용 경쟁사 Apify의 SDK