본문으로 건너뛰기
MCP 서버 전체 목록

Firecrawl MCP Server

Firecrawl 공식 MCP 서버. 웹 검색 · 스크랩 · 크롤 · 브라우저 조작을 에이전트에 연결해요(원격 · npx · Docker). MIT

원본:firecrawl/firecrawl-mcp-server

연결 · 설치 방법은 설치 탭에 정리했어요.

설명

Firecrawl MCP 서버

Firecrawl(AI 에이전트를 위한 컨텍스트 API)을 MCP 호환 클라이언트에 가져오는 Model Context Protocol(MCP) 서버입니다. 살아 있는 웹을 검색하고, 긁어 오고, 상호작용해서 깔끔한 마크다운이나 구조화된 데이터를 돌려받습니다.

초기 구현을 만들어 준 @vrknetha와 @knacklabs에 감사드립니다!

특징

  • 웹을 검색하고, 원하면 결과마다 페이지 전체 내용도 함께 가져옵니다
  • 개발자 자료(GitHub 이슈, 병합된 풀 리퀘스트, README, 문서), 미국 정부 자료, 과학 논문(PubMed, bioRxiv, medRxiv, arXiv)을 색인으로 검색합니다
  • 어떤 URL이든 깔끔한 마크다운으로 긁어 옵니다
  • PDF와 문서를 파싱합니다
  • 사이트의 여러 페이지 내용을 크롤링하거나, 지도(map)로 만들어 URL을 찾아냅니다
  • 실제 브라우저로 페이지와 상호작용합니다: 클릭, 입력, 양식 채우기, 동적 페이지 이동
  • 여러 출처를 조사해 구조화된 데이터를 돌려주는 에이전트(Agent) 작업을 실행합니다
  • 페이지를 모니터링하고 내용이 바뀌면 알림을 받습니다
  • 현재와 과거의 Firecrawl 크레딧 사용량을 확인합니다
  • 자동 재시도와 속도 제한
  • 클라우드와 자체 호스팅 지원
  • SSE 지원

💡 MCP.so 플레이그라운드나 Klavis AI에서 이 MCP 서버를 먼저 써 볼 수 있습니다.

이 서버를 쓰는 때

  • 주소를 아는 URL의 내용을 마크다운으로 받아서 필요한 항목을 직접 뽑으려면 firecrawl_scrape를 씁니다.
  • 내용을 가져오지 않고 사이트의 URL만 찾으려면 firecrawl_map을 씁니다.
  • 사이트 아래 여러 페이지의 내용이 필요하면 firecrawl_crawl을 쓰고, limit, includePaths/excludePaths, maxDiscoveryDepth로 범위를 제한합니다.
  • URL이 아니라 질의에서 출발해 순위가 매겨진 웹 결과를 얻으려면 firecrawl_search를 씁니다. 결과에는 발췌가 들어 있고, 전체 페이지가 필요하면 그 URL에 firecrawl_scrape를 씁니다. scrapeOptions는 같은 호출에서 모든 결과 페이지를 가져오고 각각 스크랩으로 과금되므로, 몇 개 결과의 전문이 필요할 때만 쓰세요.
  • 페이지를 읽기 전에 클릭, 입력, 이동이 필요하면 firecrawl_interact를 씁니다. 새 페이지는 url을, 이미 스크랩한 페이지는 scrapeId를 넘깁니다.
  • 같은 페이지를 정해진 주기로 확인하며 변경 사항을 비교하고 알림을 받으려면 firecrawl_monitor_* 도구를 씁니다.
  • 남은 크레딧이나 월별 · 일별 사용처를 확인하려면 firecrawl_credit_usage를 씁니다. 엔드포인트나 API 키별로 나눠 볼 수도 있습니다.
  • 내 재시도 · 종료 로직으로 브라우저 세션을 여러 단계에 걸쳐 열어 두고 직접 몰아야 한다면 다른 방법을 고려하세요. firecrawl_interact 호출은 한 번에 prompt 또는 code 한 턴을 끝까지 실행하고 제어를 돌려줍니다. 세션은 scrapeId로 호출 사이에 이어지고 firecrawl_interact_stop으로 끝나지만, 한 번의 호출 안에서 클라이언트 쪽에서 단계별로 직접 몰 수는 없습니다.

