Firecrawl MCP

官方

為Cursor和Claude等LLM客戶端添加強大的網頁抓取和搜索功能。

造訪 firecrawl.link

你可以用 Firecrawl MCP 做什麼？

  • 擷取已知 URL — 請你的助理透過 firecrawl_scrape 將單一頁面抓取成乾淨的 Markdown，或符合你提供之結構描述的結構化 JSON。
  • 探索網站 URL — 讓它先用 firecrawl_map 列出網站上已建立索引的 URL，再決定要擷取哪些頁面。
  • 搜尋網路 — 透過 firecrawl_search 取得查詢的排名結果，並可選擇為部分結果擷取完整頁面內容。
  • 爬取多個頁面 — 使用 firecrawl_crawl 擷取整個網站的內容，並以 limit、includePaths/excludePaths 或 maxDiscoveryDepth 加以限制。
  • 操作瀏覽器 — 透過 firecrawl_interact 點擊、輸入、填寫表單或瀏覽動態頁面，並以 scrapeId 延續工作階段。
  • 檢查額度用量 — 透過 firecrawl_credit_usage 詢問還剩多少 Firecrawl 額度，或額度花在哪些用途上。

文件

Firecrawl MCP Server

一個 Model Context Protocol (MCP) 伺服器，將 Firecrawl（為 AI 代理打造的 context API）帶給相容於 MCP 的用戶端：搜尋、擷取並與即時網路互動，並取回乾淨的 Markdown 或結構化資料。

非常感謝 @vrknetha、@knacklabs 的初始實作！

功能

  • 搜尋網路，可選擇為每筆結果取得完整頁面內容
  • 搜尋開發者來源（GitHub issues、已合併的 pull request、README 與文件）、美國政府來源，以及科學論文（PubMed、bioRxiv、medRxiv、arXiv）的索引
  • 將任何 URL 擷取為乾淨的 Markdown 或結構化 JSON
  • 解析 PDF 與文件
  • 爬取網站以取得多個頁面的內容，或對其進行對應以探索其 URL
  • 在真實瀏覽器中與頁面互動：點擊、輸入、填寫表單，並瀏覽動態頁面
  • 執行 Agent 作業以進行多來源研究並回傳結構化資料
  • 監控頁面並在其內容變更時收到通知
  • 檢查目前與歷史的 Firecrawl 額度使用量
  • 自動重試與速率限制
  • 支援雲端與自架
  • 支援 SSE

在 MCP.so 的 playground 上試玩我們的 MCP Server，或在 Klavis AI 上試玩。

何時使用此伺服器

  • 當你有已知的 URL，並想以 markdown 或符合你所提供 schema 的 JSON 取得其內容時，使用 firecrawl_scrape。
  • 當你需要探索網站上的 URL 而不擷取其內容時，使用 firecrawl_map。
  • 當你需要網站下多個頁面的內容時，使用 firecrawl_crawl；設定 limit、includePaths/excludePaths 或 maxDiscoveryDepth 來限制範圍。
  • 當你從查詢而非 URL 開始，並想要依相關性排序的網路結果時，使用 firecrawl_search。結果會附帶摘要；對你需要的 URL 使用 firecrawl_scrape 取得完整頁面。scrapeOptions 會在同一次呼叫中擷取每筆結果的頁面，並將每一筆都計為一次 scrape，因此請保留給少數結果的完整文字使用（僅搜尋的端點永遠不會擷取內容）。
  • 當頁面需要點擊、輸入或導覽動作才能閱讀時，使用 firecrawl_interact：傳入 url 以取得全新頁面，或傳入 scrapeId 以在你已擷取的頁面上繼續。
  • 當同一頁面需要依固定排程反覆檢查，並取得差異與變更警示，而非只擷取一次時，使用 firecrawl_monitor_* 工具。
  • 使用 firecrawl_credit_usage 檢查剩餘額度或額度花費在何處，可依月份或日期，並可選擇依端點或 API key 細分。
  • 當你需要在你自己的多個步驟之間保持瀏覽器工作階段開啟，並使用你自己的重試與終止邏輯時，請考慮其他方案：每次 firecrawl_interact 呼叫都會執行一輪 prompt 或 code 至完成並交還控制權。工作階段可透過 scrapeId 跨呼叫持續存在，並以 firecrawl_interact_stop 結束，但你無法在單次呼叫中從用戶端逐步互動式地驅動它。

當完整設定檔以預設設定註冊時（包含回饋工具，且未以本機無金鑰模式執行），此伺服器會列出 27 個工具。設定 FIRECRAWL_NO_SEARCH_FEEDBACK=1 和/或 FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 會移除對應的回饋工具並減少此數量，本機無金鑰啟動亦然。對於有工具槽位限制的用戶端：託管的無金鑰端點（https://mcp.firecrawl.dev/v2/mcp，無 API key）僅提供 3 個（firecrawl_scrape、firecrawl_search、firecrawl_parse），而專用的僅搜尋端點（https://mcp.firecrawl.dev/v2/mcp-search）提供固定的 9 個工具（search、developer、government 與 research search，加上 Alexandria 目錄查詢與執行）。

安裝

託管 MCP（無金鑰免費方案）

無需任何設定即可連線至遠端託管伺服器：

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

在無金鑰免費方案中，scrape、search 與 parse 無需 API key 即可運作（有速率限制）。其他工具如 crawl、map 與 agent 仍需要金鑰。

只要使用者能註冊，就優先使用 OAuth 或 API key。這可解鎖完整工具集與更高的限制。

若要進行互動式帳號連線，請設定你的 MCP 用戶端使用此伺服器 URL。這是 MCP 端點，不是瀏覽器頁面；請使用用戶端的帳號連線流程，並在重新連線時不要新增第二個 Firecrawl 伺服器項目：

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

若要使用 API key 連線（例如無人值守的整合），請將伺服器 URL 保持為：

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

然後在用戶端的安全標頭或密鑰設定中設定：

Authorization: Bearer <FIRECRAWL_API_KEY>

絕不要將 API key 放入伺服器 URL。絕不要將 API key 放入代理聊天中。請直接在用戶端或密鑰管理員中設定。用戶端專屬的指示請參閱託管 MCP 設定指南與代理上線指南。

