Firecrawl 자동화
Claude Code에서 직접 Firecrawl 웹 크롤링 및 추출을 실행하세요. 개별 페이지 스크래핑, 전체 사이트 크롤링, AI를 사용한 구조화된 데이터 추출, URL 목록 일괄 처리, 웹사이트 구조 맵핑을 터미널을 떠나지 않고 수행할 수 있습니다.
툴킷 문서: composio.dev/toolkits/firecrawl
설정
- Composio MCP 서버를 설정에 추가하세요:
https://rube.app/mcp - 프롬프트가 표시되면 Firecrawl 계정을 연결하세요. 에이전트가 인증 링크를 제공합니다.
- 크레딧 소비에 주의하세요 — 크롤링 범위를 좁게 설정하고, 확장하기 전에 작은 URL 집합으로 먼저 테스트하세요.
핵심 워크플로우
1. 단일 페이지 스크래핑
동적 페이지를 위한 선택적 브라우저 액션과 함께 여러 형식으로 URL의 콘텐츠를 가져옵니다.
도구: FIRECRAWL_SCRAPE
주요 매개변수:
url(필수) — 스크래핑할 완전한 URLformats— 출력 형식:markdown(기본값),html,rawHtml,links,screenshot,jsononlyMainContent(기본값 true) — 네비게이션/푸터/광고를 제외한 주요 콘텐츠만 추출waitFor— JS 렌더링을 기다리는 밀리초 (기본값 0)timeout— 최대 대기 시간 (ms) (기본값 30000)actions— 스크래핑 전 브라우저 액션 (클릭, 쓰기, 대기, 키 누르기, 스크롤)includeTags/excludeTags— HTML 태그로 필터링jsonOptions—schema및/또는prompt를 사용한 구조화된 추출용
프롬프트 예시: "https://example.com/pricing 의 주요 콘텐츠를 마크다운으로 스크래핑해줘"
2. 전체 사이트 크롤링
구성 가능한 깊이, 경로 필터 및 동시성을 사용하여 웹사이트의 여러 페이지를 찾아 스크래핑합니다.
도구: FIRECRAWL_CRAWL_V2
주요 매개변수:
url(필수) — 크롤링 시작 URLlimit(기본값 10) — 크롤링할 최대 페이지 수maxDiscoveryDepth— 루트 페이지로부터의 깊이 제한includePaths/excludePaths— URL 경로에 대한 정규식 패턴allowSubdomains— 서브도메인 포함 (기본값 false)crawlEntireDomain— 하위 링크뿐만 아니라 형제/상위 링크도 따라가기 (기본값 false)sitemap—include(기본값),skip, 또는onlyprompt— 크롤러 설정을 자동 구성하는 자연어scrapeOptions_formats— 각 페이지의 출력 형식scrapeOptions_onlyMainContent— 페이지별 주요 콘텐츠 추출
프롬프트 예시: "docs.example.com 사이트의 문서 섹션을 크롤링해줘, 최대 50페이지, 경로가 docs와 일치하는 것만"
3. 구조화된 데이터 추출
AI와 자연어 프롬프트 또는 JSON 스키마를 사용하여 웹 페이지에서 구조화된 JSON 데이터를 추출합니다.
도구: FIRECRAWL_EXTRACT
주요 매개변수:
urls(필수) — 추출할 URL 배열 (베타에서는 최대 10개).https://example.com/blog/*와 같은 와일드카드 지원prompt— 추출할 내용에 대한 자연어 설명schema— 원하는 출력 구조를 정의하는 JSON 스키마enable_web_search— 초기 도메인 외부의 링크를 크롤링하도록 허용 (기본값 false)
prompt 또는 schema 중 하나 이상은 반드시 제공되어야 합니다.
반환된 작업 id를 사용하여 FIRECRAWL_EXTRACT_GET으로 추출 상태를 확인하세요.
프롬프트 예시: "https://example.com/pricing 에서 회사 이름, 가격 티어, 기능 목록을 추출해줘"
4. 여러 URL 일괄 스크래핑
효율적인 대량 데이터 수집을 위해 공유 설정으로 여러 URL을 동시에 스크래핑합니다.
도구: FIRECRAWL_BATCH_SCRAPE
주요 매개변수:
urls(필수) — 스크래핑할 URL 배열formats— 모든 페이지의 출력 형식 (기본값markdown)onlyMainContent(기본값 true) — 주요 콘텐츠 추출maxConcurrency— 병렬 스크래핑 제한ignoreInvalidURLs(기본값 true) — 배치 실패 대신 잘못된 URL 건너뛰기location—country코드를 사용한 지리적 위치 설정actions— 각 페이지에 적용되는 브라우저 액션blockAds(기본값 true) — 광고 차단
프롬프트 예시: "이 20개 제품 페이지 URL을 광고 차단과 함께 마크다운으로 일괄 스크래핑해줘"
5. 웹사이트 구조 맵핑
시작 URL에서 웹사이트의 모든 URL을 찾아냅니다. 크롤링 계획 또는 사이트 구조 감사에 유용합니다.
도구: FIRECRAWL_MAP_MULTIPLE_URLS_BASED_ON_OPTIONS
주요 매개변수:
url(필수) — 시작 URL (https://또는http://여야 함)search— 특정 페이지 유형으로 URL 검색을 안내limit(기본값 5000, 최대 100000) — 반환할 최대 URL 수includeSubdomains(기본값 true) — 서브도메인 포함ignoreQueryParameters(기본값 true) — 쿼리 매개변수만 다른 URL 중복 제거sitemap—include,skip, 또는only
프롬프트 예시: "docs.example.com 의 모든 URL을 맵핑해줘, API 참조 페이지에 초점을 맞춰서"
6. 크롤링 작업 모니터링 및 관리
크롤링 진행 상황 추적, 결과 검색, 실행 중인 작업 취소.
도구: FIRECRAWL_CRAWL_GET, FIRECRAWL_GET_THE_STATUS_OF_A_CRAWL_JOB, FIRECRAWL_CANCEL_A_CRAWL_JOB
FIRECRAWL_CRawl_GET— 상태, 진행률, 사용된 크레딧 및 크롤링된 페이지 데이터 가져오기FIRECRAWL_CANCEL_A_CRAWL_JOB— 활성 또는 대기 중인 크롤링 중지
두 도구 모두 크롤링이 시작될 때 반환된 크롤링 작업 id (UUID)가 필요합니다.
프롬프트 예시: "크롤링 작업 019b0806-b7a1-7652-94c1-e865b5d2e89a의 상태를 확인해줘"
알려진 문제점
- 속도 제한: Firecrawl은 "Rate limit exceeded" 오류(429)를 유발할 수 있습니다. 여러 개별
FIRECRAWL_SCRAPE호출보다FIRECRAWL_BATCH_SCRAPE을 선호하고, 429/5xx 응답 시 백오프를 구현하세요. - 크레딧 소비:
FIRECRAWL_EXTRACT은 "Insufficient credits" 오류로 실패할 수 있습니다. 범위를 좁게 설정하고 희소 필드를 생성하는 광범위한 홈페이지 URL을 피하세요. 먼저 작은 URL 집합으로 테스트하세요. - 중첩된 오류 응답: 외부 API 호출이 성공하더라도 페이지별 실패는
response.data.code(예:SCRAPE_DNS_RESOLUTION_ERROR)에 중첩될 수 있습니다. 항상 내부 상태/오류 필드를 검증하세요. - JS가 많은 페이지: 렌더링되지 않은 가져오기는 중요한 콘텐츠를 놓칠 수 있습니다. 동적 페이지의 경우
waitFor(예: 1000-5000ms)를 사용하거나, 스크래핑 전에 페이지와 상호 작용하도록scrapeOptions_actions를 구성하세요. - 추출 스키마 정밀도: 모호하거나 변경되는 스키마/프롬프트는 노이즈가 많고 일관성 없는 출력을 생성합니다. 스키마를 고정하고 많은 URL로 확장하기 전에 작은 샘플로 테스트하세요.
- 크롤링 작업은 비동기입니다:
FIRECRAWL_CRAWL_V2는 작업 ID와 함께 즉시 반환됩니다.FIRECRAWL_CRAWL_GET을 사용하여 결과를 폴링하세요. 크레딧 낭비를 방지하려면FIRECRAWL_CANCEL_A_CRAWL_JOB으로 중단된 크롤링을 취소하세요. - 추출 작업 폴링:
FIRECRAWL_EXTRACT도 대규모 작업의 경우 비동기입니다.FIRECRAWL_EXTRACT_GET으로 최종 출력을 검색하세요. - 추출을 위한 URL 배칭: 429 속도 제한 오류를 피하기 위해 추출 URL 배치를 작게 유지하세요(~10개 URL).
- 깊게 중첩된 응답: 결과는 종종
data.data이하에 중첩됩니다. 평평한 키를 가정하지 말고 반환된 구조를 검사하세요.
빠른 참조
| 도구 슬러그 | 설명 |
|---|---|
FIRECRAWL_SCRAPE | 형식/액션 옵션으로 단일 URL 스크래핑 |
FIRECRAWL_CRAWL_V2 | 깊이/경로 제어로 웹사이트 크롤링 |
FIRECRAWL_EXTRACT | AI 프롬프트/스키마로 구조화된 데이터 추출 |
FIRECRAWL_BATCH_SCRAPE | 여러 URL을 동시에 일괄 스크래핑 |
FIRECRAWL_MAP_MULTIPLE_URLS_BASED_ON_OPTIONS | 사이트의 모든 URL 검색/맵핑 |
FIRECRAWL_CRAWL_GET | 크롤링 작업 상태 및 결과 가져오기 |
FIRECRAWL_GET_THE_STATUS_OF_A_CRAWL_JOB | 크롤링 작업 진행 상황 확인 |
FIRECRAWL_CANCEL_A_CRAWL_JOB | 활성 크롤링 작업 취소 |
FIRECRAWL_EXTRACT_GET | 추출 작업 상태 및 결과 가져오기 |
FIRECRAWL_CRAWL_PARAMS_PREVIEW | 시작 전 크롤링 매개변수 미리보기 |
FIRECRAWL_SEARCH | 웹 검색 + 상위 결과 스크래핑 |
Composio 제공