Firecrawl MCP

chính thức

Thêm khả năng thu thập dữ liệu web và tìm kiếm mạnh mẽ cho các ứng dụng khách LLM như Cursor và Claude.

Xem trên firecrawl.link

Bạn có thể làm gì với Firecrawl MCP?

Scrape một URL đã biết — Yêu cầu trợ lý của bạn kéo một trang đơn lẻ thành Markdown sạch hoặc JSON có cấu trúc khớp với schema bạn cung cấp qua firecrawl_scrape.
Khám phá URL của trang web — Yêu cầu nó liệt kê các URL đã được lập chỉ mục trên một trang web bằng firecrawl_map trước khi quyết định tải những trang nào.
Tìm kiếm trên web — Nhận kết quả được xếp hạng cho một truy vấn bằng firecrawl_search, tùy chọn tải toàn bộ nội dung trang cho một vài kết quả.
Crawl nhiều trang — Trích xuất nội dung trên toàn bộ trang web bằng firecrawl_crawl, giới hạn bằng limit, includePaths/excludePaths, hoặc maxDiscoveryDepth.
Điều khiển trình duyệt — Nhấp, gõ, điền biểu mẫu, hoặc điều hướng các trang động bằng firecrawl_interact, tiếp tục phiên qua scrapeId.
Kiểm tra mức sử dụng tín dụng — Hỏi còn bao nhiêu tín dụng Firecrawl hoặc chúng đã được dùng vào việc gì bằng firecrawl_credit_usage.

Tài liệu

Máy chủ Firecrawl MCP

Một máy chủ Model Context Protocol (MCP) mang Firecrawl, API ngữ cảnh dành cho các tác nhân AI, đến với các ứng dụng khách tương thích MCP: tìm kiếm, thu thập và tương tác với web trực tiếp và nhận về Markdown sạch hoặc dữ liệu có cấu trúc.

Xin gửi lời cảm ơn lớn đến @vrknetha, @knacklabs vì phần triển khai ban đầu!

Tính năng

