본문으로 건너뛰기
JournalTORIS / FIELD NOTES

← 블로그AI 인사이트

Firecrawl & Firecrawl Local — DB 없이 내 PC에서 웹사이트를 AI용 마크다운·MCP로 바꾸는 법

깃허브 트렌딩 1위 Firecrawl(205K+ Stars)과 신기능 Firecrawl Local의 설치·MCP 연동(Claude Code/Cursor)·localhost:3002 API 활용법 및 Cloud 비교 정리.

#Firecrawl #Firecrawl Local #MCP #Claude Code #웹크롤링 #마크다운 #오픈소스

Read in English

Firecrawl & Firecrawl Local — DB 없이 내 PC에서 웹사이트를 AI용 마크다운·MCP로 바꾸는 법

Q. DB나 Docker 컨테이너 없이 내 컴퓨터에서 웹사이트를 AI용 마크다운으로 바꿔주는 도구가 있나요? 네, Firecrawl Local(cargo install firecrawl-local)을 쓰면 됩니다. Rust 기반 단일 바이너리로 내 PC의 Chrome/Chromium을 활용해 정적·동적 웹페이지와 PDF·오피스 문서를 마크다운으로 변환하고, firecrawl-local init 한 줄로 Claude Code·Cursor·Windsurf 등에 MCP 서버까지 자동 등록합니다. 클라우드 기반 Firecrawl Keyless를 쓰면 가입과 API 키 없이도 월 1,000 크레딧까지 무료로 시작할 수 있습니다.

⚠️ 정확도 가드레일: 이 글은 2026년 11월 21일 기준 firecrawl/firecrawl 공식 GitHub 저장소(Stars 205,091, Forks 10,748, AGPL-3.0 / SDK MIT, 최신 릴리즈 v2.11.0)와 공식 README, 그리고 토리스 스튜디오 유튜브 11월 20일 깃허브 트렌딩 TOP 10 영상을 직접 대조해 작성했습니다. Firecrawl Cloud의 웹 커버리지(96%)와 P95 레이턴시(3.4s)는 공식 README에 제시된 수치이며, 실제 환경·대상 사이트의 봇 차단 정책에 따라 결과가 달라질 수 있습니다.

30초 요약

  • Firecrawl Local 도입: 데이터베이스·큐·Docker 없이 단일 바이너리로 내 PC에서 scrape·crawl·map을 실행하고 localhost:3002 v2 API 서버까지 띄울 수 있습니다.
  • 원커맨드 MCP 연동: firecrawl-local init을 실행하면 Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Codex 설정 파일을 자동 백업한 뒤 로컬 MCP 서버(Node.js 22+ 필요)로 붙여줍니다.
  • 클라우드 폴백 & 완전 격리 선택: 로컬 Chrome에서 열리지 않는 단일 페이지는 기본적으로 Firecrawl Cloud(무가입 제한적 호출 가능)로 넘기지만, FIRECRAWL_CLOUD=off 환경변수로 완전 오프라인 격리도 가능합니다.
  • Keyless & Alexandria: Firecrawl Cloud는 API 키 없이 월 1,000 크레딧(Keyless)을 제공하며, 유료/로그인 환경에서는 550개 이상 데이터 프로바이더(Alexandria)·AI 브라우저 조작(Interact)·자율 수집(Agent)까지 확장됩니다.

Firecrawl이 AI 에이전트 인프라의 표준이 된 이유

Firecrawl은 단순 HTML 파서가 아니라 LLM이 토큰 낭비 없이 즉시 읽을 수 있는 깨끗한 마크다운과 구조화 데이터를 공급하는 지식 인프라입니다.

기존 웹 스크래핑은 내비게이션 바, 광고 스크립트, 중첩된 <div> 태그까지 함께 긁어와 컨텍스트 윈도우를 낭비하는 경우가 많았습니다. Firecrawl은 본문 중심 마크다운 추출을 기본으로 삼고, Python·Node.js·Go·Rust·Java·Ruby·.NET·PHP·Elixir 등 주요 언어 SDK와 MCP를 공식 지원합니다. 덕분에 코딩 에이전트나 리서치 워크플로우에 붙이는 수고가 크게 줄어들며, 실제 개발 환경에서는 CLI-Anything 하네스 가이드처럼 에이전트 친화적 인터페이스를 설계할 때 웹 데이터 입력 계층으로 자주 결합됩니다.

firecrawl/firecrawl 공식 GitHub 저장소 화면

광고

Firecrawl Local: DB·컨테이너 없이 내 PC에서 바로 돌리기

Firecrawl Local은 기존 풀 스택 셀프호스팅(Redis·PostgreSQL·Docker Compose 필요)의 무거움을 걷어내고 개발자 로컬 머신에서 단일 바이너리로 동작하도록 만든 경량 실행 모드입니다.

설치는 crates.io를 통해 진행하며 macOS(xcode-select --install)나 Debian/Ubuntu(build-essential)의 C 컴파일러와 Rust 툴체인이 필요합니다. 설치 후에는 별도 데몬이나 컨테이너를 띄우지 않아도 곧바로 단건 스크래핑, 사이트 크롤링, URL 맵 추출을 수행할 수 있습니다.

# 1. Firecrawl Local 설치 (Rust + C 컴파일러 필요)
cargo install firecrawl-local

