AI 에이전트에게 웹페이지를 읽히려면, 먼저 그 페이지를 기계가 소화하기 좋은 형태로 바꿔야 합니다. 브라우저 화면을 그대로 넘기면 토큰만 잡아먹고, HTML 원문을 넘기면 메뉴와 광고가 본문보다 많습니다. Firecrawl은 이 변환을 대신해 주는 도구이고, 그중 Firecrawl Local은 데이터베이스도 서버도 없이 내 컴퓨터에서 그 일을 끝내는 버전입니다.
Q. Firecrawl Local은 무엇인가요?
웹사이트·PDF·오피스 문서를 가져와 마크다운으로 정리하고, 그 결과를 AI 에이전트가 MCP로 바로 쓰게 해 주는 단일 실행 파일입니다. 작업 큐도 컨테이너도 없이 cargo install firecrawl-local 한 줄로 설치합니다.
Q. 무료인가요?
소스가 공개돼 있고(AGPL-3.0), 로컬에서 처리되는 수집에는 요금이 붙지 않습니다. 검색이나 막힌 페이지 처리처럼 클라우드가 필요한 기능만 Firecrawl Cloud로 넘어가며, 이때는 가입 없이 월 1,000크레딧까지 쓰는 Keyless 방식이 기본입니다.
Q. 내 PC 밖으로 데이터가 나가나요?
기본값은 ‘필요할 때만’입니다. 스크레이핑·크롤링·맵·문서 파싱은 전부 로컬에서 돌고, 로컬에서 열리지 않는 페이지만 클라우드가 대신 가져옵니다. 이 폴백은 FIRECRAWL_CLOUD=off로 끌 수 있습니다.
이 글은 2026년 11월 21일 기준으로 GitHub 저장소(firecrawl/firecrawl의 README와 apps/local 문서), crates.io 배포 정보, firecrawl.dev 공식 문서를 직접 열어 확인한 내용만 담았습니다. 직접 설치해 본 사용기가 아니라 공개 문서를 대조한 정리이므로, 명령과 기본값은 버전에 따라 달라질 수 있습니다.
한눈에 정리
- 정체: DB·큐·Docker 없이 도는 Rust 단일 바이너리. 내 PC에 설치된 크롬을 빌려 JavaScript 페이지까지 마크다운으로 바꿉니다.
- 설치:
cargo install firecrawl-local. Rust와 C 컴파일러가 필요하고, MCP까지 쓰려면 Node.js 22 이상이 필요합니다. - 명령:
scrape·crawl·map·serve(로컬 v2 API, 포트 3002)·init(MCP 자동 등록). - 현재 버전: crates.io 0.1.1(2026년 11월 19일 공개). 저장소는 별 20만 5천 개, 라이선스 AGPL-3.0.
- 주의할 점: 기본 설정이 클라우드 폴백과 사설망 접근을 허용합니다. 신뢰할 수 없는 페이지를 다룰 때는
--public-only와FIRECRAWL_CLOUD=off를 검토해야 합니다.
1. Firecrawl Local이 하는 일: 브라우저와 마크다운 사이의 변환기
Firecrawl은 스스로를 “에이전트를 더 똑똑하게 만드는 지식 인프라”라고 소개합니다. 같은 저장소에서 세 가지 방식이 나옵니다. 클라우드 서비스(firecrawl.dev), 큐·워커·DB까지 갖춘 셀프호스팅 서버(apps/api), 그리고 이 글에서 다루는 Firecrawl Local(apps/local)입니다.
Local의 핵심은 ‘빼는 것’입니다. 데이터베이스도, 작업 큐도, 컨테이너도 없습니다. 실행 파일 하나가 URL을 받아 페이지를 가져오고, Firecrawl API와 같은 정제 코드로 본문만 남겨 마크다운으로 돌려줍니다. JavaScript로 그려지는 페이지는 내 컴퓨터에 이미 설치된 크롬이나 크로미움을 빌려 렌더링하고, PDF와 오피스 문서도 로컬에서 파싱합니다. 브라우저가 없어도 정적 페이지는 처리되며, 그때는 ‘브라우저가 필요했다’는 경고가 결과에 붙습니다.