Tìm kiếm trên web, tùy chọn kèm nội dung đầy đủ của từng trang kết quả
Tìm kiếm trong các chỉ mục dành cho nguồn lập trình viên (vấn đề GitHub, pull request đã hợp nhất, README và tài liệu), nguồn chính phủ Hoa Kỳ và các bài báo khoa học (PubMed, bioRxiv, medRxiv, arXiv)
Thu thập bất kỳ URL nào thành Markdown sạch hoặc JSON có cấu trúc
Phân tích PDF và tài liệu
Thu thập nội dung từ nhiều trang của một trang web, hoặc lập bản đồ để khám phá các URL của nó
Tương tác với các trang trong trình duyệt thực: nhấp, gõ, điền biểu mẫu và điều hướng các trang động
Chạy các tác vụ Agent cho nghiên cứu đa nguồn trả về dữ liệu có cấu trúc
Giám sát các trang và nhận thông báo khi nội dung của chúng thay đổi
Kiểm tra mức sử dụng tín dụng Firecrawl hiện tại và trong quá khứ
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 thử nghiệm Máy chủ MCP của chúng tôi trên sân chơi của 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 đã biết URL 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á các URL trên một trang web mà không 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 thuộc 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ì một URL và muốn kết quả web được xếp hạng. Kết quả có kèm trích đoạn; hãy tải toàn bộ trang bằng firecrawl_scrape trên các URL bạn cần. scrapeOptions tải trang của mọi kết quả trong cùng một lần gọi và tính phí từng trang như một lần thu thập, vì vậy hãy chỉ dùng nó khi cần toàn văn của một vài kết quả (đ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 thao tác nhấp, gõ hoặc điều hướng trước khi bạn có thể đọc nó: truyền một url cho trang mới hoặc một 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 các bản so sánh khác biệt và cảnh báo thay đổi, thay vì chỉ tải một lần.
Dùng firecrawl_credit_usage để kiểm tra số tín dụng còn lại hoặc tín dụng đã chi tiêu, theo tháng hoặc ngày, tùy chọn phân tách theo điểm cuối hoặc khóa API.
Hãy cân nhắc một giải pháp khác khi bạn cần giữ một 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 riêng: mỗi lần gọi firecrawl_interact chạy một lượt prompt hoặc code đến khi hoàn tất rồi trả lại quyền điều khiển. Phiên có thể tồn tại qua các lần gọi nhờ 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 ứng dụng khách trong một lần gọi duy nhất.

Máy chủ này liệt kê 27 công cụ khi hồ sơ đầy đủ đăng ký với cài đặt mặc định (bao gồm các 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 các ứng dụng khách có giới hạn số ô công cụ: điểm cuối được lưu trữ không khóa (https://mcp.firecrawl.dev/v2/mcp, không cần khóa API) chỉ cung cấp 3 công cụ (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) cung cấp một bộ cố định gồm 9 công cụ (tìm kiếm, tìm kiếm cho lập trình viên, chính phủ và nghiên cứu, cùng với tra cứu và thực thi danh mục Alexandria).

Cài đặt

MCP được lưu trữ (gói miễn phí không cần 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 gói miễn phí không khóa, scrape, search và parse hoạt động mà không cần khóa API (có giới hạn tốc độ). Các công cụ khác như crawl, map và agent vẫn cần khóa.

Hãy ư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, hãy cấu hình ứng dụng khách MCP của bạn để dùng URL máy chủ này. Đây là một điểm cuối MCP, không phải trang trình duyệt; hãy dùng quy trình kết nối tài khoản của ứng dụng khách và không thêm mục 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ụ: một tích hợp không cần giám sát), hãy giữ URL máy chủ là:

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

Sau đó cấu hình tiêu đề bảo mật hoặc cài đặt bí mật của ứng dụng 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 với tác nhân. Hãy cấu hình trực tiếp trong ứng dụng 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 khởi động tác nhân để biết hướng dẫn riêng cho từng ứng dụng khách.

Đặt tên cho tích hợp của bạn

Một tích hợp kết nối qua HTTP có thể tự đặt tên bằng tiêu đề X-Firecrawl-Origin, ví dụ X-Firecrawl-Origin: my-agent. Máy chủ báo cáo nó cho Firecrawl dưới dạng nguồn gốc yêu cầu mcp-my-agent@<server version>, thay cho tên ứng dụng khách hoặc User-Agent mà nó sẽ báo cáo nếu không có. Dùng chữ cái, chữ số và dấu gạch ngang: mỗi chuỗi ký tự khác sẽ trở thành một dấu gạch ngang, dấu gạch ngang ở đầu và cuối bị loại bỏ, và tên bị cắt ở 48 ký tự. Kết quả công cụ không bị ảnh hưởng; chỉ nguồn gốc gửi đến API Firecrawl (và được truyền cho beforeKeylessRequest của trình nhúng) thay đổi.

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

Một bề mặt tìm kiếm có phạm vi cố định cũng được lưu trữ tại:

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

Nó cung cấp một bộ cố định gồm chín công cụ: firecrawl_search, firecrawl_developer_search, firecrawl_gov_search, bốn công cụ firecrawl_research_*, và hai công cụ Alexandria firecrawl_find_tools và firecrawl_scrape. firecrawl_search của nó không tải nội dung trang nào.

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

Mở Cài đặt Cursor
Đi đến Features > MCP Servers
Nhấp "+ Add new global MCP server"

Nhập đoạn 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

Mở Cài đặt Cursor
Đi đến Features > MCP Servers
Nhấp "+ Add New MCP Server"
Nhập thông tin sau:
- Name: "firecrawl-mcp" (hoặc tên bạn muốn)
- Type: "command"
- Command: 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, 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 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ả những gì bạn cần từ web. 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 đoạn 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ế độ HTTP có thể truyền phát cục bộ

Để chạy máy chủ bằng Streamable HTTP cục bộ thay vì giao thức truyền tải stdio mặc định:

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

Dùng url: http://localhost:3000/mcp

Ở chế độ này, máy chủ chỉ trả lời các yêu cầu gửi đến localhost, 127.0.0.1 hoặc [::1] (trên bất kỳ cổng nào), cộng với địa chỉ trong HOST khi nó không phải là 0.0.0.0 hoặc ::. Một yêu cầu có tiêu đề Host nêu tên máy chủ khác, hoặc có tiêu đề Origin nêu tên trang khác, sẽ nhận 403, và các tiêu đề CORS phản hồi lại nguồn gốc được phép thay vì *. Các yêu cầu GET và HEAD đến /health được trả lời bất kể máy chủ nào, để các kiểm tra tình trạng vẫn hoạt động, và máy chủ ghi nhật ký một dòng nêu tên FIRECRAWL_MCP_ALLOWED_HOSTS cho mỗi yêu cầu nó từ chối. Điều này ngăn các trang web bạn truy cập gọi máy chủ cục bộ thông qua tái liên kết DNS hoặc yêu cầu khác nguồn gốc và sử dụng FIRECRAWL_API_KEY của nó.

Để truy cập máy chủ dưới tên hoặc địa chỉ khác, chẳng hạn như tên máy chủ phía sau proxy ngược hoặc IP mạng LAN, hãy liệt kê nó trong FIRECRAWL_MCP_ALLOWED_HOSTS (phân tách bằng dấu phẩy; cổng bị bỏ qua). Danh sách tương tự quyết định những nguồn gốc trình duyệt nào được phép gọi máy chủ. Một proxy ngược trên cùng máy có thể giữ địa chỉ liên kết mặc định:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  FIRECRAWL_MCP_ALLOWED_HOSTS=mcp.home.lan npx -y firecrawl-mcp

Các ứng dụng khách trên máy khác cũng cần máy chủ lắng nghe trên một địa chỉ không phải loopback, vì vậy hãy đặt cả HOST. Mọi ứng dụng khách có thể truy cập cổng sau đó đều được phục vụ bằng FIRECRAWL_API_KEY của máy chủ, vì vậy chỉ làm điều này trên một mạng bạn tin cậy:

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=* tắt kiểm tra và khôi phục tiêu đề CORS đại diện tất cả. Chỉ làm điều đó khi có thứ gì đó phía trước máy chủ tự kiểm tra máy chủ và nguồn gốc.

Chạy với Docker

Hình ảnh ghcr.io/firecrawl/firecrawl-mcp-server chạy cùng máy chủ như npx -y firecrawl-mcp. Mỗi bản dựng từ main được gắn thẻ latest, v<package version> và sha-<commit sha>. v<package version> chuyển sang bản dựng mới nhất của phiên bản đó, vì vậy hãy ghim sha-<commit sha> (hoặc một digest) khi bạn cần một hình ảnh cố định.

stdio (mặc định), dành cho các ứng dụng khách MCP khởi chạy máy chủ như một lệnh:

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, được phục vụ tại 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

Hình ảnh đặt HOST=0.0.0.0 và PORT=3000; ghi đè PORT (và ánh xạ -p) để lắng nghe ở nơi khác. Máy chủ dùng FIRECRAWL_API_KEY của container cho các yêu cầu không gửi thông tin xác thực riêng, vì vậy ví dụ chỉ công bố cổng trên 127.0.0.1; đừng để lộ nó rộng hơn trừ khi các ứng dụng khách phải tự cung cấp khóa. Đặt FIRECRAWL_API_URL để dùng API Firecrawl tự lưu trữ. Container chạy dưới người dùng node không có đặc quyền. Máy chủ chỉ trả lời localhost, 127.0.0.1 và [::1] trong các tiêu đề Host và Origin, vì vậy ánh xạ -p 127.0.0.1:3000:3000 hoạt động nguyên trạng; để truy cập nó dưới tên khác, hãy đặt -e FIRECRAWL_MCP_ALLOWED_HOSTS=<host> (xem chế độ HTTP có thể truyền phát cục bộ).

Chạy trên VS Code

Để cài đặt một cú nhấp, 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 User Settings (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 một tệp có tên .vscode/mcp.json trong không gian làm việc của bạn. Điều này 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 dùng API đám mây (mặc định)
- Tùy chọn khi 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 dùng (yêu cầu khóa API)
FIRECRAWL_INTEGRATION (Tùy chọn): Thẻ tích hợp cho các ứng dụng khởi chạy máy chủ này, chẳng hạn như tiện ích mở rộng của trình soạn thảo
- Được gửi dưới dạng trường integration của các yêu cầu scrape, batch scrape, crawl, map, search, extract, agent, parse, interact và feedback
- Dùng một giá trị bắt đầu bằng _, ví dụ _zed

Chế độ HTTP cục bộ

FIRECRAWL_MCP_ALLOWED_HOSTS (Tùy chọn): Các tên máy chủ hoặc địa chỉ bổ sung mà máy chủ phản hồi bằng HTTP_STREAMABLE_SERVER=true hoặc SSE_LOCAL=true, phân tách bằng dấu phẩy
- localhost, 127.0.0.1, [::1] và một HOST không phải ký tự đại diện luôn được cho phép; cổng bị bỏ qua
- Các yêu cầu có tiêu đề Host hoặc Origin chỉ định bất kỳ máy chủ nào khác sẽ nhận 403, ngoại trừ các yêu cầu GET và HEAD tới /health
- * tắt kiểm tra; không dùng với CLOUD_SERVICE=true, vốn phản hồi mọi máy chủ

MCP OAuth (Bearer access tokens)

Firecrawl cấp access token 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 mà nó phân giải được tới API Firecrawl dưới dạng Authorization: Bearer ….

Truyền tải HTTP stream (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. Bearer token OAuth được ưu tiên hơn x-firecrawl-api-key / x-api-key khi cả hai đều có mặt.
stdio: Dùng FIRECRAWL_OAUTH_TOKEN cho access token tĩnh, hoặc tiếp tục dùng FIRECRAWL_API_KEY cho API key.

Chỉ dùng access token (fco_…). Refresh token (fcr_…) phải được trao đổi tại endpoint token, không được truyền tới API scrape/search.

`CLOUD_SERVICE=true`

CLOUD_SERVICE=true cung cấp các công cụ qua streamable HTTP trên PORT (mặc định 3000, gắn với 0.0.0.0) với các mặc định nghiêm ngặt hơn: mọi yêu cầu phải mang thông tin xác thực (API key hoặc access token OAuth), scrape chỉ đọc (xem công cụ scrape bên dưới), và firecrawl_parse chỉ chấp nhận tải lên.

FASTMCP_ENDPOINT chọn bề mặt công cụ: /v2/mcp (mặc định) cho bộ công cụ đầy đủ, /v2/mcp-oauth cho bề mặt tài khoản, hoặc /v2/mcp-search cho các công cụ chỉ tìm kiếm (điều này cũng yêu cầu FIRECRAWL_MCP_SEARCH_OAUTH_ONLY=true). Với bề mặt đầy đủ, một phiên bản chỉ tìm kiếm cũng khởi động trên cổng 3001; đặt FIRECRAWL_MCP_SEARCH_ENABLED=false để tắt nó.

Ví dụ cấu hình

Đối với 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 đoạn 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ụ

Dùng hướng dẫn này để chọn đúng công cụ cho tác vụ của bạn:

Nếu bạn biết chính xác URL mình muốn: 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 thực sự cần một thao tác API hàng loạt, hãy dùng endpoint batch 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: dùng map
Nếu bạn muốn tìm kiếm thông tin trên web: dùng search
Nếu bạn có câu hỏi về lập trình (một thư viện, một hợp đồng API, một thông báo lỗi, một lỗi đã biết): dùng developer search
Nếu bạn có câu hỏi về pháp lý hoặc quy định (một đạo luật, quy định, bộ luật, ý kiến tòa án hoặc ấn phẩm khác của chính phủ Hoa Kỳ): dùng Firecrawl Government Index
Nếu bạn cần bài báo khoa học (y sinh, khoa học sự sống, lâm sàng hoặc tài liệu arXiv): dùng research tools, công cụ này 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: một 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 rộng trên nhiều trang (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): dùng agent
Nếu bạn muốn phân tích toàn bộ trang web hoặc một phần: 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, gõ, điều hướng): dùng interact với một URL để có trang mới, hoặc scrape + interact khi bạn đã scrape trang hoặc cần kiểm soát scrape chặt chẽ hơn
Nếu bạn cần dữ liệu từ một nhà cung cấp đã được lập danh mục (Alexandria): tìm kiếm với sources: ["alexandria"], xem xét hợp đồng đã chọn với find_tools, và thực thi nó với scrape alexandria

Bảng tham chiếu nhanh

Công cụ	Tốt nhất cho	Trả về
scrape	Nội dung một trang	JSON (ưu tiên) hoặc markdown
interact	Tương tác với một URL hoặc trang đã scrape	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 crawl 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
search	Tìm kiếm web thông tin	results[]
find_tools	Duyệt danh mục Alexandria và tra cứu URL	nhà cung cấp, hợp đồng công cụ và điều hướng nextTool
developer	Câu hỏi lập trình trên các nguồn dành cho lập trình viên	results[] với các đoạn trích
gov	Luật chính và tài liệu quy định của Hoa Kỳ	results[] với đoạn trích
agent	Nghiên cứu đa nguồn, nhiều trang hoặc chưa biết	JSON (dữ liệu có cấu trúc)
monitor	Kiểm tra trang định kỳ	siêu dữ liệu và diff 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à các kho lưu trữ khớp

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

Khi dùng scrape, hãy chọn đúng định dạng:

Định dạng JSON (khuyến nghị cho hầu hết trường hợp): Dùng khi bạn cần dữ liệu cụ thể từ một trang. Định nghĩa một schema dựa trên những gì bạn cần trích xuất. Điều này giữ phản hồi nhỏ và tránh tràn cửa sổ ngữ cảnh.
Định dạng Markdown (dùng tiết kiệm): 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`)

Scrape 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 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 (dùng các lệnh gọi scrape lặp lại cho URL đã biết, hoặc map + scrape để khám phá URL trước, hoặc crawl cho toàn bộ nội dung trang)
Khi bạn không chắc trang nào chứa thông tin (dùng search)

Lỗi thường gặp:

Truyền một 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 thực sự cần một thao tác API hàng loạt, hãy dùng endpoint batch của API Firecrawl bên ngoài MCP.
Dùng định dạng markdown theo mặc định (dùng định dạng JSON để chỉ trích xuất những gì bạn cần).

Chọn đúng định dạng:

Định dạng JSON (ưu tiên): Với hầu hết trường hợp sử dụng, dùng định dạng JSON với một schema để chỉ trích xuất dữ liệu cụ thể cần thiết. Điều này giữ phản hồi tập trung và ngăn tràn cửa sổ ngữ cảnh.
Định dạng Markdown: Chỉ khi tác vụ thực sự cần 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ụ câu lệnh:

"Lấy thông tin 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 che giấu. Với CLOUD_SERVICE=true: scrape chỉ đọc. Nó không nhận actions trình duyệt và không thể chấp nhận điều khoản của nhà cung cấp. Một profile được đặt tên sẽ tải trạng thái trình duyệt đã lưu mà không lưu thay đổi vào đó, và firecrawl_search của endpoint đầy đủ xử lý scrapeOptions.profile theo cùng cách. Để lưu trạng thái trình duyệt vào một hồ sơ, hãy mở trang với firecrawl_interact (xem bên dưới). Quản trị viên tổ chức chấp nhận điều khoản trong bảng điều khiển.

Trả về:

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

2. Công cụ Map (`firecrawl_map`)

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

Tốt nhất cho:

Khám phá URL trên một trang web trước khi quyết định scrape 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 (dùng scrape)
Khi bạn cần nội dung của các trang (dùng scrape sau khi map)

Lỗi thường gặp:

Dùng crawl để khám phá URL thay vì map

Ví dụ câu lệnh:

"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 tìm thấy trên trang web

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.

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 liên quan 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 (dùng scrape)
Khi bạn cần phạm vi bao phủ toàn diện của một trang web (dùng map hoặc crawl)

Lỗi thường gặp:

Dùng crawl hoặc map cho các câu hỏi mở (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"
  }
}

Để lấy toàn văn của một vài kết quả trong cùng một lệnh gọi, thêm "scrapeOptions": { "formats": ["markdown"], "onlyMainContent": true }. Mỗi kết quả được tải về sẽ được tính phí như một lần scrape, vì vậy với hầu hết câu hỏi, hãy dùng các đoạn trích và chỉ firecrawl_scrape những URL bạn cần.

Đặ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ữ các đoạn trích tìm kiếm gốc. Bỏ qua nó để dùng hành vi mặc định của API.

Thêm "sources": ["alexandria"] để khám phá công cụ theo ngữ nghĩa trong data.tools, tùy chọn kết hợp với web/news/images. Truy vấn là bắt buộc. Dùng firecrawl_find_tools để tra cứu theo ngữ cảnh và tiết lộ dần dần; xem Alexandria Tools.

Đối với bài báo khoa học, xem Research Tools: 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 kết quả web thông thường theo các trang web liên kết với nghiên cứu.

Trả về:

Kết quả tìm kiếm được nhóm theo nguồn (data.web, data.images, data.news), với nội dung scrape tùy chọn, cùng với trường id. Mỗi kết quả mang một source và một position được đánh số từ 1, được đánh số từ 1 trong nhóm riêng của nó — hãy sao chép cặp này thẳng vào valuableResults của firecrawl_search_feedback thay vì đếm các phần tử mảng. Truyền id đó cho firecrawl_search_feedback sau khi bạn đã 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ụ câu lệnh:

"So sánh 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ề một kết quả firecrawl_search trước đó. Phản hồi đầu tiên cho mỗi search id sẽ 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. Có tính idempotent theo search id.

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

Từ chối tham gia: đặ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ý, nên các tác nhân không thể gọi nó. Quản trị viên nhóm cũng có thể tắt phản hồi phía máy chủ; trong trường hợp đó, công cụ vẫn đượ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 gồm các phần nội dung cụ thể mà agent mong đợi tìm thấy nhưng không có. Mỗi mục tương ứng với một chủ đề bị thiếu; các mục này được tổng hợp trên toàn bộ các nhóm và cho chúng ta biết nên lập chỉ mục gì tiếp theo. Để có kết quả hữu ích, hãy dùng valuableResults với cặp source/position được đánh dấu trên từng kết quả — các kết quả được nhóm lại và mỗi nhóm được đánh số từ 1 một cách độc lập, vì vậy cả hai đều bắt buộc. Liệt kê mọi kết quả hữu ích (các kết quả không được liệt kê sẽ bị coi là không hữu ích), và dành valuableSources cho các URL hữu ích không nằm trong số các kết quả được trả về.

Giới hạn hoàn tiền hàng ngày (theo nhóm, theo ngày UTC, mặc định 100 credit). Khi creditsRefundedToday của một nhóm đạt dailyRefundCap, các lần gửi tiếp theo vẫn ghi nhận phản hồi nhưng không hoàn credit nữa. Phản hồi sẽ đặt dailyCapReached: true. 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",
    "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'"
  }
}

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 job endpoint v2 đã hoàn thành thông qua /v2/feedback. Dùng công cụ này cho phản hồi ở cấp endpoint đối với các job scrape, parse, map hoặc search. Riêng về 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 dành riêng cho tìm kiếm.

Giữ phản hồi ngắn gọn: dùng mã vấn đề, 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 tham gia: đặt FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 (hoặc FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1) trong môi trường khi khởi động MCP server. Công cụ firecrawl_feedback sẽ không được đăng ký, nên 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?, websiteCapReached?, alreadySubmitted?, warning? }.

4. Công cụ Crawl (`firecrawl_crawl`)

Khởi động một job crawl, 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 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 đơn lẻ (dùng scrape)
Khi giới hạn token là mối lo ngại (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. Hãy giới hạn độ sâu crawl và số trang, hoặc 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)
Dùng crawl cho một trang đơn lẻ (thay vào đó hãy dùng scrape)

Ví dụ prompt:

"Lấy tất cả bài viết 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. Dùng id được trả về với firecrawl_check_crawl_status nếu bạn cần kiểm tra lại job 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 job 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 job 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ữ bằng 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. Endpoint được lưu trữ sử dụng luồng tải lên 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 (dùng scrape), nhiều tệp trong một lần 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 ảnh màn hình và nhấp chuột.

Endpoint được lưu trữ: nó không thể đọc hệ thống tệp của bạn. 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 lại firecrawl_parse với uploadRef được trả về. Bước tải lên yêu cầu xác thực Firecrawl hoặc gói không cần khóa. Ở 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ột server cục bộ chỉ có API key đá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ữ kèm nextToolCall.

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

Để lấy dữ liệu có cấu trúc từ một trang đã biết, hãy 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 chưa được biết hoặc dữ liệu trải rộng trên nhiều trang web, hãy dùng firecrawl_agent để 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 web. Mô tả các trường bạn cần, tùy chọn truyền JSON schema và URL hạt giống, 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. Dùng nó 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 để tiếp cận dữ liệu. Đối với một URL đã biết, hãy 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 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 bất đồng bộ - nó trả về ID job 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ả.

Quy trình bất đồng bộ:

Gọi firecrawl_agent với prompt/schema của bạn → trả về ID job
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)
Thăm dò firecrawl_agent_status với ID job để kiểm tra tiến độ
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 đa nguồn
Tìm thông tin phân tán khắp 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:

Scrape một trang đơn giản khi bạn biết URL (dùng scrape với định dạng JSON - nhanh hơn và rẻ hơn)

Đối 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 agent vào các trang cụ thể
schema: JSON schema tùy chọn cho đầu ra có cấu trúc
effort: Tùy chọn. Ngân sách suy luận "low", "medium" hoặc "high" cho tác vụ agent.
maxCredits: Số nguyên dương tùy chọn. Giới hạn chi tiêu tính bằng credit cho lần chạy này. API mặc định là 2.500 khi bỏ qua, và giới hạn một yêu cầu miễn phí ở mức 2.500.
strictConstrainToURLs: Boolean tùy chọn. Nếu true, agent chỉ truy cập các URL trong urls.
threadId: Tùy chọn. Tiếp tục một luồng hiện có: threadId từ kết quả firecrawl_agent hoặc firecrawl_agent_status trước đó. Bỏ qua để bắt đầu một luồng mới. Trong một lần theo dõi, các cài đặt mode, urls, schema và exchange bị bỏ qua sẽ được kế thừa từ lượt trước.
mode: Tùy chọn. "extract" (mặc định) trả về kết quả có cấu trúc đầy đủ mỗi lượt. "chat" cho phép một lần theo dõi không yêu cầu dữ liệu mới nhận được câu trả lời ngắn trong message thay vì chạy lại; exchange.requireApproval cần nó.
exchange: Tùy chọn. Cài đặt nhà cung cấp Alexandria cho lượt này, được chuyển nguyên trạng đến POST /v2/agent:
- enabled, toolkits (tối đa 5 slug nhà cung cấp), maxCalls (1 đến 30), requireApproval (các cuộc gọi trả phí kết thúc lượt với pendingApproval; cần mode: "chat" trong cùng lần gọi, kể cả trong một lần theo dõi)
- onTermsRequired: việc cần làm khi một nhà cung cấp Alexandria mà agent sẽ dùng cần điều khoản dữ liệu mà nhóm của bạn chưa chấp nhận. Các nhà cung cấp bị hạn chế không bao giờ được gọi trong bất kỳ chế độ nào. Bỏ qua trong một lần theo dõi sẽ giữ giá trị của lượt trước.
  - "skip" (mặc định): trả lời chỉ với các nhà cung cấp đã được chấp nhận. exchange.skippedProviders trên kết quả trạng thái liệt kê các nhà cung cấp bị hạn chế lẽ ra sẽ hữu ích.
  - "ask": tương tự, cộng thêm một pendingApproval điều khoản và exchange.requiresAction với ID phê duyệt và yêu cầu của nhà cung cấp. Đọc điều khoản với terms/show; quản trị viên tổ chức chấp nhận chúng trong bảng điều khiển Firecrawl.
- approve: { approvalId, callIds?, always? } trả lời có cho pendingApproval mà lượt trước đã kết thúc. callIds và always chỉ áp dụng cho phê duyệt cuộc gọi trả phí.
- decline: { approvalId } trả lời không. Một đề nghị điều khoản bị từ chối sẽ giữ các nhà cung cấp đó ngoài phần còn lại của luồng.
- approve và decline cần threadId, và chỉ một trong số chúng có thể được gửi.

Điều khoản nhà cung cấp (chế độ hỏi): không có chế độ tự động chấp nhận. Khi một lượt kết thúc bằng một đề nghị điều khoản, kết quả trạng thái mang pendingApproval (kind: "terms") và exchange.requiresAction với approvalId và yêu cầu của nhà cung cấp. Bất kỳ mô tả terms/accept nào trong payload API đó đều không khả dụng thông qua MCP. Để sử dụng nhà cung cấp:

Hiển thị cho người dùng các điều khoản (terms/show đến firecrawl_scrape với alexandria).
Hướng dẫn quản trị viên tổ chức chấp nhận các điều khoản tại URL của nhà cung cấp, hoặc cài đặt nguồn dữ liệu. Một yêu cầu dữ liệu không phải là sự đồng ý.
Chờ quản trị viên xác nhận chấp nhận trong bảng điều khiển.
Tiếp tục cùng luồng: gọi firecrawl_agent với cùng threadId và exchange.approve: { "approvalId": "..." }. Thao tác này tiếp tục nghiên cứu và không chấp nhận điều khoản.

Nếu người dùng nói không, hãy gọi firecrawl_agent với cùng threadId và exchange.decline: { "approvalId": "..." } thay thế.

Ví dụ prompt:

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

Ví dụ sử dụng (khởi động 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 bằng ID job đượ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"
  }
}

Ví dụ sử dụng (theo dõi trên cùng luồng):

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

Ví dụ sử dụng (tiếp tục luồng sau khi quản trị viên đã xác nhận chấp nhận trong bảng điều khiển):

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

Trả về:

ID job để kiểm tra trạng thái, cùng với threadId và threadTurn. 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 job agent và lấy kết quả khi hoàn thành. Dùng công cụ này để thăm dò kết quả sau khi khởi động agent.

Mẫu thăm dò: Nghiên cứu của agent có thể mất vài phút cho các truy vấn phức tạp. Hãy 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: Agent vẫn đang nghiên cứu - hãy kiểm tra lại sau
completed: Nghiên cứu đã hoàn tất - 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 liệu, đ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 đã lỗi thời.

Các tùy chọn sử dụng:

Truyền url để scrape 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 đã scrape hiện có.
Để lưu trạng thái trình duyệt (cookie, localStorage) vào một hồ sơ có tên, hãy truyền url với scrapeOptions: { "profile": { "name": "my-profile", "saveChanges": true } }. Trạng thái được lưu khi firecrawl_interact_stop kết thúc phiên.
Truyền đúng 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 được suy ra để theo dõi hoặc dọn dẹp.

11. Công cụ Stop Interact (`firecrawl_interact_stop`)

Dừng một phiên interact cho một trang đã scrape khi bạn đã tương tác xong.

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

12. Các 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.

Bao gồm: tóm tắt và toàn văn bài báo trong lĩnh vực y sinh, khoa học sự sống và tài liệu 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 khả dụng:

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 bộ lọc tùy chọn theo tác giả, danh mục và ngày tháng.
firecrawl_research_inspect_paper: truy xuất siêu dữ liệu chuẩn tắc 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 neo 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: quy trình đánh giá tài liệu, tra cứu bài báo và khám phá kho lưu trữ khi tác nhân cần một bề mặt nghiên cứu chuyên biệt thay vì tìm kiếm web thông thường.

firecrawl_search với categories: ["research"] là một bề mặt khác: nó lọc kết quả web thông thường thành các trang web liên kết với nghiên cứu và trả về đoạn trích 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, vì chúng sẽ làm nổi bật 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 trình giám sát trang định kỳ. Trình giám sát chạy 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 lưu giữ gần nhất, 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ề những thay đổi có ý nghĩa bằng mục tiêu ngôn ngữ đơn giản
Theo dõi lịch sử kiểm tra và so sánh ở 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 mọi phạm vi người dùng đã đưa ra, và chỉ bao gồm các loại trừ dành riêng cho ý đị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à giao diện trang không liên quan đã được bộ đánh giá xử lý, vì vậy đừng lặp lại chúng 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 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 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 (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 cho 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 issue GitHub, pull request đã hợp nhất, README của kho lưu trữ và tài liệu mã.

Phù hợp nhất cho: một câu hỏi lập trình: hành vi mã, một thư viện hoặc framework, một hợp đồng API, một thông báo lỗi hoặc một 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 dành cho 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ề: Các kết quả được xếp hạng. Mỗi kết quả mang một ID, một loại nguồn (issue, pull_request, readme hoặc doc), một URL, một 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 chỉ mục bên cạnh kết quả web. Thay vào đó, hãy sử dụng công cụ này 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ự cũng áp dụng ở đó.

14b. Công cụ tìm kiếm chỉ mục chính phủ (`firecrawl_gov_search`)

Tìm kiếm tài liệu pháp luật và quy định chính từ các nguồn chính phủ liên bang, tiểu bang và địa phương của Hoa Kỳ: luật, quy định, bộ luật, ý kiến tòa án và các ấn phẩm chính phủ khác.

Phù hợp nhất cho: một câu hỏi pháp lý hoặc quy định cần văn bản điều chỉnh hoặc một nguồn chính phủ chính thức.

Đối số:

{
  "name": "firecrawl_gov_search",
  "arguments": {
    "query": "excessive force claims against police officers",
    "k": 10,
    "courtType": "federal-appellate",
    "cites": "42 U.S.C. § 1983"
  }
}

query (bắt buộc): câu hỏi hoặc cụm từ tìm kiếm pháp lý hoặc quy định.
k: số lượng kết quả được xếp hạng. Mặc định là 10 và tối đa là 100.
jurisdiction: chỉ giữ các trang của một khu vực tài phán: "us" cho liên bang, hoặc "us-" cộng với mã hai chữ cái của tiểu bang hoặc lãnh thổ, chẳng hạn như "us-ca" hoặc "us-dc".
court: chỉ giữ các trang được gắn nhãn cho một tòa án, theo ID tòa án của CourtListener, chẳng hạn như "scotus", "ca9" hoặc "nysd".
courtType: chỉ giữ các trang từ một loại tòa án: federal-supreme, federal-appellate, federal-district, federal-bankruptcy, federal-special, military, state-supreme, state-appellate, state-trial, state-special hoặc state-attorney-general.
cites: chỉ giữ các trang trích dẫn một luật hoặc vụ án, dưới dạng trích dẫn in như "42 U.S.C. § 1983" hoặc "5 U.S. 137", hoặc ID trích dẫn như "us:usc:42:1983".
domain: chỉ giữ các trang từ một trang web, chẳng hạn như "irs.gov".

Các bộ lọc là tùy chọn và kết hợp với nhau: một kết quả phải khớp với mọi bộ lọc được đặt. Bộ lọc chỉ giữ các trang mà chỉ mục đã gắn nhãn, vì vậy một tìm kiếm có lọc có thể bỏ sót các trang liên quan, và không có kết quả không có nghĩa là không tồn tại. Nhãn tòa án đầy đủ nhất đối với các tòa án liên bang và các bộ sưu tập án lệ.

Trả về: Các kết quả được xếp hạng. Mỗi kết quả mang một vị trí, một tiêu đề, một URL và đoạn trích khớp. Điểm cuối chỉ tìm kiếm cũng hiển thị công cụ này.

firecrawl_search với categories: ["gov"] tìm kiếm cùng các nguồn và trả về các kết quả trúng trong data.web với category: "gov". Danh mục gov không nhận các bộ lọc này và không thể kết hợp với các danh mục khác.

15. Công cụ Alexandria

Firecrawl Alexandria là một danh mục các nhà cung cấp dữ liệu có thể truy cập thông qua API Firecrawl với khóa API Firecrawl trên một nhóm có quyền truy cập Alexandria. Các phiên không có khóa (được lưu trữ hoặc cục bộ) nhận được Alexandria requires an API key on a team with Alexandria access; các công cụ khám phá Alexandria không được liệt kê cho các phiên không có khóa được lưu trữ.

Khám phá ngữ nghĩa (firecrawl_search):

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

data.tools mặc định là các gợi ý ngắn gọn với nhà cung cấp, khả năng và mô tả. Đặt toolDetail: "summary" cho siêu dữ liệu và điều hướng, hoặc toolDetail: "full" cho các hợp đồng bao gồm đầu vào, trường phản hồi và ví dụ. domainTools: true thêm các kết quả khớp theo ngữ cảnh vào các đề cập truy vấn và URL kết quả trong cùng mảng đó. Kiểm tra warning để biết khám phá không khả dụng. Tìm kiếm yêu cầu một truy vấn và không chấp nhận các bộ lọc duyệt danh mục. Khám phá này hoạt động trên cả bề mặt MCP đầy đủ và chỉ tìm kiếm.

Tiết lộ dần dần (firecrawl_find_tools):

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

Bắt đầu không có đối số để xem các danh mục, sau đó thu hẹp dần danh mục:

Đối số	Kết quả
`{}`	Các danh mục và mô tả ngắn
`{"categories":["podcasts"]}`	Các nhà cung cấp trong danh mục đó
`{"categories":["podcasts"],"providers":["particle"]}`	Tên và mô tả công cụ ngắn gọn
`{"providers":["particle"],"capabilities":["podcasts/episodes/search"]}`	Đầu vào, ràng buộc, phản hồi và ví dụ đầy đủ đã chọn

Không cần nhảy nhóm. level rõ ràng hỗ trợ categories, providers, groups hoặc tools; expand rõ ràng chọn các phần hợp đồng. expand: [] giữ kết quả ngắn gọn ngay cả khi chọn một khả năng. Đối với các hợp đồng đầy đủ rộng, hãy yêu cầu rõ ràng level: "tools" và expand: ["options", "response", "examples"]. URL cung cấp khám phá theo ngữ cảnh mà không tải trang. Kết quả công cụ bỏ qua giá tín dụng theo từng khả năng trừ khi includeCosts: true được đặt; các đối số nextTool tiếp theo giữ nguyên điều đó.

Kết quả nằm trong data.alexandria[0].data. Theo dõi nextTool của một mục bằng cách gọi name của nó với arguments của nó; nextTool của trang sẽ tiến phân trang. Các đối tượng next hiện có vẫn là các lệnh gọi khám phá Alexandria có thể sử dụng thông qua firecrawl_scrape. Khám phá tốn không tín dụng và không bao giờ thực thi các công cụ nhà cung cấp. Đọc hợp đồng đầy đủ đã chọn trước khi thực thi.

Các điều khiển này yêu cầu triển khai API Alexandria phù hợp.

Thực thi (firecrawl_scrape với alexandria): truyền alexandria thay vì url (chính xác một trong hai; requestId và timeout cũng có thể được cung cấp). Chấp nhận một lệnh gọi duy nhất hoặc một mảng tối đa mười lệnh gọi.

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

Trả về: { success, scrape_id, requestId, data: { alexandria: [...], creditsCost } }. Mỗi mục là một kết quả (provider, capability, data, records, upstreamStatus) hoặc một error với code; lô không bao giờ thất bại toàn bộ vì lỗi nhà cung cấp và data.creditsCost là tổng số tiền được tính cho yêu cầu. Nội dung lỗi Alexandria (403 khi không có quyền truy cập Alexandria, và trạng thái thanh toán 402/409) được chuyển tiếp trong băng với code của chúng.

Thực thi tạo một x-request-id và trả về nó khi thành công hoặc thất bại. Thử lại cùng một tải trọng với requestId đó; không tạo ID mới sau một kết quả không chắc chắn. Tín dụng khả dụng được API kiểm tra.

Một nhà cung cấp Alexandria mà nhóm chưa chấp nhận điều khoản sẽ thất bại trước khi bất cứ điều gì chạy với HTTP 403 và nội dung này:

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

Kết quả công cụ chuyển tiếp nó dưới dạng lỗi với structuredContent mang code, status: 403, requestId, đối tượng requiresAction không thay đổi và next_actions (human_action_required rồi retry_same_request). Chấp nhận điều khoản là một hành động pháp lý, vì vậy quản trị viên tổ chức chấp nhận chúng trong bảng điều khiển Firecrawl, không thông qua MCP. Sử dụng lệnh gọi nextTool được trả về để đọc thỏa thuận thông qua firecrawl_scrape với alexandria: [{provider: "firecrawl", capability: "terms/show", options: {provider: "<provider>"}}], được gửi riêng khỏi thực thi nhà cung cấp, và trình bày nó cho người dùng. Sau đó quản trị viên tổ chức chấp nhận nó tại requiresAction.url, hoặc tại https://www.firecrawl.dev/app/settings?tab=data-sources. firecrawl_scrape từ chối mọi khả năng terms/* khác, vì vậy nó không thực hiện thay đổi tài khoản nào. Một yêu cầu dữ liệu không phải là sự đồng ý, và không có chấp nhận tự động hoặc thử lại không chắc chắn nào xảy ra. Không có tín dụng nào bị tính cho việc truy xuất bị chặn. Sau khi quản trị viên xác nhận chấp nhận, hãy gọi lại cùng công cụ với tải trọng giống hệt và requestId.

16. Công cụ sử dụng tín dụng

Công cụ yêu cầu tài khoản Firecrawl đã xác thực và chỉ đọc.

firecrawl_credit_usage mặc định là { "view": "current" } và trả về remainingCredits, planCredits, billingPeriodStart và billingPeriodEnd. Số tín dụng còn lại có thể vượt quá tín dụng của gói khi nhóm có thêm tín dụng bổ sung hoặc tín dụng được cấp.
Truyền { "view": "historical" } cho các kỳ theo tháng dương lịch chứa startDate, endDate và creditsUsed. Truyền { "byApiKey": true } cũng chọn chế độ xem lịch sử và chia các kỳ theo API key; mỗi dòng sau đó bao gồm apiKey. Thay vào đó, truyền { "byEndpoint": true } để chia các kỳ theo endpoint đã dùng tín dụng (scrape, search, crawl, map, agent, ...); mỗi dòng sau đó bao gồm endpoint. Truyền { "bin": "day" } để có một kỳ cho mỗi ngày UTC thay vì mỗi tháng dương lịch. Không kết hợp byApiKey với byEndpoint, hoặc bất kỳ tùy chọn nào trong số này với { "view": "current" }. endDate của kỳ mới nhất có thể là null. Nếu API Firecrawl chưa cung cấp tính năng chia theo endpoint hoặc kỳ theo ngày, kết quả sẽ kèm theo notice và các số liệu theo tháng.

Sử dụng lập trình (không ổn định)

Gói này cũng cung cấp một điểm vào thư viện để nhúng máy chủ vào một runtime khác. Nó không ổn định: API, các tùy chọn và kiểu của nó có thể thay đổi trong bất kỳ bản phát hành nào, kể cả bản phát hành minor và patch, vì vậy hãy ghim một phiên bản chính xác.

npm install --save-exact firecrawl-mcp zod

Ví dụ định nghĩa các tham số công cụ bằng zod, vì vậy dự án nhúng phải cài đặt nó như một dependency riêng.

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

Đặt host một cách rõ ràng. Nếu không có nó, máy chủ sẽ lắng nghe trên localhost, mà Node gắn với một địa chỉ duy nhất (thường chỉ là ::1), nên các yêu cầu tới 127.0.0.1 sẽ bị từ chối. Dùng 0.0.0.0 hoặc :: để chấp nhận kết nối từ các máy khác chỉ khi có kiểm soát truy cập mạng hoặc kiểm tra unstable_hooks.authenticate: nếu không có, mọi bên gọi có thể tiếp cận cổng đều được phục vụ với apiKey đã cấu hình.

Thư viện không kiểm tra Host hoặc Origin trừ khi được yêu cầu, và các header CORS của nó cho phép mọi origin. Một máy chủ có thể truy cập từ trình duyệt trên cùng máy nên truyền httpStream.allowedHosts (ví dụ ['localhost', '127.0.0.1', '[::1]']): các yêu cầu có header Host hoặc Origin chỉ định một host khác sẽ nhận 403 (trừ GET và HEAD trên đường dẫn health), và các header CORS sẽ phản chiếu origin được phép. Dòng lệnh đặt danh sách này trong chế độ HTTP cục bộ.

Các tùy chọn phản ánh các biến môi trường của CLI: apiUrl, apiKey, transport, logging, safeMode, fileAccess (local hoặc upload), requireCredential, searchFeedback và endpointFeedback. unstable_hooks chấp nhận:

Hook	Mục đích
`authenticate(request)`	Xác định phiên cho một yêu cầu; ném `Response` để từ chối.
`wrapTool(tool)`	Trang trí mọi công cụ đã đăng ký.
`onToolResult(event)`	Quan sát thời điểm bắt đầu và kết quả của mỗi lần gọi công cụ.
`instructions`	Hướng dẫn của máy chủ, hoặc một hàm chọn từ các giá trị mặc định.
`registerExtraTools(registrar, context)`	Thêm công cụ sau các công cụ tích hợp.
`outboundRequest(session)`	Thông tin xác thực và header bổ sung cho mỗi yêu cầu API Firecrawl.
`beforeKeylessRequest(session, origin)`	Từ chối yêu cầu không có key bằng cách ném lỗi.
`toolFilter(name)`	Loại bỏ các công cụ tích hợp khỏi instance.
`configureHttp(app)`	Thêm các route HTTP.
`oauth.protectedResource`	Phục vụ metadata tài nguyên được bảo vệ OAuth.

Máy chủ được xây dựng trên MCP TypeScript SDK chính thức (@modelcontextprotocol/server). Hãy dùng các kiểu được xuất từ firecrawl-mcp/server (Session, ToolDefinition, ToolRegistrar, FirecrawlMcpServerHooks và các kiểu khác) thay vì các kiểu của chính SDK.

Điểm vào cũng xuất các helper mà các công cụ tích hợp sử dụng, chẳng hạn như recoveryPayload, normalizeHeader, requestOrigin, isRuntimeUserAgent, initializeClientSlug, searchToolBaseFields, searchOutputSchema và structuredCompact, để các công cụ và hook bổ sung có thể khớp với hành vi tích hợp. Chúng cũng không ổn định.

Hệ thống ghi log

Máy chủ bao gồm ghi log toàn diện:

Trạng thái và tiến độ thao tác
Số liệu hiệu năng
Theo dõi giới hạn tốc độ
Các điều kiện lỗi

Ví dụ thông báo log:

[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ụ 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

Fork kho lưu trữ
Tạo nhánh tính năng của bạn
Chạy kiểm thử: npm test
Gửi pull request

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

Cảm ơn @vrknetha, @cawstudios vì bản 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

Dữ liệu có cấu trúc và kết quả lớn

Tìm kiếm đã xác thực mặc định trả về kết quả web, các công cụ Alexandria ngữ nghĩa và kết quả khớp tên miền. Hãy bắt đầu với câu hỏi thực tế. Dùng firecrawl_find_tools để tra cứu công cụ ngữ nghĩa trực tiếp, các hợp đồng đã chọn hoặc duyệt tuần tự: danh mục → nhà cung cấp → công cụ rút gọn → hợp đồng đã chọn. Thực thi công cụ thông qua firecrawl_scrape; việc scrape URL thông thường và tìm kiếm không bao giờ tự động thực thi công cụ của nhà cung cấp.

Đối với các hợp đồng đã chọn, hãy ưu tiên expand: ["options", "response"] và chỉ yêu cầu ví dụ khi hình dạng đầu vào chưa rõ. Hãy kiểm tra các khả năng liên quan cùng nhau và tái sử dụng các hợp đồng được trả về.

Đối với một kết quả quy trình có khả năng lớn, hãy cung cấp và giữ nguyên một requestId ở cấp cao nhất trước khi thực thi. ID đó vẫn khả dụng ngay cả khi máy khách từ chối phản hồi. Các lần scrape URL thông thường sử dụng ID scrape được trả về thay thế.

Đối với một kết quả quy trình hoặc scrape thông thường lớn được lưu giữ, hãy gọi firecrawl_scrape với:

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

Đọc stdout, stderr, exitCode và workspaceId trong data.alexandria[0].data. Tiếp tục với options: {workspaceId, command} để kiểm tra response.json bằng jq, hoặc document.md bằng các lệnh văn bản có giới hạn cho các lần scrape thông thường. Giữ đầu ra có chọn lọc. Việc tải nguồn phải là một lệnh gọi độc lập; ID nguồn lồng nhau của nó khác với ID yêu cầu thực thi cấp cao nhất. Các workspace hết hạn sau năm phút không hoạt động, và không phải mọi kết quả đều được lưu giữ (bao gồm cả ZDR và payload quy trình của nhà cung cấp API). ID tìm kiếm không được hỗ trợ.

Đối với các nguồn quy trình, response.json giữ nguyên phong bì API: chọn .data.alexandria[].data, sau đó chọn response.key của hợp đồng đã chọn khi không rỗng. Kết hợp các số đếm và phép chiếu liên quan trong một lệnh Bash khi đã biết hình dạng đó, thay vì kiểm tra các khóa lặp đi lặp lại.

Các phản hồi thực thi Alexandria thành công trên 20.000 token ước tính (byte UTF-8 đã tuần tự hóa chia cho bốn) sẽ trả về một bàn giao nhỏ sau khi Bash từ xa xác nhận toàn bộ lô có thể truy cập được. Làm theo nextTool để kiểm tra dữ liệu được lưu giữ. Điều này thêm một lệnh gọi Bash và khởi tạo một workspace với TTL không hoạt động năm phút. Toàn bộ payload được giữ nguyên. Nếu xác nhận thất bại, phản hồi gốc vẫn được giữ nguyên tại chỗ. Tìm kiếm, scrape URL thông thường, phản hồi lỗi và các lệnh gọi tiện ích Firecrawl không thay đổi. Ngân sách phân phối này không đo lường ngữ cảnh còn lại của máy khách; không có bộ nhớ đệm kết quả cục bộ theo tiến trình nào được thêm vào. Khi có sẵn các công cụ hệ thống tệp cục bộ, việc lưu đầu ra CLI và đọc các phần đã chọn là một lựa chọn khác.

Trình tự khám phá của CLI ánh xạ tới các lệnh gọi MCP sau:

Mục đích	Công cụ	Đối số
Công cụ web + ngữ nghĩa + tên miền	`firecrawl_search`	`{"query":"<user question>"}`
Chỉ công cụ ngữ nghĩa	`firecrawl_search`	`{"query":"<user question>","sources":["alexandria"]}`
Danh mục	`firecrawl_find_tools`	`{}`
Nhà cung cấp trong một danh mục	`firecrawl_find_tools`	`{"categories":["<category-id>"]}`
Công cụ nhà cung cấp rút gọn	`firecrawl_find_tools`	`{"providers":["<provider-id>"]}`
Hợp đồng đã chọn	`firecrawl_find_tools`	`{"providers":["<provider-id>"],"capabilities":["<capability-id>"]}`
Thực thi	`firecrawl_scrape`	`{"alexandria":{"provider":"<provider-id>","capability":"<capability-id>","options":{"<required-field>":"<value>"}}}`

Tìm công cụ và thực thi đều có sẵn trên cả bề mặt đầy đủ và bề mặt tìm kiếm. Tái sử dụng một hợp đồng hoàn chỉnh từ tìm kiếm khi có sẵn thay vì thực hiện một lệnh gọi khám phá khác. Chỉ làm theo điều hướng nextTool được trả về khi cần thêm kết quả.

Phản hồi phiên Alexandria

Công cụ firecrawl_feedback hiện có chấp nhận 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 tùy chọn là mục tiêu cơ bản của phiên: điều mà agent hoặc người dùng của nó cuối cùng đang cố gắng hoàn thành, vượt ra ngoài một trang web duy nhất trong requestedWebsite.

Điều này sử dụng POST /v2/feedback đã xác thực, không có job ID. Nó phải đến trong vòng 20 phút kể từ lần tìm kiếm, khám phá hoặc thực thi Alexandria gần nhất của nhóm; phản hồi muộn hơn sẽ bị từ chối với FEEDBACK_WINDOW_EXPIRED. Phản hồi đủ điều kiện có thể hoàn lại 1 tín dụng, tùy thuộc vào giới hạn hàng ngày là 10 tín dụng mỗi trang web và 100 tín dụng mỗi nhóm (ngày UTC). Vượt quá một trong hai giới hạn, phản hồi vẫn được ghi lại mà không hoàn tiền, và phản hồi sẽ đặt websiteCapReached hoặc dailyCapReached. Các mảng providerFeedback và capabilityFeedback tùy chọn mô tả các khoảng trống về phạm vi và vấn đề thực thi; schema của công cụ liệt kê các giá trị vấn đề được hỗ trợ. new_capability_request yêu cầu requestedFunctionality; missing_capability (nhà cung cấp tồn tại nhưng thiếu khả năng) thì không. Các kiểm soát từ chối phản hồi và xác thực hiện có vẫn được áp dụng.

Các kết quả thực thi và khám phá Alexandria đủ điều kiện bao gồm một con trỏ feedbackTool với tên công cụ và một khung đối số. Con trỏ bị bỏ qua đối với các lệnh gọi nội bộ Firecrawl như bash và khi firecrawl_feedback chưa được đăng ký (FIRECRAWL_NO_ENDPOINT_FEEDBACK hoặc khởi động không có key).

Firecrawl MCP

Bạn có thể làm gì với Firecrawl MCP?

Tài liệu

Máy chủ Firecrawl MCP

Tính năng

Khi nào nên dùng máy chủ này

Cài đặt

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

Đặt tên cho tích hợp của bạn

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

Chạy với npx

Cài đặt thủ công

Chạy trên Cursor

Chạy trên Windsurf

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

Chạy với Docker

Chạy trên VS Code

Cấu hình

Biến môi trường

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

Chế độ HTTP cục bộ

MCP OAuth (Bearer access tokens)

CLOUD_SERVICE=true

Ví dụ cấu hình

Sử dụng với Claude Desktop

Cách chọn công cụ

Bảng tham chiếu nhanh

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

Các công cụ có sẵn

1. Công cụ Scrape (firecrawl_scrape)

2. Công cụ Map (firecrawl_map)

3. Công cụ Search (firecrawl_search)

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

3c. Công cụ phản hồi chung (firecrawl_feedback)

4. Công cụ Crawl (firecrawl_crawl)

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

6. Công cụ Parse (firecrawl_parse)

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

8. Công cụ Agent (firecrawl_agent)

9. Kiểm tra trạng thái Agent (firecrawl_agent_status)

10. Công cụ Interact (firecrawl_interact)

11. Công cụ Stop Interact (firecrawl_interact_stop)

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

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

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

14b. Công cụ tìm kiếm chỉ mục chính phủ (firecrawl_gov_search)

15. Công cụ Alexandria

16. Công cụ sử dụng tín dụng

Sử dụng lập trình (không ổn định)

Hệ thống ghi log

Xử lý lỗi

Phát triển

Đóng góp

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

Giấy phép

Dữ liệu có cấu trúc và kết quả lớn

Phản hồi phiên Alexandria

`CLOUD_SERVICE=true`

1. Công cụ Scrape (`firecrawl_scrape`)

2. Công cụ Map (`firecrawl_map`)

3. Công cụ Search (`firecrawl_search`)

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

3c. Công cụ phản hồi chung (`firecrawl_feedback`)

4. Công cụ Crawl (`firecrawl_crawl`)

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

6. Công cụ Parse (`firecrawl_parse`)

8. Công cụ Agent (`firecrawl_agent`)

9. Kiểm tra trạng thái Agent (`firecrawl_agent_status`)

10. Công cụ Interact (`firecrawl_interact`)

11. Công cụ Stop Interact (`firecrawl_interact_stop`)

12. Các công cụ nghiên cứu (`firecrawl_research_*`)

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

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

14b. Công cụ tìm kiếm chỉ mục chính phủ (`firecrawl_gov_search`)