# 2. 단일 페이지를 마크다운으로 출력
firecrawl-local scrape https://firecrawl.dev --markdown

# 3. 문서 사이트 50페이지 크롤링 후 로컬 폴더 저장
firecrawl-local crawl https://docs.firecrawl.dev --limit 50 --out ./pages

# 4. 로컬 v2 API 서버 실행 (http://localhost:3002)
firecrawl-local serve

자바스크립트 렌더링이 필요한 동적 페이지는 내 컴퓨터에 이미 설치된 Chrome 또는 Chromium을 자동으로 호출해 처리합니다. PDF와 오피스 문서 파싱도 로컬에서 바로 돌아가며, serve 명령으로 localhost:3002를 열어 두면 기존 Firecrawl Python/Node SDK 코드에서 api_url="http://localhost:3002"만 바꿔 API 키 없이 그대로 재사용할 수 있습니다.

로컬 개발 환경에서 웹 문서를 마크다운으로 변환해 확인하는 작업 모습

Firecrawl Local vs Firecrawl Cloud vs 셀프호스팅 비교

세 가지 실행 방식은 인프라 부담, 데이터 프라이버시, 고급 에이전트 기능 필요 여부에 따라 명확히 갈립니다.

구분 Firecrawl Local Firecrawl Cloud 전체 셀프호스팅 (apps/api)
설치·인프라 cargo install 단일 바이너리 (DB·큐 없음) 설치 불필요 (firecrawl.dev / Keyless) Docker Compose + Redis + PostgreSQL + 브라우저 서비스
Scrape / Crawl / Map 로컬 실행 (로컬 Chrome·PDF·오피스 지원) 클라우드 실행 (96% 웹 커버리지, P95 3.4s) 자체 인프라에서 실행
Search / Alexandria Cloud 경유 (Alexandria는 login 필요) 기본 제공 (550+ 데이터 프로바이더) Alexandria 미포함
Interact / Agent / Monitor 미지원 (Cloud 전용) 지원 (spark-2 등 자율 수집·브라우저 조작) 일부 구성 제한
초기 비용·무료 범위 로컬 무료 / Cloud 폴백 제한적 무가입 호출 Keyless 월 1,000 크레딧 무가입 무료 서버·프록시·유지비 본인 부담

여기서 눈에 띄는 안전장치는 클라우드 폴백 제어입니다. 로컬에서 열리지 않는 단일 페이지는 기본적으로 Firecrawl Cloud가 대신 가져와 결과에 "source": "firecrawl-cloud"를 표시하지만, 사내 문서나 민감한 내부망 URL을 다룰 때는 FIRECRAWL_CLOUD=off를 설정해 외부 전송을 원천 차단할 수 있습니다.

웹사이트·PDF 입력부터 Firecrawl Local 처리 및 Claude Code·Cursor MCP 연결까지의 구조도

Claude Code·Cursor에 MCP로 붙이는 실전 팁

firecrawl-local init은 현재 개발자 PC에 깔린 AI 코딩 도구를 자동으로 탐색해 로컬 MCP 서버 설정을 꽂아줍니다.

공식 README 기준으로 init 명령은 Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Codex를 지원하며, 기존 설정 파일을 덮어쓰기 전에 모든 설정 파일을 먼저 백업합니다. 단, MCP 서버 자체는 Node.js 22 이상이 필요하므로 실행 전 node -v 확인이 필수입니다. 만약 Rust 빌드 환경이 없다면 npx -y firecrawl-cli@latest init --all --browser로 Firecrawl Cloud 기반 CLI·MCP를 먼저 붙이고 Keyless 월 1,000 크레딧으로 테스트하는 편이 빠릅니다. 코드 계획과 변경점 검수 흐름까지 함께 다듬고 싶다면 Plannotator 브라우저 검수 가이드와 조합해 리서치→계획→리뷰 파이프라인을 묶기 좋습니다.

토리스의 판단

웹 문서를 AI 에이전트에게 읽히는 작업이라면, 이제 처음부터 무거운 Docker 스택이나 유료 API 키부터 준비할 필요가 없습니다.

  1. 사내 문서·개발 중 빠른 참조·비용 제로 우선: firecrawl-local을 설치하고 FIRECRAWL_CLOUD=off와 init으로 Claude Code/Cursor에 붙이세요. DB 관리 없이 공식 문서와 로컬 PDF를 깔끔한 마크다운으로 바로 넘길 수 있습니다.
  2. Rust 빌드가 번거롭거나 빠른 프로토타이핑: npx -y firecrawl-cli@latest와 Firecrawl Keyless(월 1,000 크레딧)로 먼저 파이프라인을 검증하세요.
  3. 봇 차단이 강한 대규모 상용 사이트·자율 탐색: 96% 커버리지와 Interact/Agent/Alexandria가 필요한 구간이므로 Firecrawl Cloud API 키를 붙이는 편이 운영 시간을 아껴줍니다.

단, 어떤 모드를 쓰든 대상 사이트의 robots.txt와 이용약관 준수는 사용자 책임이며, 메인 서버 코드는 AGPL-3.0(SDK는 MIT) 라이선스이므로 상용 서비스 내부에 서버 코드를 수정·재배포할 때는 라이선스 범위를 반드시 확인해야 합니다.

출처

광고

YOUTUBE · TORIS STUDIO

토리스 영상 더 보기