규모도 작지 않습니다. 2026년 11월 21일 확인 기준 저장소는 별 205,104개, 포크 10,748개, 열린 이슈 883개이고, 2024년 4월 15일에 만들어졌습니다. crates.io에 올라온 firecrawl-local은 2026년 11월 11일 첫 배포(0.1.0) 이후 11월 19일 0.1.1이 나왔고, 누적 다운로드는 3,346회입니다. 저장소 전체는 TypeScript지만 Local은 Rust로 빌드되는 별도 구성 요소입니다.
라이선스는 한 번 짚고 가야 합니다. 저장소는 AGPL-3.0이고 SDK는 MIT입니다. AGPL은 수정한 프로그램을 네트워크 서비스로 제공할 때 소스 공개 의무가 따라붙는 조건이라, Local을 사내 서비스로 감싸 제공할 계획이라면 이 조항을 먼저 확인해야 합니다.
2. 설치: cargo 한 줄, 준비물은 세 가지
설치는 crates.io에서 받습니다. 준비물은 Rust와 C 컴파일러, 그리고 선택 사항 두 가지입니다.
cargo install firecrawl-local
firecrawl-local --version
macOS는 xcode-select --install, Debian·Ubuntu는 build-essential을 먼저 설치합니다. 저장소를 클론해 직접 빌드하려면 cd firecrawl/apps/local에서 cargo build --release를 실행하고, 결과물은 target/release/firecrawl-local에 생깁니다.
| 준비물 | 없으면 | 확인 |
|---|---|---|
| Rust와 C 컴파일러 | 설치 자체가 불가능 | cargo --version |
| Chrome 또는 Chromium | 정적 페이지는 되지만 JS 페이지는 경고와 함께 실패 | 브라우저 설치 여부, --browser never로 강제 가능 |
| Node.js 22 이상 | MCP 연결 불가(CLI·로컬 API는 사용 가능) | node -v |
선택 사항은 기능을 넓힙니다. 크롬이 있으면 JS 렌더링과 스크린샷이 가능해지고, Node.js 22 이상이 있으면 MCP 서버인 firecrawl-mcp npm 패키지를 npx로 띄울 수 있습니다. 둘 다 없어도 정적 페이지 수집은 그대로 동작합니다.
3. 명령 세 개로 끝내는 수집: scrape·crawl·map
Local의 기본 명령은 세 가지입니다. 하나씩만 익히면 대부분의 수집 작업이 끝납니다.
firecrawl-local scrape https://firecrawl.dev --markdown
한 페이지를 가져와 마크다운만 출력합니다. --markdown을 빼면 Firecrawl API와 같은 JSON이 나오고, --format markdown,links처럼 형식을 고를 수 있습니다(선택지는 markdown, html, rawHtml, links). --full-page는 내비게이션과 푸터까지 남기고, --timeout은 페이지당 제한 시간을 밀리초로 정합니다.
firecrawl-local crawl https://docs.firecrawl.dev --limit 50 --out ./pages
시작 URL에서 링크를 따라가며 페이지마다 마크다운 파일 하나를 저장합니다. --limit의 기본값은 100페이지이고, --max-depth로 링크 깊이를, --include·--exclude로 경로 정규식을, --entire-domain으로 시작 경로 밖까지 따라갈지를 정합니다. 문서 사이트를 통째로 에이전트의 참고 자료로 만들 때 쓰는 명령입니다.
firecrawl-local map https://firecrawl.dev
사이트맵과 시작 페이지를 읽어 사이트의 URL 목록만 뽑습니다. --search로 특정 단어가 들어간 URL만 남기고, --limit으로 개수를 제한합니다. 크롤링 전에 범위를 가늠할 때 유용합니다.

