Firecrawl MCP 서버
웹 스크래핑 기능을 위해 Firecrawl 과 통합되는 MCP(Model Context Protocol) 서버 구현입니다.
초기 구현에 도움을 준 @vrknetha 와 @cawstudios 에게 큰 감사를 표합니다!
특징
스크래핑, 크롤링, 검색, 추출, 심층 조사 및 일괄 스크래핑 지원
JS 렌더링을 통한 웹 스크래핑
URL 검색 및 크롤링
콘텐츠 추출을 통한 웹 검색
지수 백오프를 통한 자동 재시도
내장된 속도 제한을 통한 효율적인 일괄 처리
클라우드 API에 대한 크레딧 사용 모니터링
종합 로깅 시스템
클라우드 및 자체 호스팅 Firecrawl 인스턴스 지원
모바일/데스크톱 뷰포트 지원
태그 포함/제외를 통한 스마트 콘텐츠 필터링
SSE 지원
Related MCP server: WebSearch
설치
npx로 실행
지엑스피1
수동 설치
npm install -g firecrawl-mcp커서에서 실행
커서 구성 🖥️ 참고: 커서 버전 0.45.6+ 필요 최신 구성 지침은 MCP 서버 구성에 대한 공식 커서 설명서 인 커서 MCP 서버 구성 가이드 를 참조하세요.
Cursor v0.45.6 에서 Firecrawl MCP를 구성하려면
커서 설정 열기
기능 > MCP 서버로 이동하세요
"+ 새 MCP 서버 추가"를 클릭하세요
다음을 입력하세요.
이름: "firecrawl-mcp"(또는 원하는 이름)
유형: "명령"
명령어:
env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp
Cursor v0.48.6 에서 Firecrawl MCP를 구성하려면
커서 설정 열기
기능 > MCP 서버로 이동하세요
"+ 새로운 글로벌 MCP 서버 추가"를 클릭하세요.
다음 코드를 입력하세요:
{ "mcpServers": { "firecrawl-mcp": { "command": "npx", "args": ["-y", "firecrawl-mcp"], "env": { "FIRECRAWL_API_KEY": "YOUR-API-KEY" } } } }
Windows를 사용 중이고 문제가 발생하는 경우
cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"시도해 보세요.
your-api-key Firecrawl API 키로 바꾸세요. 아직 Firecrawl API 키가 없다면 https://www.firecrawl.dev/app/api-keys 에서 계정을 생성하고 발급받으세요.
추가 후 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"
}
}
}
}SSE 로컬 모드로 실행
기본 stdio 전송 대신 로컬로 SSE(Server-Sent Events)를 사용하여 서버를 실행하려면 다음을 수행합니다.
env SSE_LOCAL=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcpURL을 사용하세요: http://localhost:3000/sse
Smithery(레거시)를 통해 설치
Smithery를 통해 Claude Desktop용 Firecrawl을 자동으로 설치하려면:
npx -y @smithery/cli install @mendableai/mcp-server-firecrawl --client claudeVS 코드에서 실행
한 번의 클릭으로 설치하려면 아래의 설치 버튼 중 하나를 클릭하세요...
수동 설치의 경우, VS Code의 사용자 설정(JSON) 파일에 다음 JSON 블록을 추가하세요. Ctrl + Shift + P 를 누르고 Preferences: Open User Settings (JSON) 입력하면 됩니다.
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "apiKey",
"description": "Firecrawl API Key",
"password": true
}
],
"servers": {
"firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_KEY": "${input:apiKey}"
}
}
}
}
}원하는 경우, 작업 공간의 .vscode/mcp.json 파일에 추가할 수 있습니다. 이렇게 하면 다른 사용자와 구성을 공유할 수 있습니다.
{
"inputs": [
{
"type": "promptString",
"id": "apiKey",
"description": "Firecrawl API Key",
"password": true
}
],
"servers": {
"firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_KEY": "${input:apiKey}"
}
}
}
}구성
환경 변수
클라우드 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 서비스를 사용합니다.
7. 심층 조사 도구(firecrawl_deep_research)
지능형 크롤링, 검색 및 LLM 분석을 사용하여 쿼리에 대한 심층적 웹 조사를 수행합니다.
{
"name": "firecrawl_deep_research",
"arguments": {
"query": "how does carbon capture technology work?",
"maxDepth": 3,
"timeLimit": 120,
"maxUrls": 50
}
}인수:
쿼리(문자열, 필수): 탐구하려는 연구 질문이나 주제입니다.
maxDepth(숫자, 선택 사항): 크롤링/검색을 위한 최대 재귀적 깊이(기본값: 3).
timeLimit(숫자, 선택 사항): 연구 세션에 대한 시간 제한(초)(기본값: 120).
maxUrls(숫자, 선택 사항): 분석할 URL의 최대 개수(기본값: 50).
보고:
LLM에서 연구를 기반으로 생성된 최종 분석(data.finalAnalysis)
연구 과정에서 사용되는 체계적인 활동과 출처도 포함될 수 있습니다.
8. LLMs.txt 생성 도구(firecrawl_generate_llmstxt)
주어진 도메인에 대해 표준화된 llms.txt(및 선택적으로 llms-full.txt) 파일을 생성합니다. 이 파일은 대규모 언어 모델이 사이트와 상호 작용하는 방식을 정의합니다.
{
"name": "firecrawl_generate_llmstxt",
"arguments": {
"url": "https://example.com",
"maxUrls": 20,
"showFullText": true
}
}인수:
url(문자열, 필수): 분석할 웹사이트의 기본 URL입니다.
maxUrls(숫자, 선택 사항): 포함할 URL의 최대 개수(기본값: 10).
showFullText(부울, 선택 사항): 응답에 llms-full.txt 내용을 포함할지 여부입니다.
보고:
생성된 llms.txt 파일 내용 및 선택적으로 llms-full.txt(data.llmstxt 및/또는 data.llmsfulltxt)
로깅 시스템
서버에는 포괄적인 로깅이 포함되어 있습니다.
운영 현황 및 진행 상황
성과 지표
신용 사용 모니터링
요금 제한 추적
오류 조건
로그 메시지 예:
[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풀 리퀘스트 제출
기여자분들께 감사드립니다
초기 구현에 도움을 준 @vrknetha , @cawstudios 에게 감사드립니다!
호스팅을 해주신 MCP.so와 Klavis AI, 그리고 서버를 통합해주신 @gstarwd , @xiangkaiz , @zihaolin96 에게 감사드립니다.
특허
MIT 라이센스 - 자세한 내용은 라이센스 파일을 참조하세요.