Firecrawl MCP Server

resmi

Menambahkan kemampuan web scraping dan pencarian yang kuat ke klien LLM seperti Cursor dan Claude.

Dokumentasi

Firecrawl MCP Server

Server Model Context Protocol (MCP) yang menghadirkan Firecrawl ke agen AI yang kompatibel dengan MCP — mencari, mengekstrak, dan berinteraksi dengan web langsung untuk konteks yang bersih dan siap digunakan agen.

Terima kasih banyak kepada @vrknetha, @knacklabs untuk implementasi awalnya!

Fitur

Mencari web dan mendapatkan konten halaman penuh
Mengekstrak URL apa pun menjadi data yang bersih dan terstruktur
Berinteraksi dengan halaman — klik, navigasi, dan operasikan
Riset mendalam dengan agen otonom
Percobaan ulang otomatis dan pembatasan laju
Dukungan cloud dan self-hosted
Dukungan SSE

Coba Server MCP kami di playground MCP.so atau di Klavis AI.

Instalasi

Menjalankan dengan npx

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

Instalasi Manual

npm install -g firecrawl-mcp

Menjalankan di Cursor

Mengonfigurasi Cursor 🖥️ Catatan: Memerlukan Cursor versi 0.45.6+ Untuk instruksi konfigurasi terbaru, silakan merujuk ke dokumentasi resmi Cursor tentang mengonfigurasi server MCP: Panduan Konfigurasi Server MCP Cursor

Untuk mengonfigurasi Firecrawl MCP di Cursor v0.48.6

Buka Pengaturan Cursor
Buka Fitur > Server MCP
Klik "+ Tambah server MCP global baru"

Masukkan kode berikut:

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

Untuk mengonfigurasi Firecrawl MCP di Cursor v0.45.6

Buka Pengaturan Cursor
Buka Fitur > Server MCP
Klik "+ Tambah Server MCP Baru"
Masukkan yang berikut:
- Nama: "firecrawl-mcp" (atau nama pilihan Anda)
- Tipe: "command"
- Perintah: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

Jika Anda menggunakan Windows dan mengalami masalah, coba cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"

Ganti your-api-key dengan kunci API Firecrawl Anda. Jika Anda belum memilikinya, Anda dapat membuat akun dan mendapatkannya dari https://www.firecrawl.dev/app/api-keys

Setelah menambahkan, segarkan daftar server MCP untuk melihat alat baru. Agen Composer akan secara otomatis menggunakan Firecrawl MCP saat sesuai, tetapi Anda dapat secara eksplisit memintanya dengan menjelaskan kebutuhan ekstraksi web Anda. Akses Composer melalui Command+L (Mac), pilih "Agent" di samping tombol kirim, dan masukkan kueri Anda.

Menjalankan di Windsurf

Tambahkan ini ke ./codeium/windsurf/model_config.json Anda:

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

Menjalankan dengan Mode Lokal HTTP Streamable

Untuk menjalankan server menggunakan HTTP Streamable secara lokal alih-alih transportasi stdio default:

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

Gunakan url: http://localhost:3000/mcp

Menginstal melalui Smithery (Legacy)

Untuk menginstal Firecrawl untuk Claude Desktop secara otomatis melalui Smithery:

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

Menjalankan di VS Code

Untuk instalasi satu klik, klik salah satu tombol instal di bawah ini...

Untuk instalasi manual, tambahkan blok JSON berikut ke file Pengaturan Pengguna (JSON) Anda di VS Code. Anda dapat melakukannya dengan menekan Ctrl + Shift + P dan mengetik 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}"
        }
      }
    }
  }
}

Secara opsional, Anda dapat menambahkannya ke file bernama .vscode/mcp.json di ruang kerja Anda. Ini akan memungkinkan Anda untuk berbagi konfigurasi dengan orang lain:

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

Konfigurasi

Variabel Lingkungan

Diperlukan untuk API Cloud

FIRECRAWL_API_KEY: Kunci API Firecrawl Anda
- Diperlukan saat menggunakan API cloud (default)
- Opsional saat menggunakan instance self-hosted dengan FIRECRAWL_API_URL
FIRECRAWL_API_URL (Opsional): Endpoint API kustom untuk instance self-hosted
- Contoh: https://firecrawl.your-domain.com
- Jika tidak disediakan, API cloud akan digunakan (memerlukan kunci API)

