Firecrawl

Máy chủ Firecrawl MCP

Máy chủ Giao thức Ngữ cảnh Mô hình (MCP) mang Firecrawl đến các tác nhân AI tương thích MCP — tìm kiếm, thu thập và tương tác với web trực tiếp để có ngữ cảnh sạch sẽ, sẵn sàng cho tác nhân.

Xin cảm ơn @vrknetha, @knacklabs vì đã triển khai ban đầu!

Tính năng

• Tìm kiếm web và lấy nội dung toàn trang
• Thu thập bất kỳ URL nào thành dữ liệu có cấu trúc, sạch sẽ
• Tương tác với các trang — nhấp, điều hướng và vận hành
• Nghiên cứu chuyên sâu với tác nhân tự động
• Tự động thử lại và giới hạn tốc độ
• Hỗ trợ đám mây và tự lưu trữ
• Hỗ trợ SSE

Hãy dùng thử Máy chủ MCP của chúng tôi trên sân chơi MCP.so hoặc trên Klavis AI.

Cài đặt

MCP được lưu trữ (bậc miễn phí không cần khóa)

Kết nối với máy chủ được lưu trữ từ xa mà không cần thiết lập:

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

Ở bậc miễn phí không cần khóa, scrape, search và interact hoạt động mà không cần khóa API (bị giới hạn tốc độ). Các công cụ khác như crawl, map, agent và extract vẫn cần khóa.

Ưu tiên sử dụng khóa API hoặc OAuth bất cứ khi nào con người có thể đăng ký. Nó mở khóa bộ công cụ đầy đủ và giới hạn cao hơn. Với khóa, hãy sử dụng:

https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/mcp

Xem tài liệu máy chủ MCP và hướng dẫn giới thiệu tác nhân để biết chi tiết thiết lập.

Điểm cuối chỉ tìm kiếm

Một bề mặt chỉ đọc, chỉ tìm kiếm cũng được lưu trữ tại:

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

Nó hiển thị một bộ cố định gồm sáu công cụ chỉ đọc: firecrawl_search và năm công cụ firecrawl_research_*. Nó không thực hiện tìm nạp nội dung trang và có danh tính OAuth riêng; điểm cuối đầy đủ ở trên không thay đổi. Xem docs/search-profile.md để biết hợp đồng đầy đủ.

Chạy với npx

env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp

Cài đặt thủ công

npm install -g firecrawl-mcp

Chạy trên Cursor

Cấu hình Cursor 🖥️ Lưu ý: Yêu cầu Cursor phiên bản 0.45.6+ Để biết hướng dẫn cấu hình cập nhật nhất, vui lòng tham khảo tài liệu Cursor chính thức về cấu hình máy chủ MCP: Hướng dẫn cấu hình máy chủ MCP trong Cursor

Để cấu hình Firecrawl MCP trong Cursor v0.48.6

1. Mở Cài đặt Cursor
2. Đi tới Tính năng > Máy chủ MCP
3. Nhấp "+ Thêm máy chủ MCP toàn cục mới"
4. Nhập mã sau:

   {
     "mcpServers": {
       "firecrawl-mcp": {
         "command": "npx",
         "args": ["-y", "firecrawl-mcp"],
         "env": {
           "FIRECRAWL_API_KEY": "YOUR-API-KEY"
         }
       }
     }
   }
   

Để cấu hình Firecrawl MCP trong Cursor v0.45.6

1. Mở Cài đặt Cursor
2. Đi tới Tính năng > Máy chủ MCP
3. Nhấp "+ Thêm máy chủ MCP mới"
4. Nhập thông tin sau:
   • Tên: "firecrawl-mcp" (hoặc tên bạn muốn)
   • Loại: "command"
   • Lệnh: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

Nếu bạn đang sử dụng Windows và gặp sự cố, hãy thử cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"

Thay thế your-api-key bằng khóa API Firecrawl của bạn. Nếu bạn chưa có, bạn có thể tạo tài khoản và lấy nó từ https://www.firecrawl.dev/app/api-keys

Sau khi thêm, hãy làm mới danh sách máy chủ MCP để thấy các công cụ mới. Composer Agent sẽ tự động sử dụng Firecrawl MCP khi thích hợp, nhưng bạn có thể yêu cầu rõ ràng bằng cách mô tả nhu cầu thu thập web của mình. Truy cập Composer qua Command+L (Mac), chọn "Agent" bên cạnh nút gửi và nhập truy vấn của bạn.

Chạy trên Windsurf

