firecrawl-mcp-server

Firecrawl MCP Server
AI 에이전트를 위한 컨텍스트 API인 Firecrawl을 MCP 호환 클라이언트에서 사용할 수 있게 해주는 Model Context Protocol(MCP) 서버입니다. 실시간 웹을 검색하고, 스크레이핑하고, 상호작용하며 깔끔한 Markdown 또는 구조화된 데이터를 받아올 수 있습니다.

초기 구현을 해주신 @vrknetha, @knacklabs께 큰 감사를 드립니다!

기능

웹 검색, 선택적으로 각 결과의 전체 페이지 콘텐츠 포함
개발자 소스(GitHub 이슈, 병합된 풀 리퀘스트, README, 문서), 미국 정부 소스, 과학 논문(PubMed, bioRxiv, medRxiv, arXiv)을 위한 검색 인덱스
모든 URL을 깔끔한 Markdown 또는 구조화된 JSON으로 스크레이핑
PDF 및 문서 파싱
여러 페이지의 콘텐츠를 위해 사이트 크롤링, 또는 URL을 발견하기 위한 사이트 매핑
실제 브라우저에서 페이지와 상호작용: 클릭, 입력, 양식 작성, 동적 페이지 탐색
구조화된 데이터를 반환하는 다중 소스 리서치를 위한 Agent 작업 실행
페이지를 모니터링하고 콘텐츠가 변경되면 알림 받기
현재 및 과거 Firecrawl 크레딧 사용량 확인
자동 재시도 및 속도 제한
클라우드 및 자체 호스팅 지원
SSE 지원

MCP.so의 플레이그라운드 또는 Klavis AI에서 MCP Server를 사용해 보세요.

이 서버를 사용해야 할 때

알려진 URL이 있고 그 콘텐츠를 markdown 또는 직접 제공한 스키마에 맞는 JSON으로 받고 싶을 때는 firecrawl_scrape를 사용하세요.
콘텐츠를 가져오지 않고 사이트의 URL을 발견하고 싶을 때는 firecrawl_map을 사용하세요.
사이트 아래 여러 페이지의 콘텐츠가 필요할 때는 firecrawl_crawl을 사용하세요. limit, includePaths / excludePaths, 또는 maxDiscoveryDepth를 설정하여 범위를 제한하세요.
URL이 아닌 쿼리에서 시작하여 순위가 매겨진 웹 결과를 원할 때는 firecrawl_search를 사용하세요. 결과에는 발췌문이 포함됩니다. 필요한 URL의 전체 페이지는 firecrawl_scrape로 가져오세요. scrapeOptions는 같은 호출에서 모든 결과의 페이지를 가져오며 각각을 스크레이프로 청구하므로, 몇 개의 결과에 대한 전체 텍스트를 위해 남겨두세요(검색 전용 엔드포인트는 콘텐츠를 절대 가져오지 않습니다).
페이지를 읽기 전에 클릭, 입력, 탐색 작업이 필요할 때는 firecrawl_interact를 사용하세요. 새 페이지에는 url을, 이미 스크레이핑한 페이지에서 계속하려면 scrapeId를 전달하세요.
같은 페이지를 한 번 가져오는 대신 차이점과 변경 알림과 함께 반복 일정으로 확인해야 할 때는 firecrawl_monitor_* 도구를 사용하세요.
남은 크레딧 또는 크레딧이 무엇에 사용되었는지(월별 또는 일별, 선택적으로 엔드포인트 또는 API 키별로 분류) 확인하려면 firecrawl_credit_usage를 사용하세요.
자체 재시도 및 종료 로직으로 여러 단계에 걸쳐 브라우저 세션을 열어두어야 할 때는 다른 방법을 고려하세요. 각 firecrawl_interact 호출은 하나의 프롬프트 또는 코드 턴을 완료까지 실행하고 제어를 반환합니다. 세션은 scrapeId를 통해 호출 간에 유지될 수 있으며 firecrawl_interact_stop으로 종료되지만, 단일 호출 내에서 클라이언트 측에서 단계별로 대화형으로 구동할 수는 없습니다.

