Firecrawl MCP Server

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.

Tài liệu

Firecrawl MCP Server

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

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

Tính năng

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

Hãy thử nghiệm với 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.

Cài đặt

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+ Để có 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 trong Cursor

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

Mở Cài đặt Cursor
Vào Tính năng > Máy chủ MCP
Nhấp "+ Thêm máy chủ MCP toàn cục mới"

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

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

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

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

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

Chạy trên Windsurf

Thêm phầ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ủ sử dụng HTTP có thể truyền phát cục bộ thay vì truyền tải stdio mặc định:

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

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

Cài đặt qua Smithery (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 lần 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, thêm khối JSON sau vào tệp Cài đặt Người dùng (JSON) trong VS Code. Bạn có thể làm điều này bằng cách nhấn Ctrl + Shift + P và nhập Preferences: Open User Settings (JSON).

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Firecrawl API Key",
        "password": true
      }
    ],
    "servers": {
      "firecrawl": {
        "command": "npx",
        "args": ["-y", "firecrawl-mcp"],
        "env": {
          "FIRECRAWL_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

Tùy chọn, bạn có thể thêm nó vào 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 sẽ cho phép bạn chia sẻ cấu hình với người khác:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Firecrawl API Key",
      "password": true
    }
  ],
  "servers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "${input:apiKey}"
      }
    }
  }
}

Cấu hình

Biến môi trường

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

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

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

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

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

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

Cấu hình tùy chọn

Cấu hình thử lại

FIRECRAWL_RETRY_MAX_ATTEMPTS: Số lần thử lại tối đa (mặc định: 3)
FIRECRAWL_RETRY_INITIAL_DELAY: Độ trễ ban đầu tính bằng mili giây trước lần thử lại đầu tiên (mặc định: 1000)
FIRECRAWL_RETRY_MAX_DELAY: Độ trễ tối đa tính bằng mili giây giữa các lần thử lại (mặc định: 10000)
FIRECRAWL_RETRY_BACKOFF_FACTOR: Hệ số nhân lùi theo cấp số nhân (mặc định: 2)

Giám sát sử dụng tín dụng

FIRECRAWL_CREDIT_WARNING_THRESHOLD: Ngưỡng cảnh báo sử dụng tín dụng (mặc định: 1000)
FIRECRAWL_CREDIT_CRITICAL_THRESHOLD: Ngưỡng quan trọng sử dụng tín dụng (mặc định: 100)

Ví dụ cấu hình

Đối với việc sử dụng API đám mây với thử lại tùy chỉnh và giám sát tín dụng:

# Required for cloud API
export FIRECRAWL_API_KEY=your-api-key

# Optional retry configuration
export FIRECRAWL_RETRY_MAX_ATTEMPTS=5        # Increase max retry attempts
export FIRECRAWL_RETRY_INITIAL_DELAY=2000    # Start with 2s delay
export FIRECRAWL_RETRY_MAX_DELAY=30000       # Maximum 30s delay
export FIRECRAWL_RETRY_BACKOFF_FACTOR=3      # More aggressive backoff

# Optional credit monitoring
export FIRECRAWL_CREDIT_WARNING_THRESHOLD=2000    # Warning at 2000 credits
export FIRECRAWL_CREDIT_CRITICAL_THRESHOLD=500    # Critical at 500 credits

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

# Custom retry configuration
export FIRECRAWL_RETRY_MAX_ATTEMPTS=10
export FIRECRAWL_RETRY_INITIAL_DELAY=500     # Start with faster retries

Sử dụng với Claude Desktop

Thêm phầ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",

        "FIRECRAWL_RETRY_MAX_ATTEMPTS": "5",
        "FIRECRAWL_RETRY_INITIAL_DELAY": "2000",
        "FIRECRAWL_RETRY_MAX_DELAY": "30000",
        "FIRECRAWL_RETRY_BACKOFF_FACTOR": "3",

        "FIRECRAWL_CREDIT_WARNING_THRESHOLD": "2000",
        "FIRECRAWL_CREDIT_CRITICAL_THRESHOLD": "500"
      }
    }
  }
}

Cấu hình hệ thống

Máy chủ bao gồm một số tham số có thể cấu hình có thể được đặt qua biến môi trường. Dưới đây là các giá trị mặc định nếu không được cấu hình:

const CONFIG = {
  retry: {
    maxAttempts: 3, // Number of retry attempts for rate-limited requests
    initialDelay: 1000, // Initial delay before first retry (in milliseconds)
    maxDelay: 10000, // Maximum delay between retries (in milliseconds)
    backoffFactor: 2, // Multiplier for exponential backoff
  },
  credit: {
    warningThreshold: 1000, // Warn when credit usage reaches this level
    criticalThreshold: 100, // Critical alert when credit usage reaches this level
  },
};