OAuth MCP (Token akses Bearer)

Firecrawl yang dihosting dapat menerbitkan token akses OAuth (fco_…) melalui server otorisasi di firecrawl.dev. Server MCP ini meneruskan kredensial mana pun yang diselesaikannya ke API Firecrawl sebagai Authorization: Bearer ….

Transportasi stream HTTP (CLOUD_SERVICE=true, HTTP_STREAMABLE_SERVER=true, atau SSE_LOCAL=true): Klien harus mengirim Authorization: Bearer <fco_access_token> pada permintaan MCP. Token bearer OAuth lebih diutamakan daripada x-firecrawl-api-key / x-api-key ketika keduanya ada.
stdio: Gunakan FIRECRAWL_OAUTH_TOKEN untuk token akses statis, atau tetap gunakan FIRECRAWL_API_KEY untuk kunci API.

Gunakan token akses (fco_…) saja. Token refresh (fcr_…) harus ditukar di endpoint token, tidak diteruskan ke API scrape/search.

Konfigurasi Opsional

Konfigurasi Percobaan Ulang

FIRECRAWL_RETRY_MAX_ATTEMPTS: Jumlah maksimum percobaan ulang (default: 3)
FIRECRAWL_RETRY_INITIAL_DELAY: Penundaan awal dalam milidetik sebelum percobaan ulang pertama (default: 1000)
FIRECRAWL_RETRY_MAX_DELAY: Penundaan maksimum dalam milidetik antara percobaan ulang (default: 10000)
FIRECRAWL_RETRY_BACKOFF_FACTOR: Pengganda backoff eksponensial (default: 2)

Pemantauan Penggunaan Kredit

FIRECRAWL_CREDIT_WARNING_THRESHOLD: Ambang peringatan penggunaan kredit (default: 1000)
FIRECRAWL_CREDIT_CRITICAL_THRESHOLD: Ambang kritis penggunaan kredit (default: 100)

Contoh Konfigurasi

Untuk penggunaan API cloud dengan percobaan ulang dan pemantauan kredit kustom:

# 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

Untuk instance self-hosted:

# 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

Penggunaan dengan Claude Desktop

Tambahkan ini ke claude_desktop_config.json Anda:

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

Konfigurasi Sistem

Server mencakup beberapa parameter yang dapat dikonfigurasi yang dapat diatur melalui variabel lingkungan. Berikut adalah nilai default jika tidak dikonfigurasi:

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
  },
};

Konfigurasi ini mengontrol:

Perilaku Percobaan Ulang
- Secara otomatis mencoba ulang permintaan yang gagal karena batas laju
- Menggunakan backoff eksponensial untuk menghindari membebani API
- Contoh: Dengan pengaturan default, percobaan ulang akan dilakukan pada:
  - Percobaan ulang ke-1: penundaan 1 detik
  - Percobaan ulang ke-2: penundaan 2 detik
  - Percobaan ulang ke-3: penundaan 4 detik (dibatasi pada maxDelay)
Pemantauan Penggunaan Kredit
- Melacak konsumsi kredit API untuk penggunaan API cloud
- Memberikan peringatan pada ambang yang ditentukan
- Membantu mencegah gangguan layanan yang tidak terduga
- Contoh: Dengan pengaturan default:
  - Peringatan pada 1000 kredit tersisa
  - Peringatan kritis pada 100 kredit tersisa

Pembatasan Laju dan Pemrosesan Batch

Server memanfaatkan kemampuan pembatasan laju dan pemrosesan batch bawaan Firecrawl:

Penanganan batas laju otomatis dengan backoff eksponensial
Pemrosesan paralel yang efisien untuk operasi batch
Antrian dan throttling permintaan yang cerdas
Percobaan ulang otomatis untuk kesalahan sementara

Cara Memilih Alat

Gunakan panduan ini untuk memilih alat yang tepat untuk tugas Anda:

Jika Anda tahu URL persis yang Anda inginkan:
- Untuk satu: gunakan scrape (dengan format JSON untuk data terstruktur)
- Untuk banyak: gunakan batch_scrape
Jika Anda perlu menemukan URL di situs: gunakan map
Jika Anda ingin mencari informasi di web: gunakan search
Jika Anda memerlukan riset kompleks di berbagai sumber yang tidak diketahui: gunakan agent
Jika Anda ingin menganalisis seluruh situs atau bagian: gunakan crawl (dengan batasan!)
Jika Anda memerlukan otomatisasi browser interaktif (klik, ketik, navigasi): gunakan scrape + interact

Tabel Referensi Cepat

Alat	Terbaik untuk	Mengembalikan
scrape	Konten halaman tunggal	JSON (disarankan) atau markdown
interact	Berinteraksi dengan halaman yang di-scrape	Hasil eksekusi
batch_scrape	Beberapa URL yang diketahui	JSON (disarankan) atau markdown[]
map	Menemukan URL di situs	URL[]
crawl	Ekstraksi multi-halaman (dengan batasan)	markdown/html[]
search	Pencarian informasi di web	results[]
agent	Riset multi-sumber yang kompleks	JSON (data terstruktur)

Panduan Pemilihan Format

Saat menggunakan scrape atau batch_scrape, pilih format yang tepat:

Format JSON (disarankan untuk sebagian besar kasus): Gunakan saat Anda membutuhkan data spesifik dari halaman. Tentukan skema berdasarkan apa yang perlu Anda ekstrak. Ini menjaga respons tetap kecil dan menghindari luapan jendela konteks.
Format Markdown (gunakan secukupnya): Hanya saat Anda benar-benar membutuhkan konten halaman penuh, seperti membaca seluruh artikel untuk diringkas atau menganalisis struktur halaman.

Alat yang Tersedia

1. Alat Scrape (`firecrawl_scrape`)

Mengekstrak konten dari satu URL dengan opsi lanjutan.

Terbaik untuk:

Ekstraksi konten halaman tunggal, ketika Anda tahu persis halaman mana yang berisi informasi.

Tidak disarankan untuk:

Mengekstrak konten dari beberapa halaman (gunakan batch_scrape untuk URL yang diketahui, atau map + batch_scrape untuk menemukan URL terlebih dahulu, atau crawl untuk konten halaman penuh)
Saat Anda tidak yakin halaman mana yang berisi informasi (gunakan search)

Kesalahan umum:

Menggunakan scrape untuk daftar URL (gunakan batch_scrape sebagai gantinya).
Menggunakan format markdown secara default (gunakan format JSON untuk mengekstrak hanya yang Anda butuhkan).

Memilih format yang tepat:

Format JSON (disarankan): Untuk sebagian besar kasus penggunaan, gunakan format JSON dengan skema untuk mengekstrak hanya data spesifik yang dibutuhkan. Ini menjaga respons tetap fokus dan mencegah luapan jendela konteks.
Format Markdown: Hanya ketika tugas benar-benar membutuhkan konten halaman penuh (mis., meringkas seluruh artikel, menganalisis struktur halaman).

Contoh Prompt:

"Dapatkan detail produk dari https://example.com/product."

Contoh Penggunaan (format JSON - disarankan):

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

Contoh Penggunaan (format markdown - saat konten penuh dibutuhkan):

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

Contoh Penggunaan (format branding - ekstrak identitas merek):

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

Format branding: Mengekstrak identitas merek yang komprehensif (warna, font, tipografi, spasi, logo, komponen UI) untuk analisis desain atau replikasi gaya. Privasi: Atur redactPII: true untuk mengembalikan konten dengan informasi identitas pribadi yang disunting.

Mengembalikan:

Data terstruktur JSON, markdown, profil branding, atau format lain sesuai yang ditentukan.

2. Alat Batch Scrape (`firecrawl_batch_scrape`)

Mengekstrak beberapa URL secara efisien dengan pembatasan laju bawaan dan pemrosesan paralel.

Terbaik untuk:

Mengambil konten dari beberapa halaman, ketika Anda tahu persis halaman mana yang akan di-scrape.

Tidak disarankan untuk:

Menemukan URL (gunakan map terlebih dahulu jika Anda tidak tahu URL-nya)
Mengekstrak satu halaman (gunakan scrape)

Kesalahan umum:

Menggunakan batch_scrape dengan terlalu banyak URL sekaligus (dapat mencapai batas laju atau luapan token)

Contoh Prompt:

"Dapatkan konten dari tiga posting blog ini: [url1, url2, url3]."

Contoh Penggunaan:

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

Mengembalikan:

Respons mencakup ID operasi untuk pengecekan status:

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

3. Periksa Status Batch (`firecrawl_check_batch_status`)

Periksa status operasi batch.

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

4. Alat Map (`firecrawl_map`)

Memetakan situs web untuk menemukan semua URL yang terindeks di situs tersebut.

Terbaik untuk:

Menemukan URL di situs web sebelum memutuskan apa yang akan di-scrape
Menemukan bagian tertentu dari situs web

Tidak disarankan untuk:

Saat Anda sudah tahu URL spesifik mana yang Anda butuhkan (gunakan scrape atau batch_scrape)
Saat Anda membutuhkan konten halaman (gunakan scrape setelah pemetaan)

Kesalahan umum:

Menggunakan crawl untuk menemukan URL alih-alih map

Contoh Prompt:

"Daftar semua URL di example.com."

Contoh Penggunaan:

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

Mengembalikan:

Array URL yang ditemukan di situs

5. Alat Search (`firecrawl_search`)

Mencari web dan secara opsional mengekstrak konten dari hasil pencarian.

Terbaik untuk:

Menemukan informasi spesifik di beberapa situs web, ketika Anda tidak tahu situs web mana yang memiliki informasi tersebut.
Saat Anda membutuhkan konten yang paling relevan untuk kueri

Tidak disarankan untuk:

Saat Anda sudah tahu situs web mana yang akan di-scrape (gunakan scrape)
Saat Anda membutuhkan cakupan komprehensif dari satu situs web (gunakan map atau crawl)

Kesalahan umum:

Menggunakan crawl atau map untuk pertanyaan terbuka (gunakan search sebagai gantinya)

Contoh Penggunaan:

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

Mengembalikan:

Array hasil pencarian (dengan konten tergores opsional), ditambah field id. Berikan id itu ke firecrawl_search_feedback setelah Anda menggunakan hasilnya untuk mengembalikan 1 kredit (pencarian memerlukan 2) dan meningkatkan kualitas pencarian.

Contoh Prompt:

"Temukan makalah penelitian terbaru tentang AI yang diterbitkan pada tahun 2023."

5b. Alat Umpan Balik Pencarian (`firecrawl_search_feedback`)

Mengirim umpan balik terstruktur pada hasil firecrawl_search sebelumnya. Umpan balik pertama per id pencarian mengembalikan 1 kredit dan meningkatkan kualitas pencarian Firecrawl. Idempoten per id pencarian.

Panggil ini setelah setiap pencarian yang benar-benar Anda gunakan (atau yang tidak membantu). Umpan balik buruk/sebagian dengan missingContent sama berharganya dengan umpan balik baik.

Menyisih: atur FIRECRAWL_NO_SEARCH_FEEDBACK=1 (atau FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1) di lingkungan saat memulai server MCP. Alat firecrawl_search_feedback tidak akan didaftarkan, sehingga agen tidak dapat memanggilnya. Admin tim juga dapat menonaktifkan umpan balik di sisi server; dalam kasus itu alat tetap terdaftar tetapi selalu mengembalikan feedbackErrorCode: "TEAM_OPTED_OUT".

Field paling penting: missingContent. Ini adalah array berisi potongan konten spesifik yang diharapkan agen temukan tetapi tidak ditemukan. Satu entri per topik yang hilang — ini teragregasi di seluruh tim dan memberi tahu kami apa yang harus diindeks selanjutnya.

Batas pengembalian harian (per tim, per hari UTC, default 100 kredit). Setelah creditsRefundedToday tim mencapai dailyRefundCap, pengiriman selanjutnya tetap mencatat umpan balik tetapi tidak lagi mengembalikan kredit. Respons menetapkan dailyCapReached: true. Agen harus berhenti memanggil alat ini selama sisa hari UTC ketika melihat flag tersebut.

Contoh Penggunaan:

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

Mengembalikan:

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

5c. Alat Umpan Balik Generik (`firecrawl_feedback`)