Thêm điều này vào ./codeium/windsurf/model_config.json của bạn:

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

Chạy với Chế độ cục bộ HTTP có thể truyền phát

Để chạy máy chủ sử dụng HTTP có thể truyền phát cục bộ thay vì truyền tải stdio mặc định:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp

Sử dụng url: http://localhost:3000/mcp

Cài đặt qua Smithery (Cũ)

Để cài đặt Firecrawl cho Claude Desktop tự động qua Smithery:

npx -y @smithery/cli install @mendableai/mcp-server-firecrawl --client claude

Chạy trên VS Code

Để cài đặt một cú nhấp chuột, hãy nhấp vào một trong các nút cài đặt bên dưới...

Để cài đặt thủ công, hãy thêm khối JSON sau vào tệp Cài đặt Người dùng (JSON) của bạn trong VS Code. Bạn có thể thực hiện việc này bằng cách nhấn Ctrl + Shift + P và nhậ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}"
        }
      }
    }
  }
}

Tùy chọn, bạn có thể thêm nó vào tệp có tên .vscode/mcp.json trong không gian làm việc của bạn. Điều này sẽ cho phép bạn chia sẻ cấu hình với người khác:

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

Cấu hình

Biến môi trường

Bắt buộc cho API đám mây

• FIRECRAWL_API_KEY: Khóa API Firecrawl của bạn
  • Bắt buộc khi sử dụng API đám mây (mặc định)
  • Tùy chọn khi sử dụng phiên bản tự lưu trữ với FIRECRAWL_API_URL
• FIRECRAWL_API_URL (Tùy chọn): Điểm cuối API tùy chỉnh cho các phiên bản tự lưu trữ
  • Ví dụ: https://firecrawl.your-domain.com
  • Nếu không được cung cấp, API đám mây sẽ được sử dụng (yêu cầu khóa API)

MCP OAuth (Mã thông báo truy cập Bearer)

Firecrawl được lưu trữ có thể cấp mã thông báo truy cập OAuth (fco_…) thông qua máy chủ ủy quyền trên firecrawl.dev. Máy chủ MCP này chuyển tiếp bất kỳ thông tin xác thực nào nó giải quyết được đến API Firecrawl dưới dạng Authorization: Bearer ….

• Truyền tải luồng HTTP (CLOUD_SERVICE=true, HTTP_STREAMABLE_SERVER=true hoặc SSE_LOCAL=true): Các máy khách nên gửi Authorization: Bearer <fco_access_token> trên các yêu cầu MCP. Mã thông báo bearer OAuth được ưu tiên hơn x-firecrawl-api-key / x-api-key khi cả hai đều có mặt.
• stdio: Sử dụng FIRECRAWL_OAUTH_TOKEN cho mã thông báo truy cập tĩnh, hoặc tiếp tục sử dụng FIRECRAWL_API_KEY cho khóa API.

Chỉ sử dụng mã thông báo truy cập (fco_…). Mã thông báo làm mới (fcr_…) phải được trao đổi tại điểm cuối mã thông báo, không được chuyển đến API thu thập/tìm kiếm.

Bề mặt chỉ tìm kiếm (được lưu trữ)

Trong chế độ được lưu trữ (CLOUD_SERVICE=true), một phiên bản trong tiến trình thứ hai phục vụ điểm cuối chỉ tìm kiếm. Dịch vụ đi kèm có một hợp đồng triển khai cố định: nginx định tuyến /v2/mcp-search đến phiên bản trên cổng cục bộ 3001 và định danh tài nguyên được bảo vệ OAuth là https://mcp.firecrawl.dev/v2/mcp-search.

FIRECRAWL_MCP_SEARCH_ENABLED (mặc định true) là công tắc vận hành được hỗ trợ; đặt nó thành false để ngăn phiên bản tìm kiếm khởi động. Tiến trình Node cũng chấp nhận FIRECRAWL_MCP_SEARCH_PORT, FIRECRAWL_MCP_SEARCH_ENDPOINT và FIRECRAWL_MCP_SEARCH_RESOURCE_URL cho các thử nghiệm cô lập. Các ghi đè đó không cấu hình lại các tuyến nginx đi kèm hoặc danh sách cho phép của máy chủ ủy quyền và không được sử dụng độc lập trong triển khai được lưu trữ.

Phiên bản tìm kiếm yêu cầu xác thực cho mọi yêu cầu (bao gồm tools/list) và từ chối các mã thông báo OAuth có đối tượng không khớp với tài nguyên của chính nó.