기본 설정으로 전체 프로필을 등록하면 이 서버는 도구 33개를 나열합니다(피드백 도구 포함, 로컬 키 없는 모드 아님). 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)는 12개로 고정된 도구(검색, 개발자 · 정부 · 연구 검색, 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. 서버는 클라이언트 이름이나 User-Agent 대신 요청 출처 mcp-my-agent@<버전>으로 Firecrawl에 보고합니다. 영문자, 숫자, 대시를 쓰세요. 그 밖의 글자가 이어지면 대시 하나로 바뀌고, 앞뒤 대시는 지워지며, 이름은 48자에서 잘립니다. 도구 결과는 영향받지 않고, Firecrawl API로 보내는 출처만 바뀝니다.

검색 전용 엔드포인트

범위가 고정된 검색 표면도 아래 주소에서 호스팅합니다.

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

도구 12개를 고정으로 엽니다: firecrawl_search, firecrawl_developer_search, firecrawl_gov_search, firecrawl_research_* 4개, Alexandria 도구 2개 firecrawl_find_tools와 firecrawl_scrape, 보강 도구 people_company_search와 people_company_enrich, 채용 도구 jobs_search. 이 엔드포인트의 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 이상이 필요합니다. 가장 최신 설정 방법은 Cursor 공식 문서 Cursor MCP 서버 설정 안내를 참고하세요.

Cursor v0.48.6에서 Firecrawl MCP를 설정하려면:

  1. Cursor Settings를 엽니다
  2. Features > MCP Servers로 갑니다
  3. "+ Add new global MCP server"를 누릅니다
  4. 다음을 입력합니다:
    {
      "mcpServers": {
        "firecrawl-mcp": {
          "command": "npx",
          "args": ["-y", "firecrawl-mcp"],
          "env": {
            "FIRECRAWL_API_KEY": "YOUR-API-KEY"
          }
        }
      }
    }

Cursor v0.45.6에서 Firecrawl MCP를 설정하려면:

  1. Cursor Settings를 엽니다
  2. Features > MCP Servers로 갑니다
  3. "+ Add New MCP Server"를 누릅니다
  4. 다음을 입력합니다:
  • 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 에이전트는 알맞을 때 자동으로 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

주소는 http://localhost:3000/mcp 입니다.

이 모드에서 서버는 localhost, 127.0.0.1, [::1](어느 포트든)과, 0.0.0.0이나 ::가 아닐 때 HOST의 주소로 오는 요청에만 응답합니다. 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<버전>, sha-<커밋> 태그가 붙습니다. v<버전>은 그 버전의 최신 빌드로 옮겨 가므로, 고정된 이미지가 필요하면 sha-<커밋>(또는 digest)을 고정하세요.

명령으로 서버를 띄우는 MCP 클라이언트용 stdio(기본):

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"
      }
    }
  }
}

http://localhost:3000/mcp로 제공하는 Streamable HTTP:

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=<호스트>를 설정하세요(Streamable HTTP 로컬 모드 참고).

VS Code에서 실행

한 번에 설치하려면 아래 단추 중 하나를 누르세요...

VS Code에서 NPX로 설치 VS Code Insiders에서 NPX로 설치

직접 설치하려면 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 키 필요)
  • stdio에서는 여기에 API 키가 없어도 Alexandria 도구가 이 엔드포인트로 보내지며, 엔드포인트가 계정을 대신해 응답합니다. Firecrawl Local은 자신이 가진 로그인으로 서명합니다
  • FIRECRAWL_INTEGRATION(선택): 이 서버를 띄우는 앱(예: 편집기 확장)을 위한 통합 태그
  • 스크랩, 배치 스크랩, 크롤, 맵, 검색, 추출, 에이전트, 파싱, 상호작용, 피드백 요청의 integration 필드로 보냅니다
  • _로 시작하는 값을 쓰세요. 예: _zed

로컬 HTTP 모드

  • FIRECRAWL_MCP_ALLOWED_HOSTS(선택): HTTP_STREAMABLE_SERVER=true 또는 SSE_LOCAL=true일 때 서버가 응답할 추가 호스트 이름이나 주소, 쉼표로 구분
  • localhost, 127.0.0.1, [::1], 와일드카드가 아닌 HOST는 항상 허용되며 포트는 무시됩니다
  • Host나 Origin 헤더가 다른 호스트를 가리키는 요청은 /health에 대한 GET과 HEAD를 제외하고 403을 받습니다
  • *는 검사를 끕니다. CLOUD_SERVICE=true에서는 쓰이지 않으며, 이 경우 모든 호스트에 응답합니다

MCP OAuth (Bearer 액세스 토큰)