Các cấu hình này kiểm soát:

Hành vi thử lại
- Tự động thử lại các yêu cầu thất bại do giới hạn tốc độ
- Sử dụng lùi theo cấp số nhân để tránh làm quá tải API
- Ví dụ: Với cài đặt mặc định, các lần thử lại sẽ được thực hiện tại:
  - Lần thử lại thứ 1: độ trễ 1 giây
  - Lần thử lại thứ 2: độ trễ 2 giây
  - Lần thử lại thứ 3: độ trễ 4 giây (giới hạn ở maxDelay)
Giám sát sử dụng tín dụng
- Theo dõi mức tiêu thụ tín dụng API cho việc sử dụng API đám mây
- Cung cấp cảnh báo tại các ngưỡng được chỉ định
- Giúp ngăn chặn gián đoạn dịch vụ bất ngờ
- Ví dụ: Với cài đặt mặc định:
  - Cảnh báo khi còn 1000 tín dụng
  - Cảnh báo quan trọng khi còn 100 tín dụng

Giới hạn tốc độ và xử lý hàng loạt

Máy chủ sử dụng khả năng giới hạn tốc độ và xử lý hàng loạt tích hợp của Firecrawl:

Xử lý giới hạn tốc độ tự động với lùi theo cấp số nhân
Xử lý song song hiệu quả cho các hoạt động hàng loạt
Xếp hàng và điều tiết yêu cầu thông minh
Tự động thử lại cho các lỗi tạm thời

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 (các) URL chính xác bạn muốn:
- Cho một URL: sử dụng scrape (với định dạng JSON cho dữ liệu có cấu trúc)
- Cho nhiều URL: sử dụng batch_scrape
Nếu bạn cần khám phá các URL trên một trang web: sử dụng map
Nếu bạn muốn tìm kiếm thông tin trên web: sử dụng search
Nếu bạn cần nghiên cứu phức tạp trên nhiều nguồn không xác định: sử dụng agent
Nếu bạn muốn phân tích toàn bộ trang web hoặc một phần: sử dụng crawl (với 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 scrape + interact

Bảng tham khảo nhanh

Công cụ	Tốt nhất cho	Trả về
scrape	Nội dung trang đơn	JSON (ưu tiên) hoặc markdown
interact	Tương tác với một trang đã thu thập	Kết quả thực thi
batch_scrape	Nhiều URL đã biết	JSON (ưu tiên) hoặc markdown[]
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)	markdown/html[]
search	Tìm kiếm web để lấy thông tin	results[]
agent	Nghiên cứu phức tạp đa nguồn	JSON (dữ liệu có cấu trúc)

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

Khi sử dụng scrape hoặc batch_scrape, hãy 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 một lược đồ dựa trên những gì bạn cần trích xuất. Điều này giữ cho phản hồi nhỏ gọn và tránh tràn cửa sổ ngữ cảnh.
Định dạng Markdown (sử dụng hạn chế): Chỉ khi bạn thực sự cần nội dung toàn trang, chẳng hạn như đọc toàn bộ bài viết để tóm tắt hoặc phân tích cấu trúc trang.

Công cụ có sẵn

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

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

Tốt nhất cho:

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

Không khuyến nghị cho:

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

Lỗi thường gặp:

Sử dụng scrape cho một danh sách URL (thay vào đó hãy sử dụng batch_scrape).
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 một lược đồ để chỉ trích xuất dữ liệu cụ thể cần thiết. Điều này giữ cho phản hồi tập trung và ngăn tràn cửa sổ ngữ cảnh.
Định dạng Markdown: Chỉ khi nhiệm vụ thực sự yêu cầu nội dung toàn trang (ví dụ: tóm tắt toàn bộ bài viết, phân tích cấu trúc trang).

Ví dụ lời nhắc:

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

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

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

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

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

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

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

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

Trả về:

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

2. Công cụ Batch Scrape (`firecrawl_batch_scrape`)

Thu thập nhiều URL một cách hiệu quả với giới hạn tốc độ và xử lý song song tích hợp.

Tốt nhất cho:

Lấy nội dung từ nhiều trang, khi bạn biết chính xác những trang nào cần thu thập.

Không khuyến nghị cho:

Khám phá URL (sử dụng map trước nếu bạn không biết URL)
Thu thập một trang duy nhất (sử dụng scrape)

Lỗi thường gặp:

Sử dụng batch_scrape với quá nhiều URL cùng một lúc (có thể gặp giới hạn tốc độ hoặc tràn mã thông báo)

Ví dụ lời nhắc:

"Lấy nội dung của ba bài đăng blog này: [url1, url2, url3]."

Ví dụ sử dụng:

{
  "name": "firecrawl_batch_scrape",
  "arguments": {
    "urls": ["https://example1.com", "https://example2.com"],
    "options": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}

Trả về:

Phản hồi bao gồm ID hoạt động để kiểm tra trạng thái:

{
  "content": [
    {
      "type": "text",
      "text": "Batch operation queued with ID: batch_1. Use firecrawl_check_batch_status to check progress."
    }
  ],
  "isError": false
}

3. Kiểm tra trạng thái hàng loạt (`firecrawl_check_batch_status`)

Kiểm tra trạng thái của một hoạt động hàng loạt.

{
  "name": "firecrawl_check_batch_status",
  "arguments": {
    "id": "batch_1"
  }
}

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

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

Tốt nhất cho:

Khám phá URL trên một trang web trước khi quyết định thu thập 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ể nào bạn cần (sử dụng scrape hoặc batch_scrape)
Khi bạn cần nội dung của các trang (sử dụng scrape sau khi lập bản đồ)

Lỗi thường gặp:

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

Ví dụ lời nhắc:

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

Ví dụ sử dụng:

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

Trả về:

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

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

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

Tốt nhất cho:

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

Không khuyến nghị cho:

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

Lỗi thường gặp:

Sử dụng crawl hoặc map cho các câu hỏi mở (thay vào đó hãy sử dụng search)

Ví dụ sử dụng:

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

Trả về:

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

Ví dụ Prompt:

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

5b. 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 cho một kết quả firecrawl_search trước đó. Phản hồi đầu tiên cho mỗi id tìm kiếm sẽ hoàn lại 1 credit và cải thiện chất lượng tìm kiếm của Firecrawl. Idempotent theo 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 giúp ích gì). 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 biến 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 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ụ 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 các 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 — những dữ liệu này được tổng hợp trên các nhóm và cho chúng tôi biết cần lập chỉ mục gì tiếp theo.

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

5c. 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 đối với các công việc scrape, parse, map, hoặc search. Đối với chất lượng kết quả tìm kiếm cụ thể, nên dùng firecrawl_search_feedback vì nó bao gồm hướng dẫn riêng cho tìm kiếm.

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

Từ chối: đặt FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 (hoặc FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1) trong biến 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 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? }.

6. Công cụ Thu thập (`firecrawl_crawl`)

Bắt đầu một công việc thu thập không đồng bộ trên một trang web và trích xuất nội dung từ tất cả các trang.

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 quát toàn diện.

Không khuyến nghị cho:

Trích xuất nội dung từ một trang duy nhất (dùng công cụ thu thập đơn lẻ)
Khi giới hạn token là mối quan tâm (dùng map + batch_scrape)
Khi bạn cần kết quả nhanh (thu thập có thể chậm)

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

Lỗi thường gặp:

Đặt limit hoặc maxDepth quá cao (gây tràn token)
Dùng thu thập cho một trang duy nhất (hãy dùng công cụ thu thập đơn lẻ)

Ví dụ Prompt:

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

Ví dụ Sử dụng:

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

Trả về:

Phản hồi bao gồm ID thao tác để kiểm tra trạng thái:

{
  "content": [
    {
      "type": "text",
      "text": "Started crawl for: https://example.com/* with job ID: 550e8400-e29b-41d4-a716-446655440000. Use firecrawl_check_crawl_status to check progress."
    }
  ],
  "isError": false
}

7. Kiểm tra Trạng thái Thu thập (`firecrawl_check_crawl_status`)

Kiểm tra trạng thái của một công việc thu thập.

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

Trả về:

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

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

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

Phù hợp nhất cho:

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

Không khuyến nghị cho:

Khi bạn cần nội dung đầy đủ của một trang (dùng công cụ thu thập đơn lẻ)
Khi bạn không tìm kiếm dữ liệu có cấu trúc cụ thể

Tham số:

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

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

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

Ví dụ Sử dụng:

{
  "name": "firecrawl_extract",
  "arguments": {
    "urls": ["https://example.com/page1", "https://example.com/page2"],
    "prompt": "Extract product information including name, price, and description",
    "systemPrompt": "You are a helpful assistant that extracts product information",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "price": { "type": "number" },
        "description": { "type": "string" }
      },
      "required": ["name", "price"]
    },
    "allowExternalLinks": false,
    "enableWebSearch": false,
    "includeSubdomains": false
  }
}

