Firecrawl MCP 서버
웹 스크래핑 기능을 위해 Firecrawl 과 통합되는 MCP(Model Context Protocol) 서버 구현입니다.
초기 구현에 도움을 준 @vrknetha 와 @cawstudios 에게 큰 감사를 표합니다!
특징
- 스크래핑, 크롤링, 검색, 추출, 심층 조사 및 일괄 스크래핑 지원
- JS 렌더링을 통한 웹 스크래핑
- URL 검색 및 크롤링
- 콘텐츠 추출을 통한 웹 검색
- 지수 백오프를 통한 자동 재시도
- 클라우드 API에 대한 크레딧 사용 모니터링
- 종합 로깅 시스템
- 클라우드 및 자체 호스팅 FireCrawl 인스턴스 지원
- 모바일/데스크톱 뷰포트 지원
- 태그 포함/제외를 통한 스마트 콘텐츠 필터링
설치
npx로 실행
지엑스피1
수동 설치
npm install -g firecrawl-mcp
커서에서 실행
커서 구성 🖥️ 참고: 커서 버전 0.45.6+ 필요
Cursor에서 FireCrawl MCP를 구성하려면:
- 커서 설정 열기
- 기능 > MCP 서버로 이동하세요
- "+ 새 MCP 서버 추가"를 클릭하세요
- 다음을 입력하세요.
- 이름: "firecrawl-mcp"(또는 원하는 이름)
- 유형: "명령"
- 명령어:
env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp
Windows를 사용 중이고 문제가 발생하는 경우 cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp" 시도해 보세요.
your-api-key FireCrawl API 키로 바꾸세요.
추가 후 MCP 서버 목록을 새로 고쳐 새 도구를 확인하세요. Composer Agent는 필요한 경우 FireCrawl MCP를 자동으로 사용하지만, 웹 스크래핑 요구 사항을 명시하여 명시적으로 요청할 수 있습니다. Command+L(Mac)을 눌러 Composer에 접속하고, 제출 버튼 옆의 "에이전트"를 선택한 후 쿼리를 입력하세요.
윈드서프에서 달리기
./codeium/windsurf/model_config.json 에 다음을 추가하세요.
{
"mcpServers": {
"mcp-server-firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
Smithery(레거시)를 통해 설치
Smithery를 통해 Claude Desktop용 FireCrawl을 자동으로 설치하는 방법:
npx -y @smithery/cli install @mendableai/mcp-server-firecrawl --client claude
구성
환경 변수
클라우드 API에 필요함
FIRECRAWL_API_KEY : FireCrawl API 키- 클라우드 API 사용 시 필수 (기본값)
FIRECRAWL_API_URL 사용하여 자체 호스팅 인스턴스를 사용하는 경우 선택 사항
FIRECRAWL_API_URL (선택 사항): 자체 호스팅 인스턴스에 대한 사용자 지정 API 엔드포인트- 예:
https://firecrawl.your-domain.com - 제공되지 않으면 클라우드 API가 사용됩니다(API 키 필요)
선택적 구성
구성 재시도
FIRECRAWL_RETRY_MAX_ATTEMPTS : 재시도 최대 횟수(기본값: 3)FIRECRAWL_RETRY_INITIAL_DELAY : 첫 번째 재시도 전 초기 지연 시간(밀리초)(기본값: 1000)FIRECRAWL_RETRY_MAX_DELAY : 재시도 간 최대 지연 시간(밀리초)(기본값: 10000)FIRECRAWL_RETRY_BACKOFF_FACTOR : 지수 백오프 배수(기본값: 2)
신용 사용 모니터링
FIRECRAWL_CREDIT_WARNING_THRESHOLD : 신용 사용 경고 임계값(기본값: 1000)FIRECRAWL_CREDIT_CRITICAL_THRESHOLD : 신용 사용 위험 임계값(기본값: 100)
구성 예제
사용자 정의 재시도 및 신용 모니터링을 통한 클라우드 API 사용의 경우:
# Required for cloud API
export FIRECRAWL_API_KEY=your-api-key
# Optional retry configuration
export FIRECRAWL_RETRY_MAX_ATTEMPTS=5 # Increase max retry attempts
export FIRECRAWL_RETRY_INITIAL_DELAY=2000 # Start with 2s delay
export FIRECRAWL_RETRY_MAX_DELAY=30000 # Maximum 30s delay
export FIRECRAWL_RETRY_BACKOFF_FACTOR=3 # More aggressive backoff
# Optional credit monitoring
export FIRECRAWL_CREDIT_WARNING_THRESHOLD=2000 # Warning at 2000 credits
export FIRECRAWL_CREDIT_CRITICAL_THRESHOLD=500 # Critical at 500 credits
자체 호스팅 인스턴스의 경우:
# Required for self-hosted
export FIRECRAWL_API_URL=https://firecrawl.your-domain.com
# Optional authentication for self-hosted
export FIRECRAWL_API_KEY=your-api-key # If your instance requires auth
# Custom retry configuration
export FIRECRAWL_RETRY_MAX_ATTEMPTS=10
export FIRECRAWL_RETRY_INITIAL_DELAY=500 # Start with faster retries
Claude Desktop과 함께 사용
claude_desktop_config.json 에 다음을 추가하세요:
{
"mcpServers": {
"mcp-server-firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE",
"FIRECRAWL_RETRY_MAX_ATTEMPTS": "5",
"FIRECRAWL_RETRY_INITIAL_DELAY": "2000",
"FIRECRAWL_RETRY_MAX_DELAY": "30000",
"FIRECRAWL_RETRY_BACKOFF_FACTOR": "3",
"FIRECRAWL_CREDIT_WARNING_THRESHOLD": "2000",
"FIRECRAWL_CREDIT_CRITICAL_THRESHOLD": "500"
}
}
}
}
시스템 구성
서버에는 환경 변수를 통해 설정할 수 있는 여러 구성 가능한 매개변수가 포함되어 있습니다. 구성하지 않을 경우 기본값은 다음과 같습니다.
const CONFIG = {
retry: {
maxAttempts: 3, // Number of retry attempts for rate-limited requests
initialDelay: 1000, // Initial delay before first retry (in milliseconds)
maxDelay: 10000, // Maximum delay between retries (in milliseconds)
backoffFactor: 2, // Multiplier for exponential backoff
},
credit: {
warningThreshold: 1000, // Warn when credit usage reaches this level
criticalThreshold: 100, // Critical alert when credit usage reaches this level
},
};
이러한 구성은 다음을 제어합니다.
- 재시도 동작
- 속도 제한으로 인해 실패한 요청을 자동으로 다시 시도합니다.
- API 과부하를 방지하기 위해 지수 백오프를 사용합니다.
- 예: 기본 설정을 사용하면 재시도는 다음에서 시도됩니다.
- 1차 재시도: 1초 지연
- 2차 재시도: 2초 지연
- 3번째 재시도: 4초 지연(maxDelay로 제한)
- 신용 사용 모니터링
- 클라우드 API 사용에 대한 API 크레딧 소비를 추적합니다.
- 지정된 임계값에서 경고를 제공합니다.
- 예상치 못한 서비스 중단을 방지하는 데 도움이 됩니다.
- 예: 기본 설정:
- 1000 크레딧이 남았을 때 경고
- 100 크레딧이 남았을 때 중요 경고가 발생합니다.
속도 제한 및 일괄 처리
서버는 FireCrawl의 내장된 속도 제한 및 일괄 처리 기능을 활용합니다.
- 지수 백오프를 통한 자동 비율 제한 처리
- 배치 작업을 위한 효율적인 병렬 처리
- 스마트 요청 대기열 및 제한
- 일시적인 오류에 대한 자동 재시도
사용 가능한 도구
1. 스크레이프 도구( firecrawl_scrape )
고급 옵션을 사용하여 단일 URL에서 콘텐츠를 스크래핑합니다.
{
"name": "firecrawl_scrape",
"arguments": {
"url": "https://example.com",
"formats": ["markdown"],
"onlyMainContent": true,
"waitFor": 1000,
"timeout": 30000,
"mobile": false,
"includeTags": ["article", "main"],
"excludeTags": ["nav", "footer"],
"skipTlsVerification": false
}
}
2. 일괄 스크래핑 도구( firecrawl_batch_scrape )
내장된 속도 제한 및 병렬 처리를 통해 여러 URL을 효율적으로 스크래핑합니다.
{
"name": "firecrawl_batch_scrape",
"arguments": {
"urls": ["https://example1.com", "https://example2.com"],
"options": {
"formats": ["markdown"],
"onlyMainContent": true
}
}
}
응답에는 상태 확인을 위한 작업 ID가 포함됩니다.
{
"content": [
{
"type": "text",
"text": "Batch operation queued with ID: batch_1. Use firecrawl_check_batch_status to check progress."
}
],
"isError": false
}
3. 배치 상태 확인( firecrawl_check_batch_status )
일괄 작업의 상태를 확인합니다.
{
"name": "firecrawl_check_batch_status",
"arguments": {
"id": "batch_1"
}
}
4. 검색 도구( firecrawl_search )
웹을 검색하고 원하는 경우 검색 결과에서 콘텐츠를 추출합니다.
{
"name": "firecrawl_search",
"arguments": {
"query": "your search query",
"limit": 5,
"lang": "en",
"country": "us",
"scrapeOptions": {
"formats": ["markdown"],
"onlyMainContent": true
}
}
}
5. 크롤 도구( firecrawl_crawl )
고급 옵션을 사용하여 비동기 크롤링을 시작합니다.
{
"name": "firecrawl_crawl",
"arguments": {
"url": "https://example.com",
"maxDepth": 2,
"limit": 100,
"allowExternalLinks": false,
"deduplicateSimilarURLs": true
}
}
LLM 기능을 사용하여 웹 페이지에서 구조화된 정보를 추출합니다. 클라우드 AI와 셀프 호스팅 LLM 추출을 모두 지원합니다.
{
"name": "firecrawl_extract",
"arguments": {
"urls": ["https://example.com/page1", "https://example.com/page2"],
"prompt": "Extract product information including name, price, and description",
"systemPrompt": "You are a helpful assistant that extracts product information",
"schema": {
"type": "object",
"properties": {
"name": { "type": "string" },
"price": { "type": "number" },
"description": { "type": "string" }
},
"required": ["name", "price"]
},
"allowExternalLinks": false,
"enableWebSearch": false,
"includeSubdomains": false
}
}
응답 예시:
{
"content": [
{
"type": "text",
"text": {
"name": "Example Product",
"price": 99.99,
"description": "This is an example product description"
}
}
],
"isError": false
}
추출 도구 옵션:
urls : 정보를 추출할 URL 배열prompt : LLM 추출을 위한 사용자 정의 프롬프트systemPrompt : LLM을 안내하는 시스템 프롬프트schema : 구조화된 데이터 추출을 위한 JSON 스키마allowExternalLinks : 외부 링크에서 추출 허용enableWebSearch : 추가 컨텍스트를 위한 웹 검색 활성화includeSubdomains : 추출에 하위 도메인을 포함합니다.
자체 호스팅 인스턴스를 사용하는 경우, 추출은 구성된 LLM을 사용합니다. 클라우드 API의 경우, FireCrawl의 관리형 LLM 서비스를 사용합니다.
로깅 시스템
서버에는 포괄적인 로깅이 포함되어 있습니다.
- 운영 현황 및 진행 상황
- 성과 지표
- 신용 사용 모니터링
- 요금 제한 추적
- 오류 조건
로그 메시지 예:
[INFO] FireCrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[INFO] Batch operation queued with ID: batch_1
[WARNING] Credit usage has reached warning threshold
[ERROR] Rate limit exceeded, retrying in 2s...
오류 처리
서버는 강력한 오류 처리 기능을 제공합니다.
- 일시적인 오류에 대한 자동 재시도
- 백오프를 통한 속도 제한 처리
- 자세한 오류 메시지
- 신용 사용 경고
- 네트워크 복원력
오류 응답 예:
{
"content": [
{
"type": "text",
"text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
}
],
"isError": true
}
개발
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
기여하다
- 저장소를 포크하세요
- 기능 브랜치를 생성하세요
- 테스트 실행:
npm test - 풀 리퀘스트 제출
특허
MIT 라이센스 - 자세한 내용은 라이센스 파일을 참조하세요.