Ví dụ cấu hình

Đối với việc sử dụng API đám mây:

export FIRECRAWL_API_KEY=your-api-key

Đối với phiên bản tự lưu trữ:

# 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

Sử dụng với Claude Desktop

Thêm điều này vào claude_desktop_config.json của bạn:

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

Cách chọn công cụ

Sử dụng hướng dẫn này để chọn công cụ phù hợp cho nhiệm vụ của bạn:

• Nếu bạn biết chính xác URL mình muốn: sử dụng scrape (với định dạng JSON cho dữ liệu có cấu trúc)
• Nếu bạn có nhiều URL đã biết: gọi scrape cho từng URL. Nếu bạn đặc biệt cần một thao tác API hàng loạt, hãy sử dụng điểm cuối hàng loạt của API Firecrawl bên ngoài MCP.
• Nếu bạn cần khám phá URL trên một trang web: sử dụng map
• Nếu bạn muốn tìm kiếm thông tin trên web: sử dụng search
• Nếu bạn cần nghiên cứu phức tạp trên nhiều nguồn không xác định: sử dụng agent
• Nếu bạn muốn phân tích toàn bộ trang web hoặc một phần: sử dụng crawl (có giới hạn!)
• Nếu bạn cần tự động hóa trình duyệt tương tác (nhấp, nhập, điều hướng): sử dụng interact với một URL cho trang mới, hoặc scrape + interact khi bạn đã thu thập trang hoặc cần kiểm soát thu thập chặt chẽ hơn

Bảng tham khảo nhanh

Công cụ	Tốt nhất cho	Trả về
scrape	Nội dung trang đơn	JSON (ưu tiên) hoặc markdown
interact	Tương tác với một URL hoặc trang đã thu thập	Kết quả thực thi + scrapeId cho chế độ URL
map	Khám phá URL trên một trang web	URL[]
crawl	Trích xuất nhiều trang (có giới hạn)	trạng thái/dữ liệu thu thập cuối cùng sau khi thăm dò nội bộ
parse	Tệp và tham chiếu tải lên được lưu trữ	markdown, JSON hoặc đầu ra tài liệu
extract	Trích xuất có cấu trúc từ các URL	Dữ liệu có cấu trúc JSON
search	Tìm kiếm thông tin trên web	results[]
agent	Nghiên cứu đa nguồn phức tạp	JSON (dữ liệu có cấu trúc)
monitor	Kiểm tra trang định kỳ	siêu dữ liệu và khác biệt của monitor/check
research	Nghiên cứu bài báo và kho lưu trữ GitHub	kết quả nghiên cứu và kết quả khớp kho lưu trữ

Hướng dẫn chọn định dạng

Khi sử dụng scrape, hãy chọn định dạng phù hợp:

• Định dạng JSON (khuyến nghị cho hầu hết trường hợp): Sử dụng khi bạn cần dữ liệu cụ thể từ một trang. Xác định lược đồ dựa trên những gì bạn cần trích xuất. Điều này giữ cho phản hồi nhỏ gọn và tránh tràn cửa sổ ngữ cảnh.
• Định dạng Markdown (sử dụng hạn chế): Chỉ khi bạn thực sự cần nội dung toàn trang, chẳng hạn như đọc toàn bộ bài viết để tóm tắt hoặc phân tích cấu trúc trang.

Công cụ có sẵn

1. Công cụ Scrape (firecrawl_scrape)

Thu thập nội dung từ một URL duy nhất với các tùy chọn nâng cao.

Tốt nhất cho:

• Trích xuất nội dung trang đơn, khi bạn biết chính xác trang nào chứa thông tin.

Không khuyến nghị cho:

• Trích xuất nội dung từ nhiều trang (sử dụng các lệnh gọi scrape lặp lại cho các URL đã biết, hoặc map + scrape để khám phá URL trước, hoặc crawl cho nội dung toàn trang)
• Khi bạn không chắc trang nào chứa thông tin (sử dụng search)

Lỗi thường gặp:

• Truyền danh sách URL vào một lệnh gọi scrape. Gọi scrape một lần cho mỗi URL trong MCP. Nếu bạn đặc biệt cần một thao tác API hàng loạt, hãy sử dụng điểm cuối hàng loạt của API Firecrawl bên ngoài MCP.
• Sử dụng định dạng markdown theo mặc định (sử dụng định dạng JSON để chỉ trích xuất những gì bạn cần).

Chọn định dạng phù hợp:

