Firecrawl

Máy chủ MCP Firecrawl

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ẵn sàng cho tác nhân.

Cảm ơn lớn đến @vrknetha, @knacklabs vì bản triển khai ban đầu!

Tính năng

• Tìm kiếm web và nhận toàn bộ nội dung trang
• Tìm kiếm chỉ mục được xây dựng cho tác nhân lập trình: vấn đề GitHub, yêu cầu kéo đã hợp nhất, tệp README và tài liệu
• 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 trang — nhấp, điều hướng và thao tác
• Nghiên cứu 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

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.

Khi Nào Nên Dùng Máy Chủ Này

• Dùng firecrawl_scrape khi bạn có URL đã biết và muốn nội dung của nó dưới dạng markdown hoặc JSON khớp với lược đồ bạn cung cấp.
• Dùng firecrawl_map khi bạn cần khám phá URL trên một trang web mà không cần tải nội dung của chúng.
• Dùng firecrawl_crawl khi bạn cần nội dung từ nhiều trang trong một trang web; đặt limit, includePaths/excludePaths, hoặc maxDiscoveryDepth để giới hạn phạm vi.
• Dùng firecrawl_search khi bạn bắt đầu từ một truy vấn thay vì URL và muốn kết quả web được xếp hạng; thêm scrapeOptions nếu bạn cũng muốn nội dung trang được tải trong cùng một lệnh gọi (điểm cuối chỉ tìm kiếm không bao giờ tải nội dung).
• Dùng firecrawl_interact khi một trang cần hành động nhấp, nhập hoặc điều hướng trước khi bạn có thể đọc nó — truyền url cho trang mới hoặc scrapeId để tiếp tục trên trang bạn đã thu thập.
• Dùng các công cụ firecrawl_monitor_* khi cùng một trang cần được kiểm tra theo lịch định kỳ với thông báo khác biệt và thay đổi, thay vì tải một lần.
• Cân nhắc giải pháp khác khi bạn cần giữ phiên trình duyệt mở qua nhiều bước của riêng bạn với logic thử lại và kết thúc của riêng bạn: mỗi lệnh gọi firecrawl_interact chạy một lượt prompt hoặc code đến khi hoàn tất và trả quyền điều khiển — phiên có thể tồn tại qua các lệnh gọi thông qua scrapeId và kết thúc bằng firecrawl_interact_stop, nhưng bạn không thể điều khiển nó tương tác từng bước từ phía máy khách trong một lệnh gọi duy nhất.

Máy chủ này liệt kê 25 công cụ khi hồ sơ đầy đủ đăng ký với cài đặt mặc định (bao gồm công cụ phản hồi, không chạy ở chế độ không khóa cục bộ). Đặt FIRECRAWL_NO_SEARCH_FEEDBACK=1 và/hoặc FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 sẽ loại bỏ các công cụ phản hồi tương ứng và giảm số lượng này, cũng như khởi động không khóa cục bộ. Đối với máy khách có giới hạn vị trí công cụ: điểm cuối không khóa được lưu trữ (https://mcp.firecrawl.dev/v2/mcp, không cần khóa API) chỉ hiển thị 3 — firecrawl_scrape, firecrawl_search, firecrawl_parse — và điểm cuối chỉ tìm kiếm chuyên dụng (https://mcp.firecrawl.dev/v2/mcp-search) hiển thị cố định 6 công cụ chỉ đọc.

Cài đặt

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

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

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

Trên tầng miễn phí không khóa, scrape, search, và parse 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, và agent vẫn cần khóa.

Ưu tiên OAuth hoặc khóa API bất cứ khi nào người dùng có thể đăng ký. Nó mở khóa toàn bộ bộ công cụ và giới hạn cao hơn.

Để kết nối tài khoản tương tác, cấu hình máy khách MCP của bạn để sử dụng URL máy chủ này. Đây là điểm cuối MCP, không phải trang trình duyệt; sử dụng luồng kết nối tài khoản của máy khách và không thêm mục nhập máy chủ Firecrawl thứ hai khi kết nối lại:

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

Để kết nối bằng khóa API (ví dụ: tích hợp không giám sát), giữ URL máy chủ là:

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

Sau đó cấu hình cài đặt tiêu đề bảo mật hoặc bí mật của máy khách với:

Authorization: Bearer <FIRECRAWL_API_KEY>

Không bao giờ đặt khóa API trong URL máy chủ. Không bao giờ đặt khóa API trong cuộc trò chuyện tác nhân. Cấu hình trực tiếp trong máy khách hoặc trình quản lý bí mật. Xem hướng dẫn thiết lập MCP được lưu trữ và hướng dẫn giới thiệu tác nhân để biết hướng dẫn cụ thể cho từng máy khách.

Đ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 sáu công cụ chỉ đọc: firecrawl_search, firecrawl_developer_search, và bốn công cụ firecrawl_research_*. Nó không thực hiện tải 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 phiên bản Cursor 0.45.6+ Để biết hướng dẫn cấu hình mới nhất, vui lòng tham khảo tài liệu chính thức của Cursor về cấu hình máy chủ MCP: Hướng dẫn cấu hình máy chủ MCP của 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ầu 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 như sau:
   • Tên: "firecrawl-mcp" (hoặc tên bạn muốn)
   • Loại: "lệnh"
   • Lệnh: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

Nếu bạn đang 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 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, làm mới danh sách máy chủ MCP để thấy các công cụ mới. Tác nhân Composer sẽ tự động sử dụng Firecrawl MCP khi phù 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 "Tác nhân" 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 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ế độ HTTP Streamable Cục bộ

Để chạy máy chủ bằng HTTP Streamable 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 (Kế thừa)

Để 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, nhấp vào một trong các nút cài đặt bên dưới...

Để cài đặt thủ công, 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ể làm điều này bằng cách nhấn Ctrl + Shift + P và gõ 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 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ã truy cập Bearer)