명령별 역할을 표로 정리하면 아래와 같습니다. ‘실행 위치’는 README의 ‘What runs where’ 설명을 따른 것입니다.
| 명령 | 하는 일 | 실행 위치 |
|---|---|---|
scrape <urls...> |
URL을 가져와 마크다운·HTML·원본 HTML·링크로 변환 | 내 PC |
crawl <url> |
링크를 따라 여러 페이지 수집, --out으로 파일 저장 |
내 PC |
map <url> |
사이트맵과 시작 페이지에서 URL 목록 추출 | 내 PC |
serve |
Firecrawl v2 API를 localhost에 제공 | 내 PC |
mcp |
MCP 서버를 stdio로 실행 | 내 PC(일부 도구는 클라우드) |
init |
설치된 AI 도구에 MCP 서버 등록 | 내 PC |
search <query> |
웹 검색 | Firecrawl Cloud |
login |
브라우저로 Firecrawl 계정 로그인 | Firecrawl Cloud |
4. AI 에이전트에 붙이기: init이 만드는 MCP 설정, serve가 여는 로컬 API
Local을 설치만 하고 끝내면 CLI 도구 하나 늘린 셈입니다. 진짜 값어치는 에이전트에 붙일 때 나옵니다. firecrawl-local init은 컴퓨터에 설치된 AI 도구를 찾아 Firecrawl Local을 MCP 서버로 등록합니다. 대상은 Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Codex 여섯 가지입니다.
init은 설정 파일을 건드리기 전에 각 파일을 먼저 백업합니다. --dry-run을 붙이면 실제로 쓰지 않고 바뀔 내용만 보여주고, --agent cursor처럼 하나만 골라 설정할 수도 있습니다. 자동 등록 후에는 해당 도구를 재시작해야 새 서버를 읽습니다.
자동 등록을 원하지 않으면 직접 넣습니다. firecrawl-local mcp를 stdio MCP 서버로 등록하면 되고, JSON 설정은 아래처럼 생겼습니다.
{ "mcpServers": { "firecrawl": { "command": "/path/to/firecrawl-local", "args": ["mcp"] } } }
이렇게 붙이면 에이전트는 Firecrawl의 표준 MCP 도구를 받습니다. firecrawl-local mcp가 루프백 포트에 로컬 API를 띄우고 firecrawl-mcp 패키지를 그 API에 연결하는 구조라서, scrape·crawl·map·batch scrape는 내 PC에서 돌고 나머지 도구는 Firecrawl Cloud로 갑니다. 검색과 Alexandria는 그래서 MCP 연결에서도 클라우드를 거칩니다.
직접 만든 코드에서 쓰려면 serve가 편합니다. Firecrawl v2 API를 포트 3002에 열고, 로컬 라우트는 API 키가 필요 없습니다. 기존 Firecrawl SDK는 주소만 바꾸면 그대로 동작합니다.
from firecrawl import Firecrawl
app = Firecrawl(api_url="http://localhost:3002")
print(app.scrape("https://firecrawl.dev").markdown)
로컬에서 도는 라우트는 /v2/scrape, /v2/map, /v2/crawl과 그 상태·취소, /v2/batch/scrape와 그 상태·취소, /health입니다. /v2/search처럼 나머지 v2 라우트는 클라우드로 전달되고, v0·v1 라우트는 아예 제공하지 않습니다. 크롤·배치 작업은 메모리에 남기 때문에 serve를 끄면 사라지고, 시작한 지 한 시간이 지나면 만료됩니다.
5. 클라우드 폴백·보안·한계: 켜기 전에 알아야 할 기본값
Local은 ‘완전한 오프라인 도구’가 아니라 기본값이 클라우드 폴백을 허용하는 도구입니다. 스크레이핑·크롤링·맵·문서 파싱은 내 PC에서 끝나고 아무것도 보내지 않지만, 세 가지는 클라우드가 필요합니다. 검색(로컬에 색인이 없음), 내 PC에서 막힌 페이지(일반 요청과 로컬 브라우저가 모두 실패할 때), Alexandria 데이터 프로바이더(무료 계정 필요)입니다.
특히 한 페이지 스크레이프가 로컬에서 열리지 않으면 기본 설정에서 클라우드가 대신 가져오고, 결과에 "source": "firecrawl-cloud"가 표시됩니다. 이 호출은 계정 없이도 제한된 속도로 동작하고, firecrawl-local login을 하면 내 계정의 크레딧으로 넘어갑니다. 클라우드 호출에는 무작위 설치 ID와 호출한 도구 이름이 함께 전달됩니다.
FIRECRAWL_CLOUD 값 |
동작 |
|---|---|
auto(기본) |
검색·막힌 페이지 폴백·Alexandria 모두 클라우드 사용 |
search |
검색만 클라우드로 보냄 |
off |
클라우드로 아무것도 보내지 않음. 알 수 없는 값도 off로 처리 |
보안 기본값은 실행 방식에 따라 다릅니다. scrape·crawl·map·mcp는 키보드 앞의 사람을 위한 명령이라 localhost와 사설망에 접근할 수 있고, --public-only를 붙여야 이를 거부합니다. 반면 serve는 다른 프로그램의 요청을 받는 서버라서 127.0.0.1에만 열리고 사설 주소는 기본으로 거부합니다(--allow-private로 허용). --host로 다른 주소에 바인딩하려면 --token이 필수이고, 허용 Host 목록 검사도 함께 적용됩니다. 링크-로컬과 클라우드 메타데이터 주소는 리다이렉트와 DNS 해석을 거친 뒤에도 모든 모드에서 차단됩니다.
이 기본값이 중요한 이유는 에이전트의 취약점과 맞닿아 있기 때문입니다. 에이전트가 읽은 페이지에 숨은 지시가 있으면 내부 URL을 열도록 유도될 수 있습니다. 문서도 신뢰할 수 없는 사이트를 에이전트에게 읽힌다면 firecrawl-local mcp --public-only로 등록하라고 권합니다. 크롬은 헤드리스·샌드박스로, 일회용 프로필을 쓰고, Local 내부의 루프백 프록시가 리다이렉트·서브리소스·스크립트·웹소켓까지 모든 연결을 검사합니다. Local은 자신의 User-Agent로 신원을 밝히고 크롤링할 때 robots.txt를 읽습니다.