• Định dạng JSON (ưu tiên): Đối với hầu hết các trường hợp sử dụng, hãy sử dụng định dạng JSON với lược đồ để chỉ trích xuất dữ liệu cụ thể cần thiết. Điều này giữ cho phản hồi tập trung và ngăn tràn cửa sổ ngữ cảnh.
• Định dạng Markdown: Chỉ khi nhiệm vụ thực sự yêu cầu nội dung toàn trang (ví dụ: tóm tắt toàn bộ bài viết, phân tích cấu trúc trang).

Ví dụ lời nhắc:

"Lấy chi tiết sản phẩm từ https://example.com/product."

Ví dụ sử dụng (định dạng JSON - ưu tiên):

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

Ví dụ sử dụng (định dạng markdown - khi cần nội dung đầy đủ):

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

Ví dụ sử dụng (định dạng branding - trích xuất nhận diện thương hiệu):

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

Định dạng branding: Trích xuất nhận diện thương hiệu toàn diện (màu sắc, phông chữ, kiểu chữ, khoảng cách, logo, thành phần UI) để phân tích thiết kế hoặc sao chép phong cách. Quyền riêng tư: Đặt redactPII: true để trả về nội dung với thông tin nhận dạng cá nhân được biên tập lại.

Trả về:

• Dữ liệu có cấu trúc JSON, markdown, hồ sơ branding hoặc các định dạng khác theo chỉ định.

2. Công cụ Map (firecrawl_map)

Lập bản đồ một trang web để khám phá tất cả các URL được lập chỉ mục trên trang web.

Tốt nhất cho:

• Khám phá URL trên một trang web trước khi quyết định thu thập nội dung gì
• Tìm các phần cụ thể của một trang web

Không khuyến nghị cho:

• Khi bạn đã biết URL cụ thể mình cần (sử dụng scrape)
• Khi bạn cần nội dung của các trang (sử dụng scrape sau khi lập bản đồ)

Lỗi thường gặp:

• Sử dụng crawl để khám phá URL thay vì map

Ví dụ lời nhắc:

"Liệt kê tất cả URL trên example.com."

Ví dụ sử dụng:

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

Trả về:

• Mảng các URL được tìm thấy trên trang web

3. Công cụ Search (firecrawl_search)

Tìm kiếm web và tùy chọn trích xuất nội dung từ kết quả tìm kiếm.

Tốt nhất cho:

• Tìm thông tin cụ thể trên nhiều trang web, khi bạn không biết trang web nào có thông tin.
• Khi bạn cần nội dung phù hợp nhất cho một truy vấn

Không khuyến nghị cho:

• Khi bạn đã biết trang web nào cần thu thập (sử dụng scrape)
• Khi bạn cần phạm vi bao phủ toàn diện của một trang web duy nhất (sử dụng map hoặc crawl)

Lỗi thường gặp:

• Sử dụng crawl hoặc map cho các câu hỏi mở (sử dụng search thay thế)

Ví dụ sử dụng:

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "latest AI research papers 2023",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

Đặt highlights thành true để yêu cầu các điểm nổi bật liên quan đến truy vấn hoặc false để giữ nguyên các đoạn trích tìm kiếm gốc. Bỏ qua nó để sử dụng hành vi mặc định của API.

Trả về:

• Mảng kết quả tìm kiếm (với nội dung đã thu thập tùy chọn), cùng với trường id. Truyền id đó vào firecrawl_search_feedback sau khi bạn đã sử dụng kết quả để được hoàn lại 1 credit (tìm kiếm tốn 2 credit) và cải thiện chất lượng tìm kiếm.

Ví dụ Prompt:

"Tìm các bài nghiên cứu mới nhất về AI được xuất bản năm 2023."

3b. Công cụ Phản hồi Tìm kiếm (firecrawl_search_feedback)

Gửi phản hồi có cấu trúc về kết quả firecrawl_search trước đó. Phản hồi đầu tiên cho mỗi id tìm kiếm sẽ hoàn lại 1 credit và cải thiện chất lượng tìm kiếm của Firecrawl. Idempotent trên mỗi id tìm kiếm.

Gọi công cụ này sau mỗi lần tìm kiếm bạn thực sự sử dụng (hoặc không hữu ích). Phản hồi xấu/một phần với missingContent cũng có giá trị như phản hồi tốt.