Firecrawl được lưu trữ có thể phát hành mã truy cập OAuth (fco_…) 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ó phân giải đế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): Máy khách nên gửi Authorization: Bearer <fco_access_token> trên các yêu cầu MCP. Mã 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ã 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ã truy cập (fco_…). Mã làm mới (fcr_…) phải được trao đổi tại điểm cuối mã, không được truyề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 quy trình thứ hai phục vụ điểm cuối chỉ tìm kiếm. Dịch vụ đi kèm có 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. Quy 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 bài kiểm tra 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 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 mã 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

Để sử dụng API đám mây:

export FIRECRAWL_API_KEY=your-api-key

Để sử dụng 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 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 URL chính xác bạn 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 mỗi URL. Nếu bạn cụ thể cần một thao tác API hàng loạt, sử dụng điểm cuối hàng loạt 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 web để lấy thông tin: sử dụng search
• Nếu bạn có câu hỏi lập trình (một thư viện, hợp đồng API, thông báo lỗi, lỗi đã biết): sử dụng tìm kiếm nhà phát triển
• Nếu bạn cần bài báo khoa học (tài liệu y sinh, khoa học đời sống, lâm sàng hoặc arXiv): sử dụng công cụ nghiên cứu — chúng tìm kiếm tóm tắt và toàn văn bài báo. search với categories: ["research"] là một thứ khác: bộ lọc trang web trên kết quả web thông thường.
• Nếu bạn cần nghiên cứu đa nguồn trả về dữ liệu có cấu trúc, không biết URL, hoặc câu trả lời trải qua nhiều trang web (một thực thể cùng các trường của nó, một danh sách, một tập dữ liệu): sử dụng agent
• Nếu bạn muốn phân tích toàn bộ trang web hoặc 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 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 chiếu 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 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 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
search	Tìm kiếm web để lấy thông tin	results[]
developer	Câu hỏi lập trình qua nguồn nhà phát triển	results[] với đoạn văn
agent	Nghiên cứu đa nguồn, không biết hoặc nhiều trang web	JSON (dữ liệu có cấu trúc)
monitor	Kiểm tra trang định kỳ	siêu dữ liệu giám sát/kiểm tra và khác biệt
research	Nghiên cứu bài báo và kho lưu trữ GitHub	kết quả nghiên cứu và khớp kho lưu trữ

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

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

• Định dạng JSON (khuyến nghị cho hầu hết các trường hợp): Sử dụng khi bạn cần dữ liệu cụ thể từ một trang. Xác định schema 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 ngữ cảnh.
• Định dạng Markdown (sử dụng hạn chế): Chỉ khi bạn thực sự cần toàn bộ nội dung 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ác công cụ có sẵn

1. Công cụ Scrape (firecrawl_scrape)

Trích xuất nội dung từ một URL duy nhất với các tùy chọn nâng cao.

Phù hợp nhất cho:

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

Các lỗi thường gặp:

• Truyền một danh sách URL vào một lệnh scrape. Gọi scrape một lần cho mỗi URL trong MCP. Nếu bạn cụ thể cần một thao tác API hàng loạt, hãy sử dụng endpoint batch 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 schema để 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 ngữ cảnh.
• Định dạng Markdown: Chỉ khi nhiệm vụ thực sự yêu cầu toàn bộ nội dung 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ụ về prompt:

"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 toàn bộ nội dung):

{
  "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 tái tạo 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 JSON có cấu trúc, 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.

Phù hợp nhất cho:

• Khám phá các URL trên một trang web trước khi quyết định scrape
• 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ể bạn 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 map)

Các lỗi thường gặp:

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