한계도 문서에 명시돼 있습니다. 로컬 스크레이프는 json·summary 형식을 경고와 함께 건너뛰고 브라우저 actions를 무시하며, 스크린샷에는 크롬이 필요합니다. 크롤·배치 작업은 메모리에 있어 serve가 멈추면 끝나고, v0·v1 라우트는 제공하지 않습니다. Docker로 JS 렌더링까지 하려면 크롬 샌드박스가 쓰는 user namespace를 막는 기본 seccomp 프로필을 바꿔야 하는데, 문서는 seccomp=unconfined 대신 Playwright가 공개한 프로필을 쓰라고 못 박습니다.
그래서 맞는 경우는 분명합니다. 사내 문서·위키·블로그처럼 내가 통제하는 사이트를 에이전트의 참고 자료로 만들 때, 페이지 원문을 밖으로 보내지 않고 마크다운으로 쌓고 싶을 때, 클라우드 API 요금 없이 배치 작업을 돌리고 싶을 때입니다. 반대로 맞지 않는 경우도 있습니다. 구조화 JSON 추출, Interact, Agent, Monitor는 클라우드 전용이라 Local만으로는 대체되지 않습니다. 여러 대의 서버에서 대규모로 돌려야 한다면 셀프호스팅 서버나 클라우드가 맞습니다. 클라우드는 웹 커버리지 96%와 P95 3.4초 레이턴시(공식 README 수치)를 내세우는데, 이 영역은 로컬 도구가 애초에 겨냥하지 않습니다.
자주 묻는 질문
Q. 정말 무료인가요?
로컬에서 처리되는 수집에는 요금이 없고, 소스는 AGPL-3.0으로 공개돼 있습니다. 클라우드가 필요한 기능(검색, 막힌 페이지, Alexandria)은 가입 없이 월 1,000크레딧까지 쓰는 Keyless가 기본이고, 계정을 연결하면 크레딧이 내 계정으로 잡힙니다. Alexandria는 550개 이상 데이터 프로바이더(2억 5천만 명 인물, 7,500만 개 기업, 4,100만 편 논문 등)를 한 API로 쓰는 크레딧 기반 라이브러리입니다.
Q. 인터넷 없이 완전 오프라인으로 쓸 수 있나요?
FIRECRAWL_CLOUD=off로 클라우드 폴백을 끄면 로컬에서 처리 가능한 페이지만 다룹니다. 이 상태에서는 검색과 Alexandria가 동작하지 않고, 막힌 페이지는 "blocked": true와 함께 실패합니다.
Q. 어떤 AI 도구에서 쓸 수 있나요?
init이 Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Codex를 자동으로 찾아 등록합니다. 그 밖의 도구는 firecrawl-local mcp를 stdio MCP 서버로 직접 등록하면 됩니다. MCP 서버를 돌리려면 Node.js 22 이상이 필요합니다.
Q. JSON으로 구조화 추출도 되나요?
로컬 스크레이프는 json·summary 형식을 건너뜁니다. 구조화 추출이 필요하면 클라우드 API를 써야 합니다. Local의 출력은 마크다운·HTML·원본 HTML·링크까지가 범위입니다.
출처
- github.com/firecrawl/firecrawl — README의 Local·Cloud 소개, ‘What runs where’ 표 (2026년 11월 21일 확인)
- apps/local README — 설치, 명령 레퍼런스, 보안 기본값, 설정 변수, 한계
- crates.io firecrawl-local — 0.1.1(2026년 11월 19일 배포), 누적 3,346회 다운로드, AGPL-3.0
- firecrawl.dev — 클라우드 서비스 소개, Keyless 월 1,000크레딧, Alexandria·Interact·Agent·Monitor
- GitHub REST API 저장소 메타데이터 — 별 205,104개, 포크 10,748개, AGPL-3.0, 최신 릴리스 v2.11.0(2026년 6월 19일) (2026년 11월 21일 조회)