Từ chối: đặt FIRECRAWL_NO_SEARCH_FEEDBACK=1 (hoặc FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1) trong môi trường khi khởi động máy chủ MCP. Công cụ firecrawl_search_feedback sẽ không được đăng ký, vì vậy các tác nhân không thể gọi nó. Quản trị viên nhóm cũng có thể vô hiệu hóa phản hồi phía máy chủ; trong trường hợp đó, công cụ được đăng ký nhưng luôn trả về feedbackErrorCode: "TEAM_OPTED_OUT".

Trường quan trọng nhất: missingContent. Đó là một mảng các phần nội dung cụ thể mà tác nhân mong đợi tìm thấy nhưng không thấy. Mỗi mục nhập cho một chủ đề bị thiếu — những mục này tổng hợp trên các nhóm và cho chúng tôi biết cần lập chỉ mục gì tiếp theo.

Giới hạn hoàn lại hàng ngày (mỗi nhóm, mỗi ngày UTC, mặc định 100 credit). Khi creditsRefundedToday của một nhóm đạt đến dailyRefundCap, các lần gửi tiếp theo vẫn ghi nhận phản hồi nhưng không còn hoàn lại credit. Phản hồi đặt dailyCapReached: true. Các tác nhân nên ngừng gọi công cụ này trong phần còn lại của ngày UTC khi thấy cờ đó.

Ví dụ Sử dụng:

{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/features/search",
        "reason": "Most up-to-date description of /search."
      }
    ],
    "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'"
  }
}

Trả về:

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

3c. Công cụ Phản hồi Chung (firecrawl_feedback)

Gửi phản hồi có cấu trúc cho một công việc endpoint v2 đã hoàn thành thông qua /v2/feedback. Sử dụng công cụ này cho phản hồi cấp endpoint trên các công việc scrape, parse, map, hoặc search. Đối với chất lượng kết quả tìm kiếm cụ thể, ưu tiên sử dụng firecrawl_search_feedback vì nó bao gồm hướng dẫn cụ thể cho tìm kiếm.

Giữ phản hồi ngắn gọn: sử dụng mã vấn đề, thẻ, ghi chú ngắn, URL, số trang, và các đối tượng siêu dữ liệu nhỏ. Không bao gồm đầu ra thu thập/phân tích cú pháp thô.

Từ chối: đặt FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 (hoặc FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1) trong môi trường khi khởi động máy chủ MCP. Công cụ firecrawl_feedback sẽ không được đăng ký, vì vậy các tác nhân không thể gọi nó.

Ví dụ Sử dụng:

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

Trả về:

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

4. Công cụ Thu thập dữ liệu (firecrawl_crawl)

Bắt đầu một công việc thu thập dữ liệu, thăm dò cho đến khi đạt trạng thái kết thúc và trả về trạng thái/dữ liệu thu thập cuối cùng.

Phù hợp nhất cho:

• Trích xuất nội dung từ nhiều trang liên quan, khi bạn cần phạm vi bao phủ toàn diện.

Không khuyến nghị cho:

• Trích xuất nội dung từ một trang duy nhất (sử dụng scrape)
• Khi giới hạn token là mối quan tâm (sử dụng map + scrape để kiểm soát chặt chẽ hơn)
• Khi bạn cần kết quả nhanh (thu thập dữ liệu có thể chậm)

Cảnh báo: Phản hồi thu thập dữ liệu có thể rất lớn và có thể vượt quá giới hạn token. Giới hạn độ sâu thu thập và số lượng trang, hoặc sử dụng map + scrape để kiểm soát chặt chẽ hơn.

Lỗi thường gặp:

• Đặt limit hoặc maxDiscoveryDepth quá cao (gây tràn token)
• Sử dụng thu thập dữ liệu cho một trang duy nhất (sử dụng scrape thay thế)

Ví dụ Prompt:

"Lấy tất cả bài đăng blog từ hai cấp độ đầu tiên của example.com/blog."

Ví dụ Sử dụng:

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

Trả về:

• Trạng thái và dữ liệu thu thập cuối cùng sau khi thăm dò nội bộ, bao gồm id, status, completed, total, creditsUsed, expiresAt, next, và data. Sử dụng id được trả về với firecrawl_check_crawl_status nếu bạn cần kiểm tra lại công việc sau.

5. Kiểm tra Trạng thái Thu thập dữ liệu (firecrawl_check_crawl_status)

Kiểm tra trạng thái và kết quả của một công việc thu thập dữ liệu hiện có bằng ID.

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

Trả về:

• Phản hồi bao gồm trạng thái của công việc thu thập dữ liệu:

6. Công cụ Phân tích cú pháp (firecrawl_parse)

Phân tích cú pháp tệp cục bộ hoặc tham chiếu tải lên được lưu trữ với endpoint /v2/parse của Firecrawl.

Phù hợp nhất cho: PDF, tài liệu Word, bảng tính, tệp HTML và các tài liệu khác cần đầu ra markdown hoặc JSON có cấu trúc. MCP được lưu trữ hỗ trợ quy trình tải lên-tham chiếu hai bước; đọc tệp trực tiếp cục bộ yêu cầu FIRECRAWL_API_URL tự lưu trữ.

Không khuyến nghị cho: URL từ xa (sử dụng scrape), nhiều tệp trong một lần gọi (gọi phân tích cú pháp một lần cho mỗi tệp), hoặc các hành động chỉ dành cho trình duyệt như chụp ảnh màn hình và nhấp chuột.

Quy trình MCP được lưu trữ: MCP được lưu trữ không thể đọc trực tiếp hệ thống tệp của người gọi. Gọi firecrawl_parse với filePath để nhận lệnh tải lên có thời hạn ngắn và nextToolCall, tải tệp lên cục bộ, sau đó gọi lại firecrawl_parse với uploadRef được trả về. Việc tạo URL tải lên được lưu trữ yêu cầu xác thực Firecrawl hoặc đủ điều kiện không cần khóa. Trong chế độ npx firecrawl-mcp cục bộ, phân tích cú pháp tệp trực tiếp hiện yêu cầu FIRECRAWL_API_URL trỏ đến API Firecrawl tự lưu trữ; một máy chủ cục bộ chỉ có khóa API đám mây thông thường không thể đọc và tải tệp lên thông qua công cụ này.

Ví dụ Sử dụng:

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

Trả về: Nội dung tài liệu đã phân tích cú pháp hoặc hướng dẫn tải lên được lưu trữ với nextToolCall.

7. Công cụ Trích xuất (firecrawl_extract)

Trích xuất thông tin có cấu trúc từ các trang web sử dụng khả năng LLM. Hỗ trợ cả AI đám mây và trích xuất LLM tự lưu trữ.

Phù hợp nhất cho:

• Trích xuất dữ liệu có cấu trúc cụ thể như giá, tên, chi tiết.

Không khuyến nghị cho:

• Khi bạn cần toàn bộ nội dung của một trang (sử dụng scrape)
• Khi bạn không tìm kiếm dữ liệu có cấu trúc cụ thể

Tham số:

• urls: Mảng URL để trích xuất thông tin từ đó
• prompt: Prompt tùy chỉnh cho việc trích xuất LLM
• systemPrompt: Prompt hệ thống để hướng dẫn LLM
• schema: Lược đồ JSON cho trích xuất dữ liệu có cấu trúc
• allowExternalLinks: Cho phép trích xuất từ các liên kết bên ngoài
• enableWebSearch: Bật tìm kiếm web để có thêm ngữ cảnh
• includeSubdomains: Bao gồm các tên miền phụ trong trích xuất

Khi sử dụng phiên bản tự lưu trữ, việc trích xuất sẽ sử dụng LLM đã cấu hình của bạn. Đối với API đám mây, nó sử dụng dịch vụ LLM được quản lý của Firecrawl. Ví dụ Prompt:

"Trích xuất tên sản phẩm, giá và mô tả từ các trang sản phẩm này."

Ví dụ Sử dụng:

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

Trả về:

• Dữ liệu có cấu trúc đã trích xuất như được xác định bởi lược đồ của bạn

{
  "content": [
    {
      "type": "text",
      "text": {
        "name": "Example Product",
        "price": 99.99,
        "description": "This is an example product description"
      }
    }
  ],
  "isError": false
}

8. Công cụ Tác nhân (firecrawl_agent)

Tác nhân nghiên cứu web tự động. Đây là một lớp tác nhân AI riêng biệt độc lập duyệt internet, tìm kiếm thông tin, điều hướng qua các trang và trích xuất dữ liệu có cấu trúc dựa trên truy vấn của bạn.

Cách thức hoạt động:

Tác nhân thực hiện tìm kiếm web, theo dõi liên kết, đọc trang và thu thập dữ liệu một cách tự động. Quá trình này chạy không đồng bộ - nó trả về ID công việc ngay lập tức và bạn thăm dò firecrawl_agent_status để kiểm tra khi nào hoàn thành và lấy kết quả.

Quy trình không đồng bộ:

1. Gọi firecrawl_agent với prompt/lược đồ của bạn → trả về ID công việc
2. Làm công việc khác trong khi tác nhân nghiên cứu (có thể mất vài phút cho các truy vấn phức tạp)
3. Thăm dò firecrawl_agent_status với ID công việc để kiểm tra tiến độ
4. Khi trạng thái là "completed", phản hồi bao gồm dữ liệu đã trích xuất

Phù hợp nhất cho:

• Các tác vụ nghiên cứu phức tạp khi bạn không biết URL chính xác
• Thu thập dữ liệu từ nhiều nguồn
• Tìm kiếm thông tin phân tán trên web
• Các tác vụ mà bạn có thể làm việc khác trong khi chờ kết quả

Không khuyến nghị cho:

• Thu thập dữ liệu trang đơn giản khi bạn biết URL (sử dụng scrape với định dạng JSON - nhanh hơn và rẻ hơn)

Tham số:

• prompt: Mô tả bằng ngôn ngữ tự nhiên về dữ liệu bạn muốn (bắt buộc, tối đa 10.000 ký tự)
• urls: Mảng URL tùy chọn để tập trung tác nhân vào các trang cụ thể
• schema: Lược đồ JSON tùy chọn cho đầu ra có cấu trúc

Ví dụ Prompt:

"Tìm những người sáng lập Firecrawl và lý lịch của họ"

Ví dụ Sử dụng (bắt đầu tác nhân, sau đó thăm dò kết quả):

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

Sau đó thăm dò với firecrawl_agent_status sử dụng ID công việc được trả về.

Ví dụ Sử dụng (với URL - tác nhân tập trung vào các trang cụ thể):

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

Trả về:

• ID công việc để kiểm tra trạng thái. Sử dụng firecrawl_agent_status để thăm dò kết quả.

9. Kiểm tra Trạng thái Tác nhân (firecrawl_agent_status)

Kiểm tra trạng thái của một công việc tác nhân và lấy kết quả khi hoàn thành. Sử dụng công cụ này để thăm dò kết quả sau khi bắt đầu một tác nhân.

Mẫu thăm dò: Nghiên cứu của tác nhân có thể mất vài phút cho các truy vấn phức tạp. Thăm dò endpoint này định kỳ (ví dụ: mỗi 10-30 giây) cho đến khi trạng thái là "completed" hoặc "failed".

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

Các trạng thái có thể có:

• processing: Tác nhân vẫn đang nghiên cứu - kiểm tra lại sau
• completed: Nghiên cứu đã hoàn thành - phản hồi bao gồm dữ liệu đã trích xuất
• failed: Đã xảy ra lỗi

10. Công cụ Tương tác (firecrawl_interact)

Tương tác với một URL mới hoặc với một trang đã được mở bởi firecrawl_scrape.

Phù hợp nhất cho: Nhấp, gõ, điều hướng và trích xuất trạng thái từ các trang động mà không khôi phục các công cụ trình duyệt đã lỗi thời.

Tùy chọn sử dụng:

• Truyền url để thu thập và mở một trang để tương tác trong một lần gọi MCP.
• Truyền scrapeId để tiếp tục tương tác với một trang đã thu thập hiện có.
• Truyền chính xác một trong url hoặc scrapeId, cộng với prompt hoặc code.

Ví dụ Sử dụng:

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

Trả về: Kết quả tương tác và, đối với chế độ URL, scrapeId dẫn xuất để theo dõi hoặc dọn dẹp.

11. Công cụ Dừng Tương tác (firecrawl_interact_stop)

Dừng một phiên tương tác cho một trang đã thu thập khi bạn tương tác xong.

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

12. Công cụ Nghiên cứu (firecrawl_research_*)

Tìm kiếm và kiểm tra các bài báo và kho lưu trữ GitHub thông qua các công cụ MCP nghiên cứu.

Các công cụ nghiên cứu có sẵn:

• firecrawl_research_search_papers: tìm kiếm bài báo nghiên cứu.
• firecrawl_research_inspect_paper: kiểm tra một bài báo.
• firecrawl_research_related_papers: tìm các bài báo liên quan.
• firecrawl_research_read_paper: đọc nội dung bài báo.
• firecrawl_research_search_github: tìm kiếm kho lưu trữ GitHub.

Phù hợp nhất cho: Quy trình đánh giá tài liệu, tra cứu bài báo và khám phá kho lưu trữ nơi tác nhân cần một bề mặt nghiên cứu tập trung thay vì thu thập dữ liệu web chung.