為你的整合命名

透過 HTTP 連線的整合可以使用 X-Firecrawl-Origin 標頭為自己命名，例如 X-Firecrawl-Origin: my-agent。伺服器會將其以請求來源 mcp-my-agent@<server version> 回報給 Firecrawl，取代原本會回報的用戶端名稱或 User-Agent。請使用字母、數字與連字號：其他字元的每一段連續字元會變成一個連字號，開頭與結尾的連字號會被移除，名稱會截斷於 48 個字元。工具結果不受影響；只有傳送給 Firecrawl API 的來源（以及傳遞給嵌入器的 beforeKeylessRequest）會改變。

僅搜尋端點

固定範圍的搜尋介面也託管於：

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

它提供固定的九個工具：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+ 版本 如需最新的設定指示，請參閱 Cursor 官方關於設定 MCP 伺服器的文件： Cursor MCP Server Configuration Guide

在 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 key。如果你還沒有，可以建立帳號並從 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 模式執行

若要在本機使用 Streamable HTTP 而非預設的 stdio 傳輸來執行伺服器：

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>（或一個 digest）。

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_URL 以使用自架的 Firecrawl API。容器以非特權的 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 上執行

若要一鍵安裝，請點擊下方的其中一個安裝按鈕...

Install with NPX in VS Code Install with NPX in VS Code Insiders

若要手動安裝，請將以下 JSON 區塊加入 VS Code 中的 User Settings (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 key
    • 使用雲端 API（預設）時為必需
    • 使用搭配 FIRECRAWL_API_URL 的自架執行個體時為選用
  • FIRECRAWL_API_URL（選用）：自架執行個體的自訂 API 端點
    • 範例：https://firecrawl.your-domain.com
    • 若未提供，將使用雲端 API（需要 API key）
  • FIRECRAWL_INTEGRATION（選用）：供啟動此伺服器的應用程式（例如編輯器擴充功能）使用的整合標籤
    • 會作為 scrape、batch scrape、crawl、map、search、extract、agent、parse、interact 與 feedback 請求的 integration 欄位傳送
    • 請使用以 _ 開頭的值，例如 _zed

本機 HTTP 模式

  • FIRECRAWL_MCP_ALLOWED_HOSTS（選填）：伺服器以 HTTP_STREAMABLE_SERVER=true 或 SSE_LOCAL=true 回應的額外主機名稱或位址，以逗號分隔
    • localhost、127.0.0.1、[::1] 以及非萬用字元的 HOST 一律允許；連接埠會被忽略
    • 若請求的 Host 或 Origin 標頭指定任何其他主機，會得到 403，但對 /health 的 GET 與 HEAD 請求除外
    • * 會關閉此檢查；不與 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_…）必須在權杖端點交換，不可傳遞給 scrape/search API。

CLOUD_SERVICE=true

CLOUD_SERVICE=true 透過可串流 HTTP 在 PORT 上提供工具（預設 3000，繫結至 0.0.0.0），並採用更嚴格的預設值：每個請求都必須攜帶憑證（API 金鑰或 OAuth 存取權杖）、scrape 為唯讀（見下方 scrape 工具），且 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（搭配 JSON 格式以取得結構化資料）
  • 如果您有多個已知 URL： 對每個 URL 呼叫 scrape。如果您特別需要單一大量 API 操作，請在 MCP 之外使用 Firecrawl API 批次端點。
  • 如果您需要在網站上探索 URL： 使用 map
  • 如果您想搜尋網路以取得資訊： 使用 search
  • 如果您有程式設計問題（函式庫、API 契約、錯誤訊息、已知錯誤）：使用 developer search
  • 如果您有法律或法規問題（法規、規章、法典、法院意見或其他美國政府出版品）：使用 Firecrawl Government Index
  • 如果您需要科學論文（生物醫學、生命科學、臨床或 arXiv 文獻）：使用 research tools，其會搜尋論文摘要與全文。搭配 categories: ["research"] 的 search 是另一回事：對一般網路結果套用網站篩選。
  • 如果您需要傳回結構化資料的多來源研究、不知道 URL，或答案橫跨多個網站（實體及其欄位、清單、資料集）：使用 agent
  • 如果您想分析整個網站或區段： 使用 crawl（請設定限制！）
  • 如果您需要互動式瀏覽器自動化（點擊、輸入、導覽）：使用 interact 搭配 URL 以開啟新頁面，或在您已擷取頁面或需要更精細的 scrape 控制時使用 scrape + interact
  • 如果您需要來自已編目提供者（Alexandria）的資料：使用 sources: ["alexandria"] 搜尋、以 find_tools 檢視所選契約，並以 scrape alexandria 執行

快速參考表

工具最適合傳回
scrape單一頁面內容JSON（偏好）或 markdown
interact與 URL 或已擷取頁面互動執行結果 + URL 模式的 scrapeId
map探索網站上的 URLURL[]
crawl多頁擷取（含限制）內部輪詢後的最終 crawl 狀態/資料
parse檔案與託管上傳參照markdown、JSON 或文件輸出
search網路搜尋以取得資訊results[]
find_toolsAlexandria 目錄瀏覽與 URL 查詢提供者、工具契約與 nextTool 導覽
developer針對開發者來源的程式設計問題含段落的 results[]
gov美國主要法律與法規資料含摘要的 results[]
agent多來源研究、未知或眾多網站JSON（結構化資料）
monitor週期性頁面檢查monitor/check 中繼資料與差異
research論文與 GitHub 儲存庫研究研究結果與儲存庫相符項目

格式選擇指南

使用 scrape 時，請選擇正確的格式：

  • JSON 格式（大多數情況建議使用）： 當您需要頁面中的特定資料時使用。根據您需要擷取的內容定義結構描述。這可讓回應保持精簡，並避免內容視窗溢位。
  • Markdown 格式（請謹慎使用）： 僅在您確實需要完整頁面內容時使用，例如閱讀整篇文章以進行摘要，或分析頁面結構。

可用工具

1. Scrape 工具（firecrawl_scrape）

以進階選項從單一 URL 擷取內容。

最適合：

  • 單一頁面內容擷取，當您確切知道哪個頁面包含資訊時。

不建議用於：

  • 從多個頁面擷取內容（對已知 URL 使用重複的 scrape 呼叫，或先使用 map + scrape 探索 URL，或使用 crawl 取得完整頁面內容）
  • 當您不確定哪個頁面包含資訊時（使用 search）

常見錯誤：

  • 將 URL 清單傳遞給單一 scrape 呼叫。在 MCP 中對每個 URL 呼叫一次 scrape。如果您特別需要單一大量 API 操作，請在 MCP 之外使用 Firecrawl API 批次端點。
  • 預設使用 markdown 格式（使用 JSON 格式僅擷取您需要的內容）。

選擇正確的格式：

  • JSON 格式（偏好）： 對大多數使用案例，使用 JSON 格式搭配結構描述，僅擷取所需的特定資料。這可讓回應保持聚焦，並避免內容視窗溢位。
  • Markdown 格式： 僅在任務確實需要完整頁面內容時使用（例如摘要整篇文章、分析頁面結構）。

提示範例：

「從 https://example.com/product. 取得產品詳細資料」

使用範例（JSON 格式 - 偏好）：

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/product",
    "formats": [
      {
        "type": "json",
        "prompt": "Extract the product information",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "price": { "type": "number" },
            "description": { "type": "string" }
          },
          "required": ["name", "price"]
        }
      }
    ]
  }
}