Ví dụ về prompt:

"Liệt kê tất cả cá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

3. Công cụ Search (firecrawl_search)

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

Phù hợp 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 scrape (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)

Các 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": "remote work stipend policies at tech companies",
    "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 để sử dụng hành vi mặc định của API.

Đối với các bài báo khoa học, xem Công cụ nghiên cứu: chúng tìm kiếm tóm tắt và toàn văn bài báo, trong khi categories: ["research"] ở đây lọc các kết quả web thông thường đến các trang web liên quan đến nghiên cứu.

Trả về:

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

Ví dụ về prompt:

"So sánh các chính sách trợ cấp làm việc từ xa giữa các công ty công nghệ."

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 hoàn lại 1 tín dụng và cải thiện chất lượng tìm kiếm của Firecrawl. Idempotent cho 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 agent 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. Đây là một mảng các phần nội dung cụ thể mà agent mong đợi tìm thấy nhưng không thấy. Một mục cho mỗi chủ đề còn thiếu — chúng được tổng hợp trên các nhóm và cho chúng tôi biết nên lập chỉ mục gì tiếp theo.

Giới hạn hoàn tiền hàng ngày (mỗi nhóm, mỗi ngày UTC, mặc định 100 tín dụng). Khi creditsRefundedToday của một nhóm đạt dailyRefundCap, các lần gửi tiếp theo vẫn ghi lại phản hồi nhưng không còn hoàn lại tín dụng. Phản hồi đặt dailyCapReached: true. Các agent 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. Cụ thể cho chất lượng kết quả tìm kiếm, hãy ưu tiên 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ã lỗi, thẻ, ghi chú ngắn, URL, số trang và các đối tượng metadata nhỏ. Không bao gồm đầu ra scrape/parse 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 agent 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ụ Crawl (firecrawl_crawl)

Bắt đầu một công việc crawl, thăm dò cho đến khi đạt trạng thái cuối và trả về trạng thái/dữ liệu crawl 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 (crawl có thể chậm)

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

Các lỗi thường gặp:

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

Ví dụ về 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 crawl 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 này.

5. Kiểm tra trạng thái Crawl (firecrawl_check_crawl_status)

Kiểm tra trạng thái và kết quả của một công việc crawl hiện có theo 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 crawl:

6. Công cụ Parse (firecrawl_parse)

Phân tích các 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ợ luồng 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ệnh gọi (gọi parse 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 màn hình và nhấp chuột.

Luồng 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 ngắn hạn và nextToolCall, tải tệp lên cục bộ, sau đó gọi firecrawl_parse lại với uploadRef được trả về. 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 tệp trực tiếp hiện yêu cầu FIRECRAWL_API_URL trỏ đến API Firecrawl tự lưu trữ; 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 hoặc hướng dẫn tải lên được lưu trữ với nextToolCall.

7. Dữ liệu có cấu trúc với Scrape JSON

Đối với dữ liệu có cấu trúc từ một trang đã biết, gọi firecrawl_scrape một lần cho mỗi URL với formats: ["json"]. Đặt prompt trích xuất và JSON schema trong 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"]
      }
    }
  }
}

Khi các URL không được biết hoặc dữ liệu trải rộng trên nhiều trang, sử dụng firecrawl_agent cho nghiên cứu đa nguồn.

8. Công cụ Agent (firecrawl_agent)

Agent nghiên cứu web tự động trả về dữ liệu có cấu trúc khi bạn không biết các URL hoặc câu trả lời trải rộng trên nhiều trang. Mô tả các trường bạn cần, tùy chọn truyền JSON schema và URL gốc, và agent sẽ tìm kiếm, điều hướng, đọc trang và trả về JSON được tổng hợp từ nhiều nguồn. Sử dụng công cụ này cho một thực thể cùng các trường của nó, cho danh sách và tập dữ liệu, và cho các trang cần điều hướng để đến dữ liệu. Đối với một URL đã biết, sử dụng firecrawl_scrape với định dạng JSON thay thế.

Cách hoạt động:

Agent thực hiện tìm kiếm web, theo liên kết, đọc trang và thu thập dữ liệu tự động. Điều 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 hoàn thành và lấy kết quả.

Luồng không đồng bộ:

1. Gọi firecrawl_agent với prompt/schema của bạn → trả về ID công việc
2. Làm việc khác trong khi agent 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 trình
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 nhiệm 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 đa nguồn
• Tìm thông tin rải rác trên web
• Các nhiệm vụ mà bạn có thể làm việc khác trong khi chờ kết quả

Không khuyến nghị cho:

• Scrape 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)

Đối số:

• prompt: Mô tả 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 agent vào các trang cụ thể
• schema: JSON schema tùy chọn cho đầu ra có cấu trúc