Firecrawl은 firecrawl.dev의 인가 서버로 OAuth 액세스 토큰(fco_…)을 발급합니다. 이 MCP 서버는 확인한 자격 증명을 Authorization: Bearer …로 Firecrawl API에 전달합니다.

  • HTTP 스트림 전송(CLOUD_SERVICE=true, HTTP_STREAMABLE_SERVER=true, SSE_LOCAL=true): 클라이언트는 MCP 요청에 Authorization: Bearer <fco_access_token>을 보내야 합니다. OAuth Bearer 토큰은 x-firecrawl-api-key / x-api-key와 함께 있으면 그보다 우선합니다.
  • stdio: 고정 액세스 토큰에는 FIRECRAWL_OAUTH_TOKEN을 쓰거나, 계속 FIRECRAWL_API_KEY(API 키)를 쓰세요.

액세스 토큰(fco_…)만 쓰세요. 리프레시 토큰(fcr_…)은 토큰 엔드포인트에서 교환해야 하며 스크랩/검색 API에 넘기면 안 됩니다.

CLOUD_SERVICE=true

CLOUD_SERVICE=true는 더 엄격한 기본값으로 PORT(기본 3000, 0.0.0.0에 바인드)에서 Streamable HTTP로 도구를 제공합니다. 모든 요청에 자격 증명(API 키나 OAuth 액세스 토큰)이 있어야 하고, 스크랩은 읽기 전용이며(아래 스크랩 도구 참고), firecrawl_parse는 업로드만 받습니다.

FASTMCP_ENDPOINT가 도구 표면을 고릅니다: 전체 도구는 /v2/mcp(기본), 계정 표면은 /v2/mcp-oauth, 검색 전용 도구는 /v2/mcp-search(이때는 FIRECRAWL_MCP_SEARCH_OAUTH_ONLY=true도 필요)입니다. 전체 표면에서는 검색 전용 인스턴스도 포트 3001에서 함께 시작되며, 끄려면 FIRECRAWL_MCP_SEARCH_ENABLED=false로 설정하세요.

설정 예시

클라우드 API를 쓸 때:

export FIRECRAWL_API_KEY=your-api-key

자체 호스팅 인스턴스:

# 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

Claude Desktop에서 쓰기

claude_desktop_config.json에 추가하세요.

{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

도구 고르는 법

이 안내로 일에 알맞은 도구를 고르세요.

  • 원하는 URL을 정확히 안다면: scrape를 쓰고, 돌려받은 마크다운에서 필요한 항목을 뽑습니다
  • 아는 URL이 여럿이라면: URL마다 scrape를 부릅니다. 한 번에 묶는 대량 API 작업이 꼭 필요하면 MCP 밖에서 Firecrawl API의 batch 엔드포인트를 씁니다.
  • 사이트의 URL을 찾아야 한다면: map
  • 웹에서 정보를 찾는다면: search
  • 프로그래밍 질문이라면(라이브러리, API 계약, 오류 메시지, 알려진 버그): developer search
  • 법률 · 규제 질문이라면(법령, 규정, 법전, 판결문, 그 밖의 미국 정부 간행물): Firecrawl Government Index
  • 과학 논문이 필요하다면(생의학, 생명과학, 임상, arXiv 문헌): 논문 초록과 전문을 검색하는 research 도구. categories: ["research"]를 준 search는 다른 것으로, 일반 웹 결과를 걸러 내는 웹사이트 필터입니다.
  • URL을 모르거나 답이 여러 사이트에 걸친 다중 출처 조사에서 구조화된 데이터가 필요하다면(개체와 그 항목, 목록, 데이터셋): agent
  • 사이트나 구역 전체를 분석한다면: crawl(한도를 꼭 걸 것!)
  • 브라우저 자동화(클릭, 입력, 이동)가 필요하다면: 새 페이지는 URL로 interact, 이미 스크랩했거나 스크랩을 더 세밀하게 다뤄야 하면 scrape + interact
  • 카탈로그에 있는 제공자(Alexandria)의 데이터가 필요하다면: sources: ["alexandria"]로 검색하고, alexandria_library_search로 라이브러리를 둘러보고 계약을 읽으며, alexandria_library_read로 실행합니다

빠른 참조 표

도구알맞은 용도돌려주는 것
scrape한 페이지의 내용기본은 마크다운
interactURL이나 스크랩한 페이지와 상호작용실행 결과 + URL 모드의 scrapeId
map사이트의 URL 찾기URL[]
crawl여러 페이지 추출(한도와 함께)내부 폴링 뒤의 최종 크롤 상태/데이터
parse파일과 호스팅 업로드 참조마크다운, JSON, 문서 출력
search정보를 찾는 웹 검색results[]
alexandria_library_search셸 명령으로 Alexandria 라이브러리 둘러보기명령 출력: 파일 경로, README, 계약
alexandria_library_readAlexandria 기능 실행, 호출당 최대 10개타입이 있고 출처가 있는 레코드
developer개발자 자료로 하는 프로그래밍 질문구절이 든 results[]
gov미국 1차 법령과 규제 자료발췌가 든 results[]
agent다중 출처 조사, 모르거나 여러 사이트JSON(구조화된 데이터)
monitor반복되는 페이지 확인모니터/확인 메타데이터와 변경 비교
research논문 조사(저장소는 developer)연구 결과

형식 고르는 안내

scrape를 쓸 때 알맞은 형식을 고르세요.

  • 마크다운 형식: 페이지를 읽고 필요한 항목을 직접 뽑을 때

쓸 수 있는 도구

1. 스크랩 도구(firecrawl_scrape)

고급 옵션으로 한 URL의 내용을 긁어 옵니다.

알맞은 용도:

  • 어느 페이지에 정보가 있는지 정확히 알 때의 한 페이지 내용 추출

권하지 않는 용도:

  • 여러 페이지에서 내용 추출(아는 URL은 scrape를 반복하거나, map + scrape로 먼저 URL을 찾거나, 페이지 전체 내용에는 crawl)
  • 어느 페이지에 정보가 있는지 모를 때(search를 쓰세요)

흔한 실수:

  • scrape 한 번에 URL 목록을 넘기기. MCP에서는 URL마다 scrape를 한 번씩 부르세요. 한 번에 묶는 대량 API 작업이 꼭 필요하면 MCP 밖에서 Firecrawl API의 batch 엔드포인트를 쓰세요.
  • 새 MCP scrape 호출에 json이나 jsonOptions 요청하기. 이 입력은 검색 목록에서 숨겨져 있지만 캐시된 도구 정의와의 호환을 위해 계속 받아들여집니다.

프롬프트 예시:

"https://example.com/product 에서 제품 정보를 가져와 줘."

사용 예시(제품 정보 읽기):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/product",
    "formats": ["markdown"]
  }
}