使用範例（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： scrape 為唯讀。它不接受瀏覽器 actions，也無法接受提供者條款。具名的 profile 會載入已儲存的瀏覽器狀態，但不會將變更儲存至其中，而完整端點的 firecrawl_search 也會以相同方式處理 scrapeOptions.profile。若要將瀏覽器狀態儲存至設定檔，請以 firecrawl_interact 開啟頁面（見下文）。組織管理員可在儀表板中接受條款。

傳回：

  • JSON 結構化資料、markdown、branding 設定檔或指定的其他格式。

2. Map 工具（firecrawl_map）

對網站進行對應，以探索網站上所有已建立索引的 URL。

最適合：

  • 在決定要擷取什麼之前探索網站上的 URL
  • 尋找網站的特定區段

不建議用於：

  • 當您已知道需要哪個特定 URL 時（使用 scrape）
  • 當您需要頁面內容時（先對應再使用 scrape）

常見錯誤：

  • 使用 crawl 而非 map 來探索 URL

提示範例：

「列出 example.com 上的所有 URL。」

使用範例：

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

傳回：

  • 在網站上找到的 URL 陣列

3. Search 工具（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 }。每個擷取的結果都會以一次 scrape 計費，因此對大多數問題，請使用摘錄，並僅對您需要的 URL 使用 firecrawl_scrape。

將 highlights 設為 true 以要求與查詢相關的重點，或設為 false 以保留原始搜尋摘要。省略則使用 API 的預設行為。

加入 "sources": ["alexandria"] 以在 data.tools 中進行語意工具探索，可選擇與 web/news/images 混合。查詢為必填。使用 firecrawl_find_tools 進行情境查閱與漸進式揭露；請參閱 Alexandria Tools。

關於科學論文，請參閱 Research 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. Search 意見回饋工具（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。這是一個陣列，包含 agent 預期找到但實際上並未找到的特定內容片段。每個缺少的主題對應一個項目；這些項目會跨團隊彙總，告訴我們接下來該索引什麼。若要獲得有用的結果，請使用 valuableResults，並在每個結果上標記 source/position 配對——結果會分組，且每個群組各自從 1 開始編號，因此兩者都必須提供。請列出每一個有用的結果（未列出的結果會被視為無用），並將 valuableSources 保留給不在回傳結果之中的有用 URL。

每日退款上限（每個團隊、每個 UTC 日，預設 100 點數）。 一旦團隊的 creditsRefundedToday 達到 dailyRefundCap，後續提交仍會記錄回饋，但不再退還點數。回應會設定 dailyCapReached: true。當 agent 看到該旗標時，應在當天剩餘的 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 工具將不會被註冊，因此 agent 無法呼叫它。

使用範例：

{
  "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）
  • 當 token 上限是考量因素時（請使用 map + scrape 以獲得更精確的控制）
  • 當你需要快速取得結果時（爬取可能很慢）

警告： 爬取回應可能非常龐大，並可能超出 token 上限。請限制爬取深度與頁面數量，或使用 map + scrape 以獲得更精確的控制。

常見錯誤：

  • 將 limit 或 maxDiscoveryDepth 設得太高（導致 token 溢出）
  • 對單一頁面使用 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 端點解析本機檔案或託管的上傳參照。

最適合： 需要 markdown 或結構化 JSON 輸出的 PDF、Word 文件、試算表、HTML 檔案及其他文件。託管端點採用兩步驟上傳流程；本機直接讀取檔案需要自架的 FIRECRAWL_API_URL。

不建議用於： 遠端 URL（請使用 scrape）、在單次呼叫中處理多個檔案（請對每個檔案各呼叫一次 parse），或僅限瀏覽器的動作，例如截圖與點擊。

託管端點： 它無法讀取你的檔案系統。請以 filePath 呼叫 firecrawl_parse，以取得短效的上傳指令與 nextToolCall，在本機上傳檔案，然後以回傳的 uploadRef 再次呼叫 firecrawl_parse。上傳步驟需要 Firecrawl 驗證或免金鑰方案。在本機 npx firecrawl-mcp 模式下，直接解析檔案目前需要將 FIRECRAWL_API_URL 指向自架的 Firecrawl API；僅有雲端 API 金鑰的純本機伺服器無法透過此工具讀取並上傳檔案。

使用範例：

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

回傳： 解析後的文件內容，或附有 nextToolCall 的託管上傳指示。

7. 使用 Scrape JSON 取得結構化資料

若要從已知頁面取得結構化資料，請以 formats: ["json"] 對每個 URL 呼叫一次 firecrawl_scrape。將擷取提示與 JSON schema 放入 jsonOptions。

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/product",
    "formats": ["json"],
    "jsonOptions": {
      "prompt": "Extract the product name, price, and description.",
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "price": { "type": "number" },
          "description": { "type": "string" }
        },
        "required": ["name", "price"]
      }
    }
  }
}

