Firecrawl MCP 서버
웹 스크래핑 기능을 위해 Firecrawl 과 통합되는 MCP(Model Context Protocol) 서버 구현입니다.
초기 구현에 도움을 준 @vrknetha 와 @cawstudios 에게 큰 감사를 표합니다!
특징
스크래핑, 크롤링, 검색, 추출, 심층 조사 및 일괄 스크래핑 지원
JS 렌더링을 통한 웹 스크래핑
URL 검색 및 크롤링
콘텐츠 추출을 통한 웹 검색
지수 백오프를 통한 자동 재시도
내장된 속도 제한을 통한 효율적인 일괄 처리
클라우드 API에 대한 크레딧 사용 모니터링
종합 로깅 시스템
클라우드 및 자체 호스팅 FireCrawl 인스턴스 지원
모바일/데스크톱 뷰포트 지원
태그 포함/제외를 통한 스마트 콘텐츠 필터링
Related MCP server: OneSearch MCP Server
설치
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 retriesClaude 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
}
}6. 추출 도구( firecrawl_extract )
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 라이센스 - 자세한 내용은 라이센스 파일을 참조하세요.