이 서버는 전체 프로필이 기본 설정으로 등록될 때 27개의 도구를 나열합니다(피드백 도구 포함, 로컬 키리스 모드로 실행되지 않음). FIRECRAWL_NO_SEARCH_FEEDBACK=1 및/또는 FIRECRAWL_NO_ENDPOINT_FEEDBACK=1을 설정하면 해당 피드백 도구가 제거되어 이 개수가 줄어들며, 로컬 키리스 시작도 마찬가지입니다. 도구 슬롯 제한이 있는 클라이언트의 경우: 호스팅된 키리스 엔드포인트(https://mcp.firecrawl.dev/v2/mcp, API 키 없음)는 3개(firecrawl_scrape, firecrawl_search, firecrawl_parse)만 노출하며, 검색 전용 전용 엔드포인트(https://mcp.firecrawl.dev/v2/mcp-search)는 고정된 9개 도구 세트(검색, 개발자, 정부, 리서치 검색, 그리고 Alexandria 카탈로그 조회 및 실행)를 노출합니다.

설치
호스팅된 MCP (키리스 무료 티어)
설정 없이 원격 호스팅 서버에 연결하세요:

https://mcp.firecrawl.dev/v2/mcp

키리스 무료 티어에서는 scrape, search, parse가 API 키 없이 작동합니다(속도 제한됨). crawl, map, agent 같은 다른 도구는 여전히 키가 필요합니다.

사람이 가입할 수 있을 때는 항상 OAuth 또는 API 키를 선호하세요. 전체 도구 세트와 더 높은 제한이 열립니다.

대화형 계정 연결의 경우, MCP 클라이언트가 이 서버 URL을 사용하도록 구성하세요. 이것은 브라우저 페이지가 아닌 MCP 엔드포인트입니다. 클라이언트의 계정 연결 흐름을 사용하고, 재연결 시 두 번째 Firecrawl 서버 항목을 추가하지 마세요:

https://mcp.firecrawl.dev/v2/mcp-oauth

API 키 연결(예: 무인 통합)의 경우, 서버 URL을 다음과 같이 유지하세요:

https://mcp.firecrawl.dev/v2/mcp

그런 다음 클라이언트의 보안 헤더 또는 시크릿 설정을 다음과 같이 구성하세요:

Authorization: Bearer <FIRECRAWL_API_KEY>

API 키를 서버 URL에 절대 넣지 마세요. API 키를 에이전트 채팅에 절대 넣지 마세요. 클라이언트 또는 시크릿 관리자에서 직접 구성하세요. 클라이언트별 지침은 호스팅된 MCP 설정 가이드 및 에이전트 온보딩 가이드를 참조하세요.

통합 이름 지정
HTTP를 통해 연결하는 통합은 X-Firecrawl-Origin 헤더로 자신의 이름을 지정할 수 있습니다. 예: X-Firecrawl-Origin: my-agent. 서버는 이를 요청 출처 mcp-my-agent@<서버 버전>으로 Firecrawl에 보고하며, 그렇지 않으면 보고했을 클라이언트 이름 또는 User-Agent를 대체합니다. 문자, 숫자, 대시를 사용하세요. 다른 문자의 각 연속은 하나의 대시가 되고, 앞뒤 대시는 제거되며, 이름은 48자에서 잘립니다. 도구 결과는 영향을 받지 않습니다. Firecrawl API로 전송되는 출처(및 임베더의 beforeKeylessRequest에 전달되는 값)만 변경됩니다.

검색 전용 엔드포인트
고정 범위 검색 표면도 다음에서 호스팅됩니다:

https://mcp.firecrawl.dev/v2/mcp-search

고정된 9개 도구 세트를 노출합니다: firecrawl_search, firecrawl_developer_search, firecrawl_gov_search, 네 개의 firecrawl_research_* 도구, 그리고 두 개의 Alexandria 도구 firecrawl_find_tools 및 firecrawl_scrape. 이 firecrawl_search는 페이지 콘텐츠를 가져오지 않습니다.

npx로 실행
env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp
수동 설치
npm install -g firecrawl-mcp
Cursor에서 실행
Cursor 구성 🖥️
참고: Cursor 버전 0.45.6+ 필요
최신 구성 지침은 MCP 서버 구성에 대한 공식 Cursor 문서를 참조하세요:
Cursor MCP Server Configuration Guide

Cursor v0.48.6에서 Firecrawl MCP를 구성하려면

Cursor Settings 열기
Features > MCP Servers로 이동
"+ Add new global MCP server" 클릭
다음 코드 입력:
{
"mcpServers" : {
"firecrawl-mcp" : {
"command" : " npx " ,
"args" : [ " -y " , " firecrawl-mcp " ],
"env" : {
"FIRECRAWL_API_KEY" : " YOUR-API-KEY "
}
}
}
}

Cursor v0.45.6에서 Firecrawl MCP를 구성하려면

Cursor Settings 열기
Features > MCP Servers로 이동
"+ Add New MCP Server" 클릭
다음 입력:

Name: "firecrawl-mcp" (또는 원하는 이름)
Type: "command"
Command: 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 키로 교체하세요. 아직 없다면 계정을 만들고 https://www.firecrawl.dev/app/api-keys에서 받을 수 있습니다

추가한 후 MCP 서버 목록을 새로고침하여 새 도구를 확인하세요. Composer Agent는 적절할 때 Firecrawl MCP를 자동으로 사용하지만, 웹에서 필요한 것을 설명하여 명시적으로 요청할 수도 있습니다. Command+L(Mac)로 Composer에 접근하고, 제출 버튼 옆의 "Agent"를 선택한 후 쿼리를 입력하세요.

Windsurf에서 실행
./codeium/windsurf/model_config.json에 다음을 추가하세요:

{
"mcpServers" : {
"mcp-server-firecrawl" : {
"command" : " npx " ,
"args" : [ " -y " , " firecrawl-mcp " ],
"env" : {
"FIRECRAWL_API_KEY" : " YOUR_API_KEY "
}
}
}
}
Streamable HTTP 로컬 모드로 실행
기본 stdio 전송 대신 로컬에서 Streamable HTTP를 사용하여 서버를 실행하려면:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp
url 사용: http://localhost:3000/mcp

이 모드에서 서버는 localhost, 127.0.0.1 또는 [::1](모든 포트)로 주소 지정된 요청과, HOST의 주소가 0.0.0.0 또는 ::가 아닐 때 해당 주소에만 응답합니다. Host 헤더가 다른 호스트를 지정하거나 Origin 헤더가 다른 사이트를 지정하는 요청은 403을 받으며, CORS 헤더는 * 대신 허용된 출처를 반영합니다. /health에 대한 GET 및 HEAD 요청은 호스트와 관계없이 응답되므로 상태 확인이 계속 작동하며, 서버는 거부하는 모든 요청에 대해 FIRECRAWL_MCP_ALLOWED_HOSTS를 명시하는 로그 줄을 기록합니다. 이는 방문하는 웹 페이지가 DNS 리바인딩 또는 교차 출처 요청을 통해 로컬 서버를 호출하고 그 FIRECRAWL_API_KEY를 사용하는 것을 막습니다.

다른 이름이나 주소(예: 리버스 프록시 뒤의 호스트 이름 또는 LAN IP)로 서버에 접근하려면 FIRECRAWL_MCP_ALLOWED_HOSTS에 나열하세요(쉼표로 구분, 포트는 무시됨). 같은 목록이 서버를 호출할 수 있는 브라우저 출처를 결정합니다. 같은 머신의 리버스 프록시는 기본 바인드 주소를 유지할 수 있습니다:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
FIRECRAWL_MCP_ALLOWED_HOSTS=mcp.home.lan npx -y firecrawl-mcp
다른 머신의 클라이언트는 서버가 루프백이 아닌 주소에서 수신 대기해야 하므로 HOST도 설정하세요. 그러면 포트에 접근할 수 있는 모든 클라이언트가 서버의 FIRECRAWL_API_KEY로 서비스되므로, 신뢰하는 네트워크에서만 이렇게 하세요:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY HOST=0.0.0.0 \
FIRECRAWL_MCP_ALLOWED_HOSTS=192.168.1.20 npx -y firecrawl-mcp
FIRECRAWL_MCP_ALLOWED_HOSTS=*는 검사를 끄고 와일드카드 CORS 헤더를 복원합니다. 서버 앞의 무언가가 자체적으로 호스트와 출처를 검사할 때만 그렇게 하세요.

Docker로 실행
ghcr.io/firecrawl/firecrawl-mcp-server 이미지는 npx -y firecrawl-mcp와 동일한 서버를 실행합니다. main에서의 모든 빌드는 latest, v<package version>, sha-<commit sha>로 태그됩니다. v<package version>은 해당 버전의 최신 빌드로 이동하므로, 고정된 이미지가 필요할 때는 sha-<commit sha>(또는 다이제스트)를 고정하세요.

stdio(기본값), 서버를 명령으로 실행하는 MCP 클라이언트용:

docker run -i --rm -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY ghcr.io/firecrawl/firecrawl-mcp-server:latest
{
"mcpServers" : {
"firecrawl-mcp" : {
"command" : " docker " ,
"args" : [ " run " , " -i " , " --rm " , " -e " , " FIRECRAWL_API_KEY " , " ghcr.io/firecrawl/firecrawl-mcp-server:latest " ],
"env" : {
"FIRECRAWL_API_KEY" : " YOUR_API_KEY "
}
}
}
}
Streamable HTTP, http://localhost:3000/mcp에서 제공:

docker run --rm -p 127.0.0.1:3000:3000 \
-e HTTP_STREAMABLE_SERVER=true \
-e FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
ghcr.io/firecrawl/firecrawl-mcp-server:latest
이미지는 HOST=0.0.0.0 및 PORT=3000을 설정합니다. 다른 곳에서 수신하려면 PORT(및 -p 매핑)를 재정의하세요. 서버는 자체 자격 증명을 보내지 않는 요청에 컨테이너의 FIRECRAWL_API_KEY를 사용하므로, 예제는 포트를 127.0.0.1에만 게시합니다. 클라이언트가 자체 키를 제공해야 하는 경우가 아니면 더 넓게 노출하지 마세요. 자체 호스팅 Firecrawl API를 사용하려면 FIRECRAWL_API_URL을 설정하세요. 컨테이너는 권한 없는 node 사용자로 실행됩니다. 서버는 Host 및 Origin 헤더에서 localhost, 127.0.0.1 및 [::1]에만 응답하므로 -p 127.0.0.1:3000:3000 매핑은 그대로 작동합니다. 다른 이름으로 접근하려면 -e FIRECRAWL_MCP_ALLOWED_HOSTS=<host>를 설정하세요(Streamable HTTP 로컬 모드 참조).

VS Code에서 실행
원클릭 설치의 경우, 아래 설치 버튼 중 하나를 클릭하세요...

수동 설치의 경우, VS Code의 User Settings(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" : " ${in…