當 URL 未知，或資料橫跨多個網站時，請使用 firecrawl_agent 進行多來源研究。

8. Agent 工具（firecrawl_agent）

自主網路研究 agent，當你不知道 URL，或答案橫跨多個網站時，會回傳結構化資料。描述你需要的欄位，可選擇性地傳入 JSON schema 與種子 URL，agent 便會搜尋、瀏覽、讀取頁面，並回傳跨來源彙整的 JSON。適用於實體及其欄位、清單與資料集，以及需要瀏覽才能取得資料的頁面。若只有一個已知 URL，請改用 firecrawl_scrape 搭配 JSON 格式。

運作方式：

agent 會執行網路搜尋、追蹤連結、讀取頁面，並自主蒐集資料。此流程以非同步方式執行——它會立即回傳任務 ID，你則輪詢 firecrawl_agent_status 以檢查何時完成並取得結果。

非同步工作流程：

  1. 以你的提示/schema 呼叫 firecrawl_agent → 回傳任務 ID
  2. 在 agent 研究期間進行其他工作（複雜查詢可能需要數分鐘）
  3. 以任務 ID 輪詢 firecrawl_agent_status 以檢查進度
  4. 當狀態為「completed」時，回應會包含擷取到的資料

最適合：

  • 你不知道確切 URL 的複雜研究任務
  • 多來源資料蒐集
  • 尋找散落於網路各處的資訊
  • 你可以在等待結果期間進行其他工作的任務

不建議用於：

  • 你知道 URL 的簡單單頁擷取（請使用 scrape 搭配 JSON 格式——更快且更便宜）

參數：

  • prompt：以自然語言描述你想要的資料（必填，最多 10,000 個字元）
  • urls：選用的 URL 陣列，用於讓 agent 聚焦於特定頁面
  • schema：選用的 JSON schema，用於結構化輸出
  • effort：選用。agent 任務的 "low"、"medium" 或 "high" 推理預算。
  • maxCredits：選用的正整數。此次執行的點數花費上限。省略時 API 預設為 2,500，並將免費請求上限設為 2,500。
  • strictConstrainToURLs：選用的布林值。若為 true，agent 只會造訪 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 個供應商 slug）、maxCalls（1 到 30）、requireApproval（付費呼叫會以 pendingApproval 結束該輪；需在同一次呼叫中設定 mode: "chat"，即使是後續追問也一樣）
    • onTermsRequired：當 agent 會使用的 Alexandria 供應商需要你的團隊尚未接受的資料條款時該怎麼做。受閘門限制的供應商在任何模式下都不會被呼叫。在後續追問時省略，會保留上一輪的值。
      • "skip"（預設）：僅以已接受的供應商作答。狀態結果上的 exchange.skippedProviders 會列出原本有幫助但受閘門限制的供應商。
      • "ask"：同上，另附條款 pendingApproval 與 exchange.requiresAction，包含核准 ID 與供應商要求。使用 terms/show 閱讀條款；由組織管理員在 Firecrawl 儀表板中接受。
    • approve：{ approvalId, callIds?, always? } 表示對上一輪結束時提出的 pendingApproval 回答同意。callIds 與 always 僅適用於付費呼叫的核准。
    • decline：{ approvalId } 表示回答不同意。拒絕條款提案會讓這些供應商在該執行緒剩餘部分中被排除。
    • approve 與 decline 需要 threadId，且兩者只能傳送其中一個。

供應商條款（詢問模式）： 沒有自動接受模式。當某一輪以條款提案結束時，狀態結果會帶有 pendingApproval（kind: "terms"）與 exchange.requiresAction，其中包含 approvalId 與供應商要求。該 API 承載內容中的任何 terms/accept 描述元都無法透過 MCP 取得。若要使用該供應商：

  1. 向使用者顯示條款（terms/show 至 firecrawl_scrape，搭配 alexandria）。
  2. 指示組織管理員在供應商的 URL 或資料來源設定中接受條款。提出資料請求並不代表同意。
  3. 等待管理員在儀表板中確認接受。
  4. 接續同一執行緒：以相同的 threadId 與 exchange.approve: { "approvalId": "..." } 呼叫 firecrawl_agent。這會恢復研究，並不會接受條款。

若使用者表示不同意，請改以相同的 threadId 與 exchange.decline: { "approvalId": "..." } 呼叫 firecrawl_agent。

提示範例：

「找出 Firecrawl 的創辦人及其背景」

使用範例（啟動 agent，然後輪詢結果）：

{
  "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——agent 聚焦於特定頁面）：

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

使用範例（在同一執行緒上後續追問）：

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Only keep the startups based in Europe",
    "threadId": "0199a1b2-0000-7000-8000-000000000031"
  }
}

使用範例（在管理員確認儀表板接受後接續執行緒）：

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "The admin confirmed acceptance of the Apollo terms in the dashboard. Continue.",
    "threadId": "0199a1b2-0000-7000-8000-000000000031",
    "exchange": { "approve": { "approvalId": "0199a1b2-0000-7000-8000-000000000033" } }
  }
}

回傳：

  • 用於檢查狀態的任務 ID，以及 threadId 與 threadTurn。使用 firecrawl_agent_status 輪詢結果。

9. 檢查 Agent 狀態（firecrawl_agent_status）

檢查 agent 任務的狀態，並在完成時取得結果。用於在啟動 agent 後輪詢結果。

輪詢模式： 複雜查詢的 agent 研究可能需要數分鐘。請定期輪詢此端點（例如每 10-30 秒一次），直到狀態為「completed」或「failed」。

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

可能的狀態：

  • processing：agent 仍在研究——請稍後再檢查
  • completed：研究完成——回應包含擷取到的資料
  • failed：發生錯誤

10. 互動工具（firecrawl_interact）

與全新的 URL 互動，或與已由 firecrawl_scrape 開啟的頁面互動。

最適合： 在無需還原已棄用的瀏覽器工具的情況下，對動態頁面進行點擊、輸入、瀏覽及擷取狀態。