13. Công cụ Giám sát (firecrawl_monitor_*)

Tạo và quản lý các trình giám sát trang định kỳ. Trình giám sát chạy các lần thu thập hoặc thu thập dữ liệu theo lịch trình, so sánh từng kết quả với ảnh chụp nhanh được giữ lại cuối cùng và có thể thông báo qua webhook hoặc email.

Phù hợp nhất cho:

• Theo dõi một trang hoặc một vài trang theo thời gian
• Cảnh báo về các thay đổi có ý nghĩa bằng cách sử dụng mục tiêu bằng tiếng Anh đơn giản
• Theo dõi lịch sử kiểm tra và các khác biệt cấp trang

Mẫu tạo khuyến nghị:

Sử dụng page hoặc pages cộng với goal. Máy chủ MCP xây dựng yêu cầu giám sát với lịch trình 30 phút và API tự động kích hoạt đánh giá thay đổi có ý nghĩa.

Đánh giá thay đổi có ý nghĩa chạy tự động khi goal được đặt. Webhook trang hiển thị isMeaningful và judgment trên các sự kiện monitor.page.

Viết mục tiêu dưới dạng hướng dẫn giám sát ngắn gọn 2-3 câu. Nói rõ điều gì sẽ kích hoạt cảnh báo, giữ nguyên bất kỳ phạm vi nào người dùng đã đưa ra và chỉ bao gồm các loại trừ cụ thể theo ý định khi rõ ràng từ yêu cầu. Nhiễu chung như khoảng trắng, thay đổi chỉ về định dạng, ID yêu cầu, tham số theo dõi, siêu dữ liệu chung và chrome trang không liên quan đã được xử lý bởi trình đánh giá, vì vậy không lặp lại nó trong mọi mục tiêu. Nếu người dùng mơ hồ, hãy giữ mục tiêu rộng; nếu họ yêu cầu giám sát rộng hoặc "bất kỳ thay đổi nào", hãy giữ nguyên điều đó. Nếu người dùng nói họ không quan tâm đến điều gì đó, hãy bao gồm điều đó một cách rõ ràng.

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

Nhiều trang với webhooks:

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

Yêu cầu tạo nâng cao:

Truyền body khi bạn cần mục tiêu thu thập dữ liệu, theo dõi thay đổi JSON, lưu giữ tùy chỉnh hoặc kiểm soát judgeEnabled rõ ràng.

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

Các công cụ giám sát khác:

• firecrawl_monitor_list: liệt kê các trình giám sát.
• firecrawl_monitor_get: lấy một trình giám sát.
• firecrawl_monitor_update: cập nhật các trường bao gồm goal, judgeEnabled, webhook và notification.
• firecrawl_monitor_run: kích hoạt kiểm tra ngay bây giờ.
• firecrawl_monitor_delete: xóa một trình giám sát (có tính hủy hoại; chỉ gọi khi người dùng có ý định xóa nó).
• firecrawl_monitor_checks: liệt kê các lần kiểm tra, tùy chọn lọc theo trạng thái.
• firecrawl_monitor_check: lấy kết quả cấp trang, bao gồm diff, snapshot, judgment.meaningful và judgment.meaningfulChanges.

Hệ thống Ghi nhật ký

Máy chủ bao gồm ghi nhật ký toàn diện:

• Trạng thái và tiến trình hoạt động
• Chỉ số hiệu suất
• Theo dõi giới hạn tốc độ
• Các điều kiện lỗi

Ví dụ về thông điệp nhật ký:

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

Xử lý Lỗi

Máy chủ cung cấp khả năng xử lý lỗi mạnh mẽ:

• Lỗi giới hạn tốc độ API được hiển thị cho máy khách MCP
• Thông điệp lỗi chi tiết
• Khả năng phục hồi mạng

Ví dụ về phản hồi lỗi:

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

Phát triển

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Đóng góp

1. Fork kho lưu trữ
2. Tạo nhánh tính năng của bạn
3. Chạy kiểm thử: npm test
4. Gửi yêu cầu kéo (pull request)

Cảm ơn những người đóng góp

Cảm ơn @vrknetha, @cawstudios vì đã triển khai ban đầu!

Cảm ơn MCP.so và Klavis AI đã lưu trữ và @gstarwd, @xiangkaiz và @zihaolin96 đã tích hợp máy chủ của chúng tôi.

Giấy phép

Giấy phép MIT - xem tệp LICENSE để biết chi tiết