사용 예시(마크다운 형식 — 전체 내용이 필요할 때):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/article",
    "formats": ["markdown"],
    "onlyMainContent": true
  }
}

사용 예시(branding 형식 — 브랜드 정체성 추출):

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["branding"]
  }
}

Branding 형식: 디자인 분석이나 스타일 재현을 위해 브랜드 정체성(색, 글꼴, 타이포그래피, 간격, 로고, UI 구성 요소)을 종합해 추출합니다. 개인정보: redactPII: true를 주면 개인 식별 정보를 가린 내용을 돌려줍니다. CLOUD_SERVICE=true일 때: 스크랩은 읽기 전용입니다. 브라우저 actions를 받지 않고 제공자 약관에 동의할 수 없습니다. 이름 붙은 profile은 변경을 저장하지 않고 저장된 브라우저 상태를 불러오며, 전체 엔드포인트의 firecrawl_search도 scrapeOptions.profile을 같게 다룹니다. 브라우저 상태를 프로필에 저장하려면 firecrawl_interact로 페이지를 여세요(아래 참고). 약관 동의는 조직 관리자가 대시보드에서 합니다.

돌려주는 것:

  • 지정한 마크다운, 브랜딩 프로필, 그 밖의 형식.

2. 맵 도구(firecrawl_map)

웹사이트를 지도로 만들어 색인된 모든 URL을 찾습니다.

알맞은 용도:

  • 무엇을 긁을지 정하기 전에 웹사이트의 URL 찾기
  • 웹사이트의 특정 구역 찾기

권하지 않는 용도:

  • 필요한 URL을 이미 알 때(scrape를 쓰세요)
  • 페이지 내용이 필요할 때(지도를 만든 뒤 scrape를 쓰세요)

흔한 실수:

  • URL을 찾는 데 map 대신 crawl 쓰기

프롬프트 예시:

"example.com의 모든 URL을 나열해 줘."

사용 예시:

{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com"
  }
}

돌려주는 것:

  • 사이트에서 찾은 URL 배열

3. 검색 도구(firecrawl_search)

웹을 검색하고, 원하면 검색 결과의 내용을 추출합니다.

알맞은 용도:

  • 어느 웹사이트에 정보가 있는지 모를 때 여러 웹사이트에서 특정 정보 찾기
  • 질의에 가장 알맞은 내용이 필요할 때