使用選項：

  • 傳入 url，在單次 MCP 呼叫中擷取並開啟頁面以供互動。
  • 傳入 scrapeId，繼續與現有已擷取的頁面互動。
  • 若要將瀏覽器狀態（cookies、localStorage）儲存至具名設定檔，請傳入 url 搭配 scrapeOptions: { "profile": { "name": "my-profile", "saveChanges": true } }。狀態會在 firecrawl_interact_stop 結束工作階段時儲存。
  • 請恰好傳入 url 或 scrapeId 其中之一，再加上 prompt 或 code 其中之一。

使用範例：

{
  "name": "firecrawl_interact",
  "arguments": {
    "url": "https://example.com",
    "prompt": "Click the pricing link and summarize the visible plans"
  }
}

回傳： 互動結果，以及在 URL 模式下用於後續追蹤或清理的衍生 scrapeId。

11. 停止互動工具（firecrawl_interact_stop）

當你完成互動後，停止已擷取頁面的互動工作階段。

{
  "name": "firecrawl_interact_stop",
  "arguments": {
    "scrapeId": "scrape-id-here"
  }
}

12. 研究工具（firecrawl_research_*）

透過研究 MCP 工具搜尋並檢視論文與 GitHub 儲存庫。

涵蓋範圍： 生物醫學、生命科學與臨床文獻（PubMed、bioRxiv、medRxiv）以及 arXiv 和其他科學來源的論文摘要與全文。

可用的研究工具：

  • firecrawl_research_search_papers：以自然語言查詢搜尋論文中介資料與摘要，可選用作者、類別與日期篩選條件。
  • firecrawl_research_inspect_paper：擷取單一論文 ID（arXiv、PMC、PMID 或 DOI）的標準中介資料。
  • firecrawl_research_related_papers：從一或多篇錨定論文出發，透過引用圖譜向外擴展。
  • firecrawl_research_read_paper：讀取特定論文的全文段落。

最適合： 文獻回顧、論文查詢與儲存庫探索工作流程，適合代理需要專注的研究介面而非一般網頁搜尋的情況。

firecrawl_search 搭配 categories: ["research"] 是另一個不同的介面：它會將一般網頁結果篩選為研究相關網站，並傳回頁面摘要，而非論文記錄。當問題是關於文獻本身時，請使用這些工具，並以同一問題的數種不同表述分別傳入，因為它們會呈現與單一查詢不同的論文。

13. 監控工具（firecrawl_monitor_*）

建立並管理週期性頁面監控。監控會依排程執行擷取或爬取，將每次結果與上次保留的快照進行差異比對，並可透過 webhook 或電子郵件通知。

最適合：

  • 長期觀察單一頁面或少數頁面
  • 使用白話目標對有意義的變更發出警示
  • 追蹤檢查歷史與頁面層級的差異

建議的建立模式：

使用 page 或 pages 加上 goal。MCP 伺服器會以 30 分鐘的排程建立監控請求，API 則會自動啟用有意義變更的判定。

當設定 goal 時，有意義變更的判定會自動執行。頁面 webhook 會在 monitor.page 事件中提供 isMeaningful 與 judgment。

請將目標寫成簡潔的 2 至 3 句監控指示。說明應觸發警示的條件，保留使用者提供的任何範圍，並僅在請求中明顯可見時加入意圖特定的排除項目。空白、僅格式變更、請求 ID、追蹤參數、一般中介資料與無關的頁面外框等一般雜訊已由判定器處理，因此不要在每個目標中重複列出。若使用者表達模糊，請保持目標寬泛；若他們要求廣泛監控或「任何變更」，請保留該意圖。若使用者表示不在意某事物，請明確納入。

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "page": "https://example.com/pricing",
    "goal": "Alert when pricing, packaging, or launch messaging changes."
  }
}

多個頁面搭配 webhook：

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "pages": ["https://example.com/pricing", "https://example.com/changelog"],
    "goal": "Alert when pricing, packaging, or launch messaging changes.",
    "webhookUrl": "https://example.com/webhooks/firecrawl"
  }
}

進階建立請求：

當你需要爬取目標、JSON 變更追蹤、自訂保留期或明確控制 judgeEnabled 時，請傳入 body。

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "body": {
      "name": "Docs monitor",
      "schedule": { "text": "hourly", "timezone": "UTC" },
      "goal": "Alert when docs pages add, remove, or materially change API behavior.",
      "targets": [{ "type": "crawl", "url": "https://example.com/docs" }]
    }
  }
}

其他監控工具：

  • firecrawl_monitor_list：列出監控。
  • firecrawl_monitor_get：取得單一監控。
  • firecrawl_monitor_update：更新欄位，包括 goal、judgeEnabled、webhook 與 notification。
  • firecrawl_monitor_run：立即觸發檢查。
  • firecrawl_monitor_delete：刪除監控（具破壞性；僅在使用者有意移除時呼叫）。
  • firecrawl_monitor_checks：列出檢查，可依狀態篩選。
  • firecrawl_monitor_check：取得頁面層級結果，包括 diff、snapshot、judgment.meaningful 與 judgment.meaningfulChanges。

14. 開發者搜尋工具（firecrawl_developer_search）

搜尋專為程式設計代理建立的索引。該索引涵蓋 GitHub issue、已合併的 pull request、儲存庫 README 與程式碼文件。

最適合： 程式設計問題：程式碼行為、函式庫或框架、API 契約、錯誤訊息或已知錯誤。

引數：

{
  "name": "firecrawl_developer_search",
  "arguments": {
    "query": "how do I configure retries",
    "k": 10,
    "skills": "only"
  }
}
  • query（必填）：開發者問題或搜尋詞。
  • k：排序結果的數量。預設為 10，上限為 100。
  • skills：設為 "only" 以僅搜尋代理技能檔案。

傳回： 排序後的結果。每筆結果包含 ID、來源類型（issue、pull_request、readme 或 doc）、URL、標題，以及以 markdown 呈現的相符段落。

firecrawl_search 搭配 categories: ["developer"] 會在網頁結果旁搜尋相同索引。當你想要相符段落、skills 篩選，或回應中不含網頁結果時，請改用此工具。僅搜尋端點會同時提供這兩種工具，該處也適用相同的選擇。

14b. 政府索引搜尋工具（firecrawl_gov_search）