Ví dụ về 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 agent, 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 - agent 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 Agent (firecrawl_agent_status)

Kiểm tra trạng thái của một công việc agent 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 agent.

Mẫu thăm dò: Nghiên cứu agent 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ể:

• processing: Agent 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ụ Interact (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 chuột, nhập văn bản, điều hướng và trích xuất trạng thái từ các trang động mà không cần khôi phục các công cụ trình duyệt đã ngừng hoạt động.

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 đã được thu thập trướ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 hoàn tất việc tương tác.

{
  "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 cũng như kho lưu trữ GitHub thông qua các công cụ MCP nghiên cứu.

Bao gồm: Tóm tắt bài báo và toàn văn trên các tài liệu y sinh, khoa học đời sống và lâm sàng (PubMed, bioRxiv, medRxiv) cùng với arXiv và các nguồn khoa học khác.

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

• firecrawl_research_search_papers: tìm kiếm siêu dữ liệu và tóm tắt bài báo bằng truy vấn ngôn ngữ tự nhiên, với các bộ lọc tác giả, danh mục và ngày tùy chọn.
• firecrawl_research_inspect_paper: truy xuất siêu dữ liệu chuẩn cho một ID bài báo (arXiv, PMC, PMID hoặc DOI).
• firecrawl_research_related_papers: mở rộng từ một hoặc nhiều bài báo mốc thông qua đồ thị trích dẫn.
• firecrawl_research_read_paper: đọc các đoạn toàn văn từ một bài báo cụ thể.

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

firecrawl_search với categories: ["research"] là một bề mặt khác: nó lọc các kết quả web thông thường đến các trang web liên kết với nghiên cứu và trả về các đoạn trang, không phải bản ghi bài báo. Sử dụng các công cụ này khi câu hỏi liên quan đến chính tài liệu và truyền nhiều cách diễn đạt khác nhau của cùng một câu hỏi — chúng hiển thị các bài báo khác nhau so với một truy vấn duy nhất.

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

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

Phù hợp nhất cho:

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

Mẫu tạo được 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 bậ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êu rõ điều gì nên kích hoạt cảnh báo, giữ nguyên phạm vi mà người dùng đưa ra và chỉ bao gồm các loại trừ theo ý định khi rõ ràng từ yêu cầu. Nhiễu chung như khoảng trắng, thay đổi chỉ định dạng, ID yêu cầu, tham số theo dõi, siêu dữ liệu chung và khung trang không liên quan đã được bộ đánh giá xử lý, vì vậy không lặp lại trong mỗi mục tiêu. Nếu người dùng mơ hồ, 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. 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 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"
  }
}

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

Truyền body khi bạn cần mục tiêu thu thập, 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 bộ giám sát.
• firecrawl_monitor_get: lấy một bộ 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 bộ giám sát (có tính phá hủy; 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.

14. Công cụ Tìm kiếm Nhà phát triển (firecrawl_developer_search)

Tìm kiếm một chỉ mục được xây dựng cho các tác nhân lập trình. Chỉ mục bao gồm các vấn đề GitHub, yêu cầu kéo đã hợp nhất, README kho lưu trữ và các trang tài liệu được tuyển chọn.

Phù hợp nhất cho: Một câu hỏi lập trình — hành vi mã, thư viện hoặc khung, hợp đồng API, thông báo lỗi hoặc lỗi đã biết.

Đối số:

{
  "name": "firecrawl_developer_search",
  "arguments": {
    "query": "how do I configure retries",
    "k": 10,
    "skills": "only"
  }
}

• query (bắt buộc): câu hỏi hoặc cụm từ tìm kiếm của nhà phát triển.
• k: số lượng kết quả được xếp hạng. Mặc định là 10 và tối đa là 100.
• skills: đặt thành "only" để chỉ tìm kiếm các tệp kỹ năng tác nhân.

Trả về: Kết quả được xếp hạng. Mỗi kết quả mang ID, loại nguồn (issue, pull_request, readme hoặc doc), URL, tiêu đề và các đoạn khớp ở định dạng markdown.

firecrawl_search với categories: ["developer"] tìm kiếm cùng một chỉ mục bên cạnh các kết quả web. Sử dụng công cụ này thay thế khi bạn muốn các đoạn khớp, bộ lọc skills hoặc không có kết quả web trong phản hồi. Điểm cuối chỉ tìm kiếm hiển thị cả hai công cụ và lựa chọn tương tự áp dụng ở đó.

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
• Số liệu hiệu suất
• Theo dõi giới hạn tốc độ
• Điều kiện lỗi

Ví dụ về thông báo 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 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 báo 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 tra: npm test
4. Gửi yêu cầu kéo

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 vì đã lưu trữ và @gstarwd, @xiangkaiz và @zihaolin96 vì đã 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