Trả về:

Dữ liệu có cấu trúc đã trích xuất theo lược đồ của bạn

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

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

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

Cách hoạt động:

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

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

Gọi firecrawl_agent với prompt/lược đồ của bạn → trả về ID công việc
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)
Kiểm tra firecrawl_agent_status với ID công việc để theo dõi tiến độ
Khi trạng thái là "completed", phản hồi sẽ bao gồm dữ liệu đã trích xuất

Phù hợp nhất cho:

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

Không khuyến nghị cho:

Thu thập đơn giản một trang khi bạn biết URL (dùng công cụ thu thập đơn lẻ với định dạng JSON - nhanh hơn và rẻ hơn)

Tham số:

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

Ví dụ Prompt:

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

Ví dụ Sử dụng (khởi động agent, sau đó kiểm tra 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 đó kiểm tra với firecrawl_agent_status bằng ID công việ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. Dùng firecrawl_agent_status để kiểm tra kết quả.

10. 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. Dùng công cụ này để kiểm tra kết quả sau khi khởi động agent.

Mẫu kiểm tra: 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. Kiểm tra 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 - 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

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

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

Phù hợp nhất cho:

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

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

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

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

Viết mục tiêu dưới dạng hướng dẫn giám sát ngắn gọn 2-3 câu. Nêu rõ điều gì sẽ kích hoạt cảnh báo, giữ nguyên phạm vi người dùng đã đưa ra, và chỉ bao gồm các loại trừ cụ thể theo ý định khi rõ ràng từ yêu cầu. Các 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, metadata chung, và các thành phần trang không liên quan đã được trình đánh giá xử lý, vì vậy khô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. Nếu người dùng nói họ không quan tâm đến điều gì đó, hãy bao gồm điều đó một cách rõ ràng.

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

Nhiều trang với webhooks:

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

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

Truyền body khi bạn cần mục tiêu thu thập, theo dõi thay đổi JSON, thời gian 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ê giám sát.
firecrawl_monitor_get: lấy một 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_checks: liệt kê các lần kiểm tra, tùy chọn lọc theo trạng thái.
firecrawl_monitor_check: lấy kết quả cấp trang, bao gồm diff, snapshot, judgment.meaningful, và judgment.meaningfulChanges.

Hệ thống Ghi nhật ký

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

Trạng thái và tiến độ thao tác
Chỉ số hiệu suất
Giám sát sử dụng credit
Theo dõi giới hạn tốc độ
Các điều kiện lỗi

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

[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[INFO] Batch operation queued with ID: batch_1
[WARNING] Credit usage has reached warning threshold
[ERROR] Rate limit exceeded, retrying in 2s...

Xử lý Lỗi

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

Tự động thử lại cho các lỗi tạm thời
Xử lý giới hạn tốc độ với backoff
Thông điệp lỗi chi tiết
Cảnh báo sử dụng credit
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. Retrying in 2 seconds..."
    }
  ],
  "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ì đã 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

Firecrawl MCP Server

Tài liệu

Firecrawl MCP Server

Tính năng

Cài đặt

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ộ

Cài đặt qua Smithery (Kế thừa)

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

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

Cấu hình tùy chọn

Cấu hình thử lại

Giám sát sử dụng tín dụng

Ví dụ cấu hình

Sử dụng với Claude Desktop

Cấu hình hệ thống

Giới hạn tốc độ và xử lý hàng loạt

Cách chọn công cụ

Bảng tham khảo nhanh

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

Công cụ có sẵn

1. Công cụ Scrape (firecrawl_scrape)

2. Công cụ Batch Scrape (firecrawl_batch_scrape)

3. Kiểm tra trạng thái hàng loạt (firecrawl_check_batch_status)

4. Công cụ Map (firecrawl_map)

5. Công cụ Search (firecrawl_search)

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

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

6. Công cụ Thu thập (firecrawl_crawl)

7. Kiểm tra Trạng thái Thu thập (firecrawl_check_crawl_status)

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

9. Công cụ Agent (firecrawl_agent)

10. Kiểm tra Trạng thái Agent (firecrawl_agent_status)

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

Hệ thống Ghi nhật ký

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

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

2. Công cụ Batch Scrape (`firecrawl_batch_scrape`)

3. Kiểm tra trạng thái hàng loạt (`firecrawl_check_batch_status`)

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

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

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

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

6. Công cụ Thu thập (`firecrawl_crawl`)

7. Kiểm tra Trạng thái Thu thập (`firecrawl_check_crawl_status`)

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

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

10. Kiểm tra Trạng thái Agent (`firecrawl_agent_status`)

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