권하지 않는 용도:

  • 긁을 웹사이트를 이미 알 때(scrape를 쓰세요)
  • 한 웹사이트를 빠짐없이 다뤄야 할 때(map이나 crawl을 쓰세요)

흔한 실수:

  • 열린 질문에 crawl이나 map 쓰기(search를 쓰세요)

사용 예시:

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "remote work stipend policies at tech companies",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us"
  }
}

같은 호출에서 몇몇 결과의 전문까지 받으려면 "scrapeOptions": { "formats": ["markdown"], "onlyMainContent": true }를 더하세요. 가져온 결과마다 스크랩으로 과금되므로, 대부분의 질문에는 발췌를 쓰고 필요한 URL에만 firecrawl_scrape를 쓰세요.

highlights를 true로 두면 질의와 관련된 하이라이트를 요청하고, false로 두면 원래 검색 스니펫을 유지합니다. 생략하면 API의 기본 동작을 따릅니다.

"sources": ["alexandria"]를 더하면 data.tools에서 의미 기반 도구 찾기를 하며, 웹/뉴스/이미지와 섞을 수도 있습니다. 질의가 필요합니다. 라이브러리 전체를 둘러보고 계약을 읽으려면 alexandria_library_search(검색 전용 엔드포인트에서는 firecrawl_find_tools)를 쓰세요.

과학 논문은 연구 도구를 보세요. 이 도구들은 논문 초록과 전문을 검색하는 반면, 여기의 categories: ["research"]는 일반 웹 결과를 연구 관련 웹사이트로 걸러 냅니다.

돌려주는 것:

  • 출처별로 묶은 검색 결과(data.web, data.images, data.news)와 선택적인 스크랩 내용, 그리고 id 필드. 모든 결과에는 source와 1부터 시작하는 position이 있으며, 각 묶음 안에서 1부터 매깁니다. 배열 요소를 세지 말고 이 쌍을 그대로 firecrawl_search_feedback의 valuableResults에 복사하세요. 결과를 쓴 뒤 그 id를 firecrawl_search_feedback에 넘기면 크레딧 1을 환급받고(검색은 2) 검색 품질이 개선됩니다.

프롬프트 예시:

"기술 기업들의 원격근무 수당 정책을 비교해 줘."

3b. 검색 피드백 도구(firecrawl_search_feedback)

이전 firecrawl_search 결과에 대한 구조화된 피드백을 보냅니다. 검색 id마다 첫 피드백은 크레딧 1을 환급하고 Firecrawl의 검색 품질을 높입니다. 검색 id마다 멱등입니다.

실제로 쓴(또는 도움이 되지 않은) 검색마다 호출하세요. missingContent가 있는 나쁜/부분 피드백도 좋은 피드백만큼 가치 있습니다.

끄기: MCP 서버를 시작할 때 환경에 FIRECRAWL_NO_SEARCH_FEEDBACK=1(또는 FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1)을 설정하세요. firecrawl_search_feedback 도구가 등록되지 않아 에이전트가 부를 수 없습니다. 팀 관리자가 서버 쪽에서 끌 수도 있으며, 그러면 도구는 등록되지만 항상 feedbackErrorCode: "TEAM_OPTED_OUT"을 돌려줍니다.

가장 중요한 필드: missingContent. 에이전트가 찾을 줄 알았지만 찾지 못한 구체적인 내용의 배열입니다. 빠진 주제마다 한 항목을 넣습니다. 팀에 걸쳐 집계되어 다음에 무엇을 색인할지 알려 줍니다. 쓸모 있는 결과를 위해 각 결과에 찍힌 source/position 쌍과 함께 valuableResults를 쓰세요. 결과는 묶음별로 나뉘어 각각 1부터 번호가 매겨지므로 둘 다 필요합니다. 쓸모 있었던 결과를 모두 적고(적지 않은 결과는 쓸모없다고 봅니다), valuableSources는 돌려받은 결과에 없었던 쓸모 있는 URL에만 쓰세요.

일일 환급 한도(팀별, UTC 하루당, 기본 100크레딧). 팀의 creditsRefundedToday가 dailyRefundCap에 닿으면 피드백은 기록되지만 더는 크레딧이 환급되지 않습니다. 응답에 dailyCapReached: true가 설정됩니다. 에이전트는 이 표시를 보면 그날 UTC 나머지 시간 동안 이 도구 호출을 멈춰야 합니다.

사용 예시:

{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableResults": [
      { "source": "web", "position": 1 },
      { "source": "web", "position": 3 },
      { "source": "news", "position": 2, "reason": "Broke the pricing change." }
    ],
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/pricing",
        "reason": "Not in the results; found via a result's pricing link. Answered the question."
      }
    ],
    "missingContent": [
      {
        "topic": "Pricing for the search endpoint",
        "description": "No pricing tier table for /search specifically."
      },
      { "topic": "Per-team rate limits" }
    ],
    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
  }
}

돌려주는 것:

  • { success, feedbackId, creditsRefunded, alreadySubmitted? } JSON.

3c. 일반 피드백 도구(firecrawl_feedback)

/v2/feedback으로 끝난 v2 엔드포인트 작업에 대한 구조화된 피드백을 보냅니다. scrape, parse, map, search 작업의 엔드포인트 수준 피드백에 쓰세요. 검색 결과 품질만 다룰 때는 검색 전용 안내가 있는 firecrawl_search_feedback을 권합니다.

피드백은 간결하게 쓰세요. 이슈 코드, 태그, 짧은 메모, URL, 페이지 번호, 작은 메타데이터 객체를 쓰고, 스크랩/파싱 원문 출력은 넣지 마세요.

끄기: MCP 서버를 시작할 때 환경에 FIRECRAWL_NO_ENDPOINT_FEEDBACK=1(또는 FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1)을 설정하세요. firecrawl_feedback 도구가 등록되지 않아 에이전트가 부를 수 없습니다.

사용 예시:

{
  "name": "firecrawl_feedback",
  "arguments": {
    "endpoint": "scrape",
    "jobId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "partial",
    "issues": ["missing_markdown"],
    "tags": ["docs"],
    "note": "The pricing table was missing from the markdown output.",
    "url": "https://example.com/pricing",
    "pageNumbers": [1],
    "metadata": {
      "format": "markdown"
    }
  }
}

돌려주는 것:

  • { success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, websiteCapReached?, alreadySubmitted?, warning? } JSON.

4. 크롤 도구(firecrawl_crawl)

크롤 작업을 시작하고, 끝 상태에 닿을 때까지 폴링한 뒤 최종 크롤 상태와 데이터를 돌려줍니다.

알맞은 용도:

  • 서로 관련된 여러 페이지에서 빠짐없이 내용을 추출해야 할 때

권하지 않는 용도:

  • 한 페이지의 내용 추출(scrape를 쓰세요)
  • 토큰 한도가 걱정될 때(더 세밀하게 다루려면 map + scrape)
  • 빠른 결과가 필요할 때(크롤은 느릴 수 있습니다)

경고: 크롤 응답은 매우 커서 토큰 한도를 넘길 수 있습니다. 크롤 깊이와 페이지 수를 제한하거나, 더 세밀하게 다루려면 map + scrape를 쓰세요.

흔한 실수:

  • limit이나 maxDiscoveryDepth를 너무 높게 잡기(토큰 넘침의 원인)
  • 한 페이지에 crawl 쓰기(scrape를 쓰세요)

프롬프트 예시:

"example.com/blog의 처음 두 단계에 있는 블로그 글을 모두 가져와 줘."

사용 예시:

{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com/blog/*",
    "maxDiscoveryDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}

돌려주는 것:

  • id, status, completed, total, creditsUsed, expiresAt, next, data를 포함한 내부 폴링 뒤의 최종 크롤 상태와 데이터. 나중에 작업을 다시 확인하려면 돌려받은 id를 firecrawl_check_crawl_status에 쓰세요.

5. 크롤 상태 확인(firecrawl_check_crawl_status)

ID로 이미 있는 크롤 작업의 상태와 결과를 확인합니다.

{
  "name": "firecrawl_check_crawl_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

돌려주는 것:

  • 크롤 작업의 상태가 담긴 응답

6. 파싱 도구(firecrawl_parse)

Firecrawl의 /v2/parse 엔드포인트로 로컬 파일이나 호스팅 업로드 참조를 파싱합니다.

알맞은 용도: 마크다운이나 구조화된 JSON 출력이 필요한 PDF, Word 문서, 스프레드시트, HTML 파일 등의 문서. 호스팅 엔드포인트는 2단계 업로드 흐름을 쓰며, 로컬 파일을 직접 읽으려면 자체 호스팅 FIRECRAWL_API_URL이 필요합니다.

권하지 않는 용도: 원격 URL(scrape를 쓰세요), 한 호출에 여러 파일(파일마다 parse를 한 번씩 부르세요), 스크린샷이나 클릭 같은 브라우저 전용 동작.

호스팅 엔드포인트: 내 파일 시스템을 읽을 수 없습니다. filePath로 firecrawl_parse를 부르면 짧은 수명의 업로드 명령과 nextToolCall을 받습니다. 로컬에서 파일을 올린 뒤 돌려받은 uploadRef로 firecrawl_parse를 다시 부르세요. 업로드 단계에는 Firecrawl 인증이나 키 없는 구간이 필요합니다. 로컬 npx firecrawl-mcp 모드에서는 직접 파일 파싱에 자체 호스팅 Firecrawl API를 가리키는 FIRECRAWL_API_URL이 필요하며, API 키만 있는 일반 클라우드 로컬 서버는 이 도구로 파일을 읽고 올릴 수 없습니다.

사용 예시:

{
  "name": "firecrawl_parse",
  "arguments": {
    "filePath": "/absolute/path/to/document.pdf",
    "formats": ["markdown"],
    "parsers": ["pdf"],
    "zeroDataRetention": true
  }
}

돌려주는 것: 파싱된 문서 내용 또는 nextToolCall이 든 호스팅 업로드 안내.

7. 아는 페이지의 구조화된 데이터

formats: ["markdown"]로 URL마다 firecrawl_scrape를 한 번씩 부른 뒤, 돌려받은 내용에서 필요한 항목을 직접 뽑으세요.

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/product",
    "formats": ["markdown"]
  }
}

URL을 모르거나 데이터가 여러 사이트에 걸쳐 있으면 다중 출처 조사에 firecrawl_agent를 쓰세요.

8. 에이전트 도구(firecrawl_agent)

URL을 모르거나 답이 여러 사이트에 걸칠 때 구조화된 데이터를 돌려주는 자율 웹 조사 에이전트입니다. 필요한 항목을 설명하고, 원하면 JSON 스키마와 시작 URL을 주면, 에이전트가 검색하고, 이동하고, 페이지를 읽고, 여러 출처에서 모은 JSON을 돌려줍니다. 개체와 그 항목, 목록과 데이터셋, 데이터에 닿으려면 이동이 필요한 페이지에 쓰세요. 아는 URL 하나에는 마크다운으로 firecrawl_scrape를 쓰고 필요한 항목을 직접 뽑으세요.

동작 방식:

에이전트는 웹 검색을 하고, 링크를 따라가고, 페이지를 읽고, 데이터를 자율적으로 모읍니다. 이것은 비동기로 실행됩니다. 작업 ID를 바로 돌려주면 firecrawl_agent_status를 폴링해 끝났는지 확인하고 결과를 가져옵니다.

비동기 흐름:

  1. 프롬프트/스키마로 firecrawl_agent를 부릅니다 → 작업 ID를 돌려줍니다
  2. 에이전트가 조사하는 동안 다른 일을 합니다(복잡한 질의는 몇 분 걸릴 수 있습니다)
  3. 작업 ID로 firecrawl_agent_status를 폴링해 진행 상황을 확인합니다
  4. 상태가 "completed"이면 응답에 추출된 데이터가 들어 있습니다

알맞은 용도:

  • 정확한 URL을 모르는 복잡한 조사 작업
  • 여러 출처에서 데이터 모으기
  • 웹에 흩어진 정보 찾기
  • 결과를 기다리는 동안 다른 일을 할 수 있는 작업

권하지 않는 용도:

  • URL을 아는 단순한 한 페이지 스크랩(마크다운으로 scrape를 쓰고 필요한 항목을 직접 뽑으세요)

인자:

  • prompt: 원하는 데이터를 자연어로 설명(필수, 최대 10,000자)
  • urls: 에이전트가 특정 페이지에 집중하게 하는 선택적 URL 배열
  • schema: 구조화된 출력을 위한 선택적 JSON 스키마
  • effort: 선택. 에이전트 작업의 추론 예산 "low", "medium", "high".
  • maxCredits: 선택, 양의 정수. 이번 실행의 크레딧 지출 한도. 생략하면 API 기본값은 2,500이고 무료 요청은 2,500으로 제한됩니다.
  • strictConstrainToURLs: 선택, 불리언. true이면 에이전트는 urls의 URL만 방문합니다.
  • threadId: 선택. 기존 스레드를 이어 갑니다. 앞선 firecrawl_agent나 firecrawl_agent_status 결과의 threadId. 새 스레드를 시작하려면 생략하세요. 후속 호출에서 생략한 mode, urls, schema, exchange 설정은 이전 턴에서 이어집니다.
  • mode: 선택. "extract"(기본)는 매 턴 완전한 구조화 결과를 돌려줍니다. "chat"은 새 데이터를 요구하지 않는 후속 질문에 다시 실행하지 않고 message로 짧게 답하게 합니다. exchange.requireApproval에 필요합니다.
  • exchange: 선택. 이번 턴의 Alexandria 제공자 설정으로, POST /v2/agent에 그대로 전달됩니다.
  • enabled, toolkits(제공자 슬러그 최대 5개), maxCalls(1~30), requireApproval(유료 호출은 pendingApproval로 턴을 끝내며, 후속 호출이어도 같은 호출에 mode: "chat"이 필요)
  • onTermsRequired: 에이전트가 쓰려는 Alexandria 제공자가 내 팀이 동의하지 않은 데이터 약관을 요구할 때의 동작. 약관 제한이 걸린 제공자는 어떤 모드에서도 호출되지 않습니다. 후속 호출에서 생략하면 이전 턴의 값이 유지됩니다.
  • "skip"(기본): 동의된 제공자만으로 답합니다. 상태 결과의 exchange.skippedProviders에 도움이 됐을 약관 제한 제공자가 나옵니다.
  • "ask": 같은 동작에 더해 약관 pendingApproval과 승인 ID, 제공자 요구 사항이 담긴 exchange.requiresAction을 돌려줍니다. 약관은 terms/show로 읽고, 조직 관리자가 Firecrawl 대시보드에서 동의합니다.
  • approve: { approvalId, callIds?, always? }로, 직전 턴이 끝난 pendingApproval에 예라고 답합니다. callIds와 always는 유료 호출 승인에만 적용됩니다.
  • decline: { approvalId }로 아니오라고 답합니다. 거절한 약관 제안은 그 스레드의 남은 동안 해당 제공자를 제외합니다.
  • approve와 decline은 threadId가 필요하고, 둘 중 하나만 보낼 수 있습니다.

제공자 약관(ask 모드): 자동 동의 모드는 없습니다. 턴이 약관 제안으로 끝나면 상태 결과에 pendingApproval(kind: "terms")과 승인 ID, 제공자 요구 사항이 담긴 exchange.requiresAction이 들어 있습니다. API 응답의 terms/accept 설명자는 MCP로는 쓸 수 없습니다. 제공자를 쓰려면:

  1. 사용자에게 약관을 보여 줍니다(alexandria_library_read로 terms/show).
  2. 조직 관리자에게 제공자 URL이나 데이터 소스 설정에서 약관에 동의하라고 안내합니다. 데이터를 달라는 요청은 동의가 아닙니다.
  3. 관리자가 대시보드에서 동의했다고 확인할 때까지 기다립니다.
  4. 같은 스레드를 이어 갑니다: 같은 threadId와 exchange.approve: { "approvalId": "..." }로 firecrawl_agent를 부릅니다. 이것은 조사를 재개할 뿐 약관에 동의하는 것이 아닙니다.

사용자가 아니라고 하면 같은 threadId와 exchange.decline: { "approvalId": "..." }로 firecrawl_agent를 부르세요.

프롬프트 예시:

"Firecrawl 창업자들과 그들의 배경을 찾아 줘"

사용 예시(에이전트를 시작한 뒤 결과 폴링):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Find the top 5 AI startups founded in 2024 and their funding amounts",
    "schema": {
      "type": "object",
      "properties": {
        "startups": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "funding": { "type": "string" },
              "founded": { "type": "string" }
            }
          }
        }
      }
    }
  }
}

그런 다음 돌려받은 작업 ID로 firecrawl_agent_status를 폴링하세요.

사용 예시(URL 지정 — 에이전트가 특정 페이지에 집중):

{
  "name": "firecrawl_agent",
  "arguments": {
    "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    "prompt": "Compare the features and pricing information from these pages"
  }
}

더 알아보기

저장소 README는 이어서 에이전트 상태 확인(firecrawl_agent_status), 브라우저 상호작용(firecrawl_interact · firecrawl_interact_stop), 모니터(firecrawl_monitor_*), 크레딧 사용량(firecrawl_credit_usage), 연구 도구(firecrawl_research_*), Alexandria 도구, 보강 도구(people_company_search · people_company_enrich), 채용 도구(jobs_search), 로깅 · 오류 처리, 속도 제한, 개발 방법, 라이선스를 다룹니다. 전체 내용은 원문 README에서 확인하세요.

라이선스

이 프로젝트는 MIT 라이선스로 배포됩니다. 자세한 조항은 LICENSE 파일을 보세요.


저장소: firecrawl/firecrawl-mcp-server