Mengirim umpan balik terstruktur untuk pekerjaan endpoint v2 yang selesai melalui /v2/feedback. Gunakan ini untuk umpan balik tingkat endpoint pada pekerjaan scrape, parse, map, atau search. Untuk kualitas hasil pencarian secara spesifik, lebih baik gunakan firecrawl_search_feedback karena mencakup panduan khusus pencarian.

Jaga umpan balik tetap ringkas: gunakan kode isu, tag, catatan singkat, URL, nomor halaman, dan objek metadata kecil. Jangan sertakan output mentah goresan/parse.

Menyisih: atur FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 (atau FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1) di lingkungan saat memulai server MCP. Alat firecrawl_feedback tidak akan didaftarkan, sehingga agen tidak dapat memanggilnya.

Contoh Penggunaan:

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

Mengembalikan:

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

6. Alat Crawl (`firecrawl_crawl`)

Memulai pekerjaan crawl asinkron pada sebuah situs web dan mengekstrak konten dari semua halaman.

Terbaik untuk:

Mengekstrak konten dari beberapa halaman terkait, ketika Anda membutuhkan cakupan komprehensif.

Tidak disarankan untuk:

Mengekstrak konten dari satu halaman (gunakan scrape)
Ketika batas token menjadi perhatian (gunakan map + batch_scrape)
Ketika Anda membutuhkan hasil cepat (crawling bisa lambat)

Peringatan: Respons crawl bisa sangat besar dan mungkin melebihi batas token. Batasi kedalaman crawl dan jumlah halaman, atau gunakan map + batch_scrape untuk kontrol yang lebih baik.

Kesalahan umum:

Mengatur limit atau maxDepth terlalu tinggi (menyebabkan token overflow)
Menggunakan crawl untuk satu halaman (gunakan scrape saja)

Contoh Prompt:

"Dapatkan semua postingan blog dari dua level pertama example.com/blog."

Contoh Penggunaan:

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

Mengembalikan:

Respons mencakup ID operasi untuk pengecekan status:

{
  "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. Periksa Status Crawl (`firecrawl_check_crawl_status`)

Periksa status pekerjaan crawl.

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

Mengembalikan:

Respons mencakup status pekerjaan crawl:

8. Alat Extract (`firecrawl_extract`)

Mengekstrak informasi terstruktur dari halaman web menggunakan kemampuan LLM. Mendukung AI cloud dan ekstraksi LLM self-hosted.

Terbaik untuk:

Mengekstrak data terstruktur spesifik seperti harga, nama, detail.

Tidak disarankan untuk:

Ketika Anda membutuhkan konten penuh halaman (gunakan scrape)
Ketika Anda tidak mencari data terstruktur spesifik

Argumen:

urls: Array URL untuk mengekstrak informasi
prompt: Prompt kustom untuk ekstraksi LLM
systemPrompt: Prompt sistem untuk memandu LLM
schema: Skema JSON untuk ekstraksi data terstruktur
allowExternalLinks: Izinkan ekstraksi dari tautan eksternal
enableWebSearch: Aktifkan pencarian web untuk konteks tambahan
includeSubdomains: Sertakan subdomain dalam ekstraksi

Saat menggunakan instance self-hosted, ekstraksi akan menggunakan LLM yang Anda konfigurasi. Untuk API cloud, ia menggunakan layanan LLM terkelola Firecrawl. Contoh Prompt:

"Ekstrak nama produk, harga, dan deskripsi dari halaman produk ini."

Contoh Penggunaan:

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

Mengembalikan:

Data terstruktur yang diekstrak sesuai skema Anda

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

9. Alat Agent (`firecrawl_agent`)

Agen riset web otonom. Ini adalah lapisan agen AI terpisah yang secara independen menjelajahi internet, mencari informasi, menavigasi halaman, dan mengekstrak data terstruktur berdasarkan kueri Anda.

Cara kerjanya:

Agen melakukan pencarian web, mengikuti tautan, membaca halaman, dan mengumpulkan data secara otonom. Ini berjalan secara asinkron - ia mengembalikan ID pekerjaan segera, dan Anda melakukan polling firecrawl_agent_status untuk memeriksa kapan selesai dan mengambil hasil.

Alur kerja asinkron:

Panggil firecrawl_agent dengan prompt/skema Anda → mengembalikan ID pekerjaan
Lakukan pekerjaan lain sementara agen meriset (bisa memakan waktu menit untuk kueri kompleks)
Polling firecrawl_agent_status dengan ID pekerjaan untuk memeriksa kemajuan
Ketika status "completed", respons mencakup data yang diekstrak

Terbaik untuk:

Tugas riset kompleks di mana Anda tidak tahu URL pastinya
Pengumpulan data multi-sumber
Menemukan informasi yang tersebar di web
Tugas di mana Anda dapat melakukan pekerjaan lain sambil menunggu hasil

Tidak disarankan untuk:

Scraping halaman tunggal sederhana di mana Anda tahu URL-nya (gunakan scrape dengan format JSON - lebih cepat dan murah)

Argumen:

prompt: Deskripsi bahasa alami dari data yang Anda inginkan (wajib, maks 10.000 karakter)
urls: Array opsional URL untuk memfokuskan agen pada halaman tertentu
schema: Skema JSON opsional untuk output terstruktur

Contoh Prompt:

"Temukan pendiri Firecrawl dan latar belakang mereka"

Contoh Penggunaan (mulai agen, lalu polling hasil):

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

Kemudian polling dengan firecrawl_agent_status menggunakan ID pekerjaan yang dikembalikan.

Contoh Penggunaan (dengan URL - agen fokus pada halaman tertentu):

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

Mengembalikan:

ID pekerjaan untuk pengecekan status. Gunakan firecrawl_agent_status untuk polling hasil.

10. Periksa Status Agent (`firecrawl_agent_status`)

Periksa status pekerjaan agen dan ambil hasil ketika selesai. Gunakan ini untuk polling hasil setelah memulai agen.

Pola polling: Riset agen bisa memakan waktu menit untuk kueri kompleks. Polling endpoint ini secara berkala (mis., setiap 10-30 detik) hingga status "completed" atau "failed".

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

Status yang mungkin:

processing: Agen masih meriset - periksa kembali nanti
completed: Riset selesai - respons mencakup data yang diekstrak
failed: Terjadi kesalahan

11. Alat Monitor (`firecrawl_monitor_*`)

Membuat dan mengelola monitor halaman berulang. Monitor menjalankan scrape atau crawl terjadwal, membandingkan setiap hasil dengan snapshot terakhir yang disimpan, dan dapat memberi notifikasi melalui webhook atau email.

Terbaik untuk:

Memantau satu halaman atau beberapa halaman dari waktu ke waktu
Memberi peringatan pada perubahan bermakna menggunakan tujuan bahasa sederhana
Melacak riwayat pemeriksaan dan perbedaan tingkat halaman

Pola pembuatan yang disarankan:

Gunakan page atau pages ditambah goal. Server MCP membangun permintaan monitor dengan jadwal 30 menit dan API mengaktifkan penilaian perubahan bermakna secara otomatis.

Penilaian perubahan bermakna berjalan otomatis ketika goal diatur. Webhook halaman mengekspos isMeaningful dan judgment pada event monitor.page.

Tulis tujuan sebagai instruksi monitor ringkas 2-3 kalimat. Katakan apa yang seharusnya memicu peringatan, pertahankan cakupan apa pun yang diberikan pengguna, dan sertakan pengecualian spesifik maksud hanya jika jelas dari permintaan. Noise generik seperti spasi putih, perubahan hanya format, ID permintaan, parameter pelacakan, metadata generik, dan chrome halaman yang tidak terkait sudah ditangani oleh penilai, jadi jangan ulangi di setiap tujuan. Jika pengguna tidak jelas, biarkan tujuan tetap luas; jika mereka meminta pemantauan luas atau "perubahan apa pun", pertahankan itu. Jika pengguna mengatakan mereka tidak peduli tentang sesuatu, sertakan itu secara eksplisit.

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

Beberapa halaman dengan 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"
  }
}

Permintaan pembuatan lanjutan:

Berikan body ketika Anda membutuhkan target crawl, pelacakan perubahan JSON, retensi kustom, atau kontrol judgeEnabled eksplisit.

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

Alat monitor lainnya:

firecrawl_monitor_list: daftar monitor.
firecrawl_monitor_get: dapatkan satu monitor.
firecrawl_monitor_update: perbarui field termasuk goal, judgeEnabled, webhook, dan notification.
firecrawl_monitor_run: picu pemeriksaan sekarang.
firecrawl_monitor_checks: daftar pemeriksaan, opsional difilter berdasarkan status.
firecrawl_monitor_check: dapatkan hasil tingkat halaman, termasuk diff, snapshot, judgment.meaningful, dan judgment.meaningfulChanges.

Sistem Logging

Server mencakup logging komprehensif:

Status operasi dan kemajuan
Metrik kinerja
Pemantauan penggunaan kredit
Pelacakan batas laju
Kondisi kesalahan

Contoh pesan log:

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

Penanganan Kesalahan

Server menyediakan penanganan kesalahan yang tangguh:

Percobaan ulang otomatis untuk kesalahan sementara
Penanganan batas laju dengan backoff
Pesan kesalahan terperinci
Peringatan penggunaan kredit
Ketahanan jaringan

Contoh respons kesalahan:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
    }
  ],
  "isError": true
}

Pengembangan

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Berkontribusi

Fork repositori
Buat cabang fitur Anda
Jalankan pengujian: npm test
Kirim pull request

Terima kasih kepada kontributor

Terima kasih kepada @vrknetha, @cawstudios untuk implementasi awal!

Terima kasih kepada MCP.so dan Klavis AI untuk hosting dan @gstarwd, @xiangkaiz dan @zihaolin96 untuk mengintegrasikan server kami.

Lisensi

Lisensi MIT - lihat file LICENSE untuk detailnya

Firecrawl MCP Server

Dokumentasi

Firecrawl MCP Server

Fitur

Instalasi

Menjalankan dengan npx

Instalasi Manual

Menjalankan di Cursor

Menjalankan di Windsurf

Menjalankan dengan Mode Lokal HTTP Streamable

Menginstal melalui Smithery (Legacy)

Menjalankan di VS Code

Konfigurasi

Variabel Lingkungan

Diperlukan untuk API Cloud

OAuth MCP (Token akses Bearer)

Konfigurasi Opsional

Konfigurasi Percobaan Ulang

Pemantauan Penggunaan Kredit

Contoh Konfigurasi

Penggunaan dengan Claude Desktop

Konfigurasi Sistem

Pembatasan Laju dan Pemrosesan Batch

Cara Memilih Alat

Tabel Referensi Cepat

Panduan Pemilihan Format

Alat yang Tersedia

1. Alat Scrape (firecrawl_scrape)

2. Alat Batch Scrape (firecrawl_batch_scrape)

3. Periksa Status Batch (firecrawl_check_batch_status)

4. Alat Map (firecrawl_map)

5. Alat Search (firecrawl_search)

5b. Alat Umpan Balik Pencarian (firecrawl_search_feedback)

5c. Alat Umpan Balik Generik (firecrawl_feedback)

6. Alat Crawl (firecrawl_crawl)

7. Periksa Status Crawl (firecrawl_check_crawl_status)

8. Alat Extract (firecrawl_extract)

9. Alat Agent (firecrawl_agent)

10. Periksa Status Agent (firecrawl_agent_status)

11. Alat Monitor (firecrawl_monitor_*)

Sistem Logging

Penanganan Kesalahan

Pengembangan

Berkontribusi

Terima kasih kepada kontributor

Lisensi

1. Alat Scrape (`firecrawl_scrape`)

2. Alat Batch Scrape (`firecrawl_batch_scrape`)

3. Periksa Status Batch (`firecrawl_check_batch_status`)

4. Alat Map (`firecrawl_map`)

5. Alat Search (`firecrawl_search`)

5b. Alat Umpan Balik Pencarian (`firecrawl_search_feedback`)

5c. Alat Umpan Balik Generik (`firecrawl_feedback`)

6. Alat Crawl (`firecrawl_crawl`)

7. Periksa Status Crawl (`firecrawl_check_crawl_status`)

8. Alat Extract (`firecrawl_extract`)

9. Alat Agent (`firecrawl_agent`)

10. Periksa Status Agent (`firecrawl_agent_status`)

11. Alat Monitor (`firecrawl_monitor_*`)