搜尋來自美國聯邦、州與地方政府來源的主要法律與法規資料：法規、規章、法典、法院意見書與其他政府出版品。

最適合： 需要具拘束力文本或官方政府來源的法律或法規問題。

引數：

{
  "name": "firecrawl_gov_search",
  "arguments": {
    "query": "excessive force claims against police officers",
    "k": 10,
    "courtType": "federal-appellate",
    "cites": "42 U.S.C. § 1983"
  }
}
  • query（必填）：法律或法規問題或搜尋詞。
  • k：排序結果的數量。預設為 10，上限為 100。
  • jurisdiction：僅保留單一司法管轄區的頁面："us" 代表聯邦，或 "us-" 加上兩個字母的州或領地代碼，例如 "us-ca" 或 "us-dc"。
  • court：僅保留標記為特定法院的頁面，依 CourtListener 法院 ID，例如 "scotus"、"ca9" 或 "nysd"。
  • courtType：僅保留來自單一法院類型的頁面：federal-supreme、federal-appellate、federal-district、federal-bankruptcy、federal-special、military、state-supreme、state-appellate、state-trial、state-special 或 state-attorney-general。
  • cites：僅保留引用某一法律或案例的頁面，以印刷引用格式如 "42 U.S.C. § 1983" 或 "5 U.S. 137"，或引用 ID 如 "us:usc:42:1983" 表示。
  • domain：僅保留來自單一網站的頁面，例如 "irs.gov"。

篩選條件為選用且可組合：結果必須符合所有已設定的篩選條件。篩選只會保留索引已標記的頁面，因此經過篩選的搜尋可能漏掉相關頁面，而沒有結果並不代表不存在。法院標記在聯邦法院與判例法集合中最為完整。

傳回： 排序後的結果。每筆結果包含位置、標題、URL 與相符摘要。僅搜尋端點也會提供此工具。

firecrawl_search 搭配 categories: ["gov"] 會搜尋相同來源，並以 data.web 搭配 category: "gov" 傳回命中結果。gov 類別不接受這些篩選條件，且無法與其他類別合併使用。

15. Alexandria 工具

Firecrawl Alexandria 是可透過 Firecrawl API 存取的資料提供者目錄，需在具備 Alexandria 存取權的團隊中使用 Firecrawl API 金鑰。無金鑰工作階段（託管或本機）會取得 Alexandria requires an API key on a team with Alexandria access；託管的無金鑰工作階段不會列出 Alexandria 探索工具。

語意探索（firecrawl_search）：

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "podcast conversations about AI agents",
    "sources": ["web", "alexandria"],
    "domainTools": true,
    "limit": 2
  }
}

data.tools 預設為精簡建議，包含提供者、能力與描述。設定 toolDetail: "summary" 可取得中介資料與導覽，或設定 toolDetail: "full" 可取得包含輸入、回應欄位與範例的契約。domainTools: true 會在同一陣列中為查詢提及與結果 URL 加入情境相符項目。檢查 warning 以了解無法使用探索的情況。搜尋需要查詢詞，且不接受目錄遍歷篩選條件。此探索功能在完整與僅搜尋的 MCP 介面上皆可使用。

漸進式揭露（firecrawl_find_tools）：

{
  "name": "firecrawl_find_tools",
  "arguments": {
    "providers": ["particle"],
    "capabilities": ["podcasts/episodes/search"],
    "expand": ["options", "response", "examples"],
    "limit": 2
  }
}

先不帶引數以取得類別，然後逐步縮小目錄範圍：

引數結果
{}類別與簡短描述
{"categories":["podcasts"]}該類別中的提供者
{"categories":["podcasts"],"providers":["particle"]}精簡的工具名稱與描述
{"providers":["particle"],"capabilities":["podcasts/episodes/search"]}所選項目的完整輸入、限制、回應與範例

不需要群組跳轉。明確的 level 支援 categories、providers、groups 或 tools；明確的 expand 會選取契約區段。expand: [] 即使在選取能力時也能讓結果保持精簡。若需要廣泛的完整契約，請明確要求 level: "tools" 與 expand: ["options", "response", "examples"]。URL 可提供情境探索而不需擷取頁面。除非設定 includeCosts: true，否則工具結果會省略各能力的點數價格；後續的 nextTool 引數會保留該設定。

結果位於 data.alexandria[0].data。若要跟隨項目的 nextTool，請以其 arguments 呼叫其 name；頁面的 nextTool 會推進分頁。既有的 next 物件仍可透過 firecrawl_scrape 作為 Alexandria 探索呼叫使用。探索不消耗點數，且絕不會執行提供者工具。執行前請先閱讀所選的完整契約。

這些控制項需要對應的 Alexandria API 部署。

執行（firecrawl_scrape 搭配 alexandria）： 傳入 alexandria 而非 url（兩者擇一，且僅能一個；也可提供 requestId 與 timeout）。可接受單一呼叫或最多十個呼叫的陣列。

{
  "name": "firecrawl_scrape",
  "arguments": {
    "alexandria": [
      {
        "provider": "fred",
        "capability": "series/observations",
        "options": { "series_id": "CPIAUCSL" }
      }
    ]
  }
}

傳回： { success, scrape_id, requestId, data: { alexandria: [...], creditsCost } }。每個項目不是結果（provider、capability、data、records、upstreamStatus），就是帶有 code 的 error；批次不會因提供者錯誤而整體失敗，data.creditsCost 是該請求收取的總點數。Alexandria 錯誤主體（無 Alexandria 存取權的 403，以及 402/409 計費狀態）會以其 code 在頻內轉送。

執行會產生一個 x-request-id，並在成功或失敗時傳回。請以該 requestId 重試完全相同的承載內容；在結果不確定後不要建立新的 ID。API 會檢查可用點數。

若團隊尚未接受某 Alexandria 提供者的條款，該提供者會在執行任何內容前失敗，並傳回 HTTP 403 與以下主體：

{
  "success": false,
  "code": "THIRD_PARTY_DATA_TERMS_REQUIRED",
  "error": "An organization admin must accept the benzinga provider's terms (version 2026-09-12-placeholder) before this request can run. Accept them at https://www.firecrawl.dev/app/alexandria/benzinga",
  "requiresAction": {
    "type": "accept_terms",
    "terms": "benzinga",
    "version": "2026-09-12-placeholder",
    "url": "https://www.firecrawl.dev/app/alexandria/benzinga"
  }
}

工具結果會將其轉送為錯誤，其中 structuredContent 帶有 code、status: 403、requestId、原樣不變的 requiresAction 物件，以及 next_actions（先 human_action_required 再 retry_same_request）。接受條款屬於法律行為，因此須由組織管理員在 Firecrawl 儀表板中接受，而非透過 MCP。請使用傳回的 nextTool 呼叫，透過 firecrawl_scrape 搭配 alexandria: [{provider: "firecrawl", capability: "terms/show", options: {provider: "<provider>"}}] 閱讀協議（與提供者執行分開傳送），並呈現給使用者。接著由組織管理員在 requiresAction.url，或於 https://www.firecrawl.dev/app/settings?tab=data-sources. 接受。firecrawl_scrape 會拒絕其他所有 terms/* 能力，因此不會變更帳戶。請求資料並不構成同意，也不會發生自動接受或不確定的重試。被封鎖的擷取不會收取點數。管理員確認接受後，請以完全相同的承載內容與 requestId 再次呼叫同一工具。

16. 點數用量工具

此工具需要已驗證的 Firecrawl 帳戶，且為唯讀。

  • firecrawl_credit_usage 預設為 { "view": "current" }，並回傳 remainingCredits、planCredits、billingPeriodStart 與 billingPeriodEnd。當團隊有加購額度或贈與額度時，剩餘額度可能超過方案額度。
  • 對於包含 startDate、endDate 與 creditsUsed 的日曆月期間，請傳入 { "view": "historical" }。傳入 { "byApiKey": true } 也會選取歷史檢視，並依 API 金鑰拆分期間；此時每一列會包含 apiKey。改為傳入 { "byEndpoint": true } 則會依使用額度的端點（scrape、search、crawl、map、agent 等）拆分期間；此時每一列會包含 endpoint。傳入 { "bin": "day" } 可改為每個 UTC 日一個期間，而非每個日曆月一個期間。請勿將 byApiKey 與 byEndpoint 合併使用，也不要將其中任一項與 { "view": "current" } 合併使用。最新期間的 endDate 可能為 null。若 Firecrawl API 尚未提供端點拆分或每日期間，結果會帶有 notice 與每月數據。

程式化使用（不穩定）

此套件也提供函式庫進入點，可將伺服器嵌入另一個執行環境。它不穩定：API、其選項與型別可能在任何版本中變更，包括次要版本與修補版本，因此請固定使用確切版本。

npm install --save-exact firecrawl-mcp zod

此範例使用 zod 定義工具參數，因此嵌入專案會將其安裝為自身的相依套件。

import { createFirecrawlMcpServer } from 'firecrawl-mcp/server';
import { z } from 'zod';

const server = createFirecrawlMcpServer({
  transport: 'httpStream',
  apiKey: process.env.FIRECRAWL_API_KEY,
  unstable_hooks: {
    registerExtraTools: (registrar) => {
      registrar.addTool({
        name: 'my_tool',
        description: 'An extra tool served next to the Firecrawl tools.',
        parameters: z.object({ text: z.string() }),
        execute: async ({ text }) => text,
      });
    },
  },
});

await server.start({
  transportType: 'httpStream',
  httpStream: { port: 3000, host: '127.0.0.1', endpoint: '/mcp', stateless: true },
});
// MCP endpoint: http://127.0.0.1:3000/mcp

請明確設定 host。若未設定，伺服器會監聽 localhost，而 Node 會將其繫結至單一位址（通常僅為 ::1），因此對 127.0.0.1 的請求會被拒絕。只有在具備網路存取控制或 unstable_hooks.authenticate 檢查的情況下，才使用 0.0.0.0 或 :: 接受來自其他機器的連線：若無此類控制，任何能連上該連接埠的呼叫者都會以設定的 apiKey 提供服務。

除非有要求，否則此函式庫不會檢查 Host 或 Origin，且其 CORS 標頭允許任何來源。若伺服器可從同一台機器上的瀏覽器存取，應傳入 httpStream.allowedHosts（例如 ['localhost', '127.0.0.1', '[::1]']）：此時若請求的 Host 或 Origin 標頭指向其他主機，便會得到 403（健康檢查路徑上的 GET 與 HEAD 除外），且 CORS 標頭會回傳允許的來源。命令列會在本地 HTTP 模式下設定此清單。

選項對應 CLI 的環境變數：apiUrl、apiKey、transport、logging、safeMode、fileAccess（local 或 upload）、requireCredential、searchFeedback 與 endpointFeedback。unstable_hooks 接受：

Hook用途
authenticate(request)為請求解析工作階段；擲出 Response 以拒絕請求。
wrapTool(tool)裝飾每個已註冊的工具。
onToolResult(event)觀察每次工具呼叫的開始與結果。
instructions伺服器指示，或從預設值中選擇的函式。
registerExtraTools(registrar, context)在內建工具之後新增工具。
outboundRequest(session)每次 Firecrawl API 請求的憑證與額外標頭。
beforeKeylessRequest(session, origin)擲出例外以拒絕無金鑰的請求。
toolFilter(name)將內建工具排除於執行個體之外。
configureHttp(app)新增 HTTP 路由。
oauth.protectedResource提供 OAuth 受保護資源中繼資料。

此伺服器建構於官方 MCP TypeScript SDK（@modelcontextprotocol/server）之上。請使用從 firecrawl-mcp/server 匯出的型別（Session、ToolDefinition、ToolRegistrar、FirecrawlMcpServerHooks 等），而非 SDK 自身的型別。

此進入點也匯出內建工具所使用的輔助函式，例如 recoveryPayload、normalizeHeader、requestOrigin、isRuntimeUserAgent、initializeClientSlug、searchToolBaseFields、searchOutputSchema 與 structuredCompact，讓額外的工具與 hook 能與內建行為一致。它們同樣不穩定。

記錄系統

此伺服器包含完整的記錄功能：

  • 操作狀態與進度
  • 效能指標
  • 速率限制追蹤
  • 錯誤狀況

記錄訊息範例：

[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[ERROR] Rate limit exceeded

錯誤處理

此伺服器提供穩健的錯誤處理：

  • 將 API 速率限制錯誤呈現給 MCP 用戶端
  • 詳細的錯誤訊息
  • 網路韌性

錯誤回應範例：

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded"
    }
  ],
  "isError": true
}

開發

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

貢獻

  1. 分叉此儲存庫
  2. 建立您的功能分支
  3. 執行測試：npm test
  4. 提交拉取請求

感謝貢獻者

感謝 @vrknetha、@cawstudios 的初始實作！

感謝 MCP.so 與 Klavis AI 提供託管，以及 @gstarwd、@xiangkaiz 與 @zihaolin96 整合我們的伺服器。

授權

MIT 授權 - 詳情請參閱 LICENSE 檔案

結構化資料與大型結果

已驗證的搜尋預設會使用網頁結果、語意 Alexandria 工具與網域比對。請從實際問題開始。使用 firecrawl_find_tools 進行直接的語意工具查詢、選定的契約，或漸進式瀏覽：類別 → 提供者 → 精簡工具 → 選定契約。透過 firecrawl_scrape 執行工具；一般的 URL 擷取與搜尋絕不會自動執行提供者工具。

對於選定的契約，優先使用 expand: ["options", "response"]，且僅在輸入結構不清楚時才請求範例。一併檢視相關能力，並重複使用回傳的契約。

對於可能很大的工作流程結果，請在執行前提供並保留頂層的 requestId。即使用戶端拒絕回應，該 ID 仍會保留。一般 URL 擷取則改用回傳的擷取 ID。

對於大型的保留工作流程或一般擷取結果，請以下列方式呼叫 firecrawl_scrape：

{
  "alexandria": {
    "provider": "firecrawl",
    "capability": "bash",
    "options": {
      "requestId": "<source-request-or-scrape-id>",
      "command": "ls -lh"
    }
  }
}

在 data.alexandria[0].data 中讀取 stdout、stderr、exitCode 與 workspaceId。接著使用 options: {workspaceId, command} 搭配 jq 檢視 response.json，或針對一般擷取使用有界文字命令搭配 document.md 檢視。請保持輸出精簡。來源載入必須是獨立呼叫；其巢狀來源 ID 與頂層執行請求 ID 不同。工作區在閒置五分鐘後過期，且並非每個結果都會保留（包括 ZDR 與 API 提供者工作流程承載資料）。不支援搜尋 ID。

對於工作流程來源，response.json 會保留 API 封裝：先選取 .data.alexandria[].data，然後在非空時選取所選契約的 response.key。當結構已知時，請在單一 Bash 命令中合併相關計數與投影，而非反覆檢視鍵。

超過 20,000 個估計 token（序列化 UTF-8 位元組除以四）的成功 Alexandria 執行回應，會在遠端 Bash 確認完整批次可存取後回傳一個小型交接。請依照 nextTool 檢視保留的資料。這會增加一次 Bash 呼叫，並啟動一個閒置 TTL 為五分鐘的工作區。完整承載資料會保留。若確認失敗，原始回應會保持內嵌。搜尋、一般 URL 擷取、錯誤回應與 Firecrawl 公用程式呼叫皆不變。此傳遞預算不會衡量用戶端剩餘的上下文；也不會新增程序本機的結果快取。當有本機檔案系統工具可用時，儲存 CLI 輸出並讀取選定區段是另一個選項。

CLI 探索順序對應至下列 MCP 呼叫：

意圖工具引數
網頁 + 語意 + 網域工具firecrawl_search{"query":"<user question>"}
僅語意工具firecrawl_search{"query":"<user question>","sources":["alexandria"]}
類別firecrawl_find_tools{}
類別中的提供者firecrawl_find_tools{"categories":["<category-id>"]}
精簡提供者工具firecrawl_find_tools{"providers":["<provider-id>"]}
選定契約firecrawl_find_tools{"providers":["<provider-id>"],"capabilities":["<capability-id>"]}
執行firecrawl_scrape{"alexandria":{"provider":"<provider-id>","capability":"<capability-id>","options":{"<required-field>":"<value>"}}}

尋找工具與執行在完整介面與搜尋介面上皆可使用。若搜尋結果中存在完整的契約，請重複使用，而非再進行一次探索呼叫。僅在需要更多結果時，才依照回傳的 nextTool 導覽。

Alexandria 工作階段回饋

現有的 firecrawl_feedback 工具接受 endpoint: "alexandria"：

{
  "endpoint": "alexandria",
  "rating": "partial",
  "requestedWebsite": {
    "url": "https://example.com",
    "requestedFunctionality": "Find records and download their attachments"
  },
  "objective": "Compare contract requirements across agencies before bidding",
  "rationale": "Found summaries but could not retrieve attachments"
}

選用的 objective 是工作階段的底層目標：代理或其使用者最終試圖達成的事，而不只是 requestedWebsite 中的單一網站。

這會使用已驗證的 POST /v2/feedback，且不帶作業 ID。它必須在團隊最近一次 Alexandria 搜尋、探索或執行後的 20 分鐘內送達；較晚的回饋會以 FEEDBACK_WINDOW_EXPIRED 拒絕。符合資格的回饋可退還 1 點額度，但受每日上限限制：每個網站 10 點額度，每個團隊 100 點額度（UTC 日）。超過任一上限後，回饋仍會記錄但不退款，且回應會設定 websiteCapReached 或 dailyCapReached。選用的 providerFeedback 與 capabilityFeedback 陣列描述涵蓋範圍缺口與執行問題；工具結構描述會列出支援的問題值。new_capability_request 需要 requestedFunctionality；missing_capability（提供者存在但缺少該能力）則不需要。現有的回饋退出與驗證控制仍適用。

符合資格的 Alexandria 執行與探索結果會包含 feedbackTool 指標，其中帶有工具名稱與引數骨架。對於 Firecrawl 內部呼叫（例如 bash），以及當 firecrawl_feedback 未註冊時（FIRECRAWL_NO_ENDPOINT_FEEDBACK 或無金鑰啟動），則會省略此指標。