Firecrawl

Server MCP Firecrawl

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

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

Fitur

• Cari web dan dapatkan konten halaman penuh
• Kikis URL apa pun menjadi data terstruktur yang bersih
• 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

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

Instalasi

MCP Hosted (tingkat gratis tanpa kunci)

Hubungkan ke server remote hosted tanpa pengaturan:

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

Pada tingkat gratis tanpa kunci, scrape, search, dan interact berfungsi tanpa kunci API (dibatasi laju). Alat lain seperti crawl, map, agent, dan extract masih memerlukan kunci.

Utamakan kunci API atau OAuth setiap kali pengguna dapat mendaftar. Ini membuka set alat lengkap dan batas yang lebih tinggi. Dengan kunci, gunakan:

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

Lihat dokumen server MCP dan panduan orientasi agen untuk detail pengaturan.

Endpoint khusus pencarian

Permukaan hanya-baca, khusus pencarian juga dihosting di:

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

Ini mengekspos set tetap enam alat hanya-baca: firecrawl_search dan lima alat firecrawl_research_*. Ini tidak melakukan pengambilan konten halaman dan memiliki identitas OAuth sendiri; endpoint penuh di atas tidak berubah. Lihat docs/search-profile.md untuk kontrak lengkapnya.

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

1. Buka Pengaturan Cursor
2. Buka Fitur > Server MCP
3. Klik "+ Tambahkan server MCP global baru"
4. 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

1. Buka Pengaturan Cursor
2. Buka Fitur > Server MCP
3. Klik "+ Tambahkan Server MCP Baru"
4. 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 web scraping Anda. Akses Composer melalui Command+L (Mac), pilih "Agent" di sebelah 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 melakukan ini 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 Cloud API

• FIRECRAWL_API_KEY: Kunci API Firecrawl Anda
  • Diperlukan saat menggunakan cloud API (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, cloud API akan digunakan (memerlukan kunci API)

MCP OAuth (Token akses Bearer)

Firecrawl Hosted dapat menerbitkan token akses OAuth (fco_…) melalui server otorisasi di firecrawl.dev. Server MCP ini meneruskan kredensial mana pun yang diselesaikannya ke Firecrawl API 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.

Permukaan khusus pencarian (hosted)

Dalam mode hosted (CLOUD_SERVICE=true) instance dalam proses kedua melayani endpoint khusus pencarian. Layanan yang dibundel memiliki kontrak deployment tetap: nginx merutekan /v2/mcp-search ke instance pada port lokal 3001, dan pengidentifikasi sumber daya yang dilindungi OAuth adalah https://mcp.firecrawl.dev/v2/mcp-search.

FIRECRAWL_MCP_SEARCH_ENABLED (default true) adalah toggle operasional yang didukung; atur ke false untuk mencegah instance pencarian dimulai. Proses Node juga menerima FIRECRAWL_MCP_SEARCH_PORT, FIRECRAWL_MCP_SEARCH_ENDPOINT, dan FIRECRAWL_MCP_SEARCH_RESOURCE_URL untuk pengujian terisolasi. Override tersebut tidak mengonfigurasi ulang rute nginx yang dibundel atau daftar izin server otorisasi dan tidak boleh digunakan secara independen dalam deployment hosted.

Instance pencarian memerlukan autentikasi untuk setiap permintaan (termasuk tools/list) dan menolak token OAuth yang audiensnya tidak cocok dengan sumber dayanya sendiri.

Contoh Konfigurasi

Untuk penggunaan cloud API:

export FIRECRAWL_API_KEY=your-api-key

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

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

Cara Memilih Alat

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

• Jika Anda tahu URL persis yang Anda inginkan: gunakan scrape (dengan format JSON untuk data terstruktur)
• Jika Anda memiliki beberapa URL yang diketahui: panggil scrape untuk setiap URL. Jika Anda secara spesifik membutuhkan satu operasi API massal, gunakan endpoint batch Firecrawl API di luar MCP.
• Jika Anda perlu menemukan URL di suatu situs: gunakan map
• Jika Anda ingin mencari info 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 interact dengan URL untuk halaman baru, atau scrape + interact ketika Anda sudah mengikis halaman atau memerlukan kontrol scrape yang lebih ketat

Tabel Referensi Cepat

Alat	Terbaik untuk	Mengembalikan
scrape	Konten halaman tunggal	JSON (disarankan) atau markdown
interact	Berinteraksi dengan URL atau halaman yang dikikis	Hasil eksekusi + scrapeId untuk mode URL
map	Menemukan URL di suatu situs	URL[]
crawl	Ekstraksi multi-halaman (dengan batasan)	status/data crawl akhir setelah polling internal
parse	File dan referensi unggahan yang dihosting	markdown, JSON, atau output dokumen
extract	Ekstraksi terstruktur dari URL	Data terstruktur JSON
search	Pencarian web untuk info	results[]
agent	Riset multi-sumber yang kompleks	JSON (data terstruktur)
monitor	Pemeriksaan halaman berulang	metadata dan perbedaan monitor/check
research	Riset makalah dan repositori GitHub	hasil riset dan kecocokan repo

Panduan Pemilihan Format

Saat menggunakan scrape, pilih format yang tepat:

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

Alat yang Tersedia

1. Alat Scrape (firecrawl_scrape)

Mengikis 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 panggilan scrape berulang untuk URL yang diketahui, atau map + scrape untuk menemukan URL terlebih dahulu, atau crawl untuk konten halaman penuh)
• Ketika Anda tidak yakin halaman mana yang berisi informasi (gunakan search)

Kesalahan umum:

• Meneruskan daftar URL ke satu panggilan scrape. Panggil scrape sekali per URL di MCP. Jika Anda secara spesifik membutuhkan satu operasi API massal, gunakan endpoint batch Firecrawl API di luar MCP.
• 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 memerlukan 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 pengenal pribadi disunting.

Mengembalikan:

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

2. Alat Map (firecrawl_map)

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

Terbaik untuk:

• Menemukan URL di situs web sebelum memutuskan apa yang akan dikikis
• Menemukan bagian tertentu dari situs web

Tidak disarankan untuk:

• Ketika Anda sudah tahu URL spesifik mana yang Anda butuhkan (gunakan scrape)
• Ketika Anda membutuhkan konten halaman (gunakan scrape setelah pemetaan)

Kesalahan umum:

• Menggunakan crawl untuk menemukan URL alih-alih map

Contoh Prompt:

"Daftarkan semua URL di example.com."

Contoh Penggunaan:

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

Mengembalikan:

• Array URL yang ditemukan di situs

3. Alat Search (firecrawl_search)

Cari web dan secara opsional ekstrak konten dari hasil pencarian.

Terbaik untuk:

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

Tidak disarankan untuk:

• Ketika Anda sudah tahu situs web mana yang akan dikikis (gunakan scrape)
• Ketika 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",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

Atur highlights ke true untuk meminta sorotan yang relevan dengan kueri atau false untuk mempertahankan cuplikan pencarian asli. Abaikan untuk menggunakan perilaku default API.

Mengembalikan:

• Array hasil pencarian (dengan konten yang di-scrape opsional), ditambah bidang id. Berikan id tersebut ke firecrawl_search_feedback setelah Anda menggunakan hasilnya untuk mengembalikan 1 kredit (biaya pencarian 2) dan meningkatkan kualitas pencarian.

Contoh Prompt:

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

3b. 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 hal ini alat tetap terdaftar tetapi selalu mengembalikan feedbackErrorCode: "TEAM_OPTED_OUT".

Bidang terpenting: missingContent. Ini adalah array berisi potongan konten spesifik yang diharapkan agen untuk ditemukan 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 dana 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. Responsnya menetapkan dailyCapReached: true. Agen harus berhenti memanggil alat ini untuk sisa hari UTC ketika mereka melihat tanda itu.

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? }.

3c. Alat Umpan Balik Generik (firecrawl_feedback)

Mengirim umpan balik terstruktur untuk pekerjaan endpoint v2 yang telah 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 disarankan firecrawl_search_feedback karena mencakup panduan khusus pencarian.

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

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? }.

4. Alat Crawl (firecrawl_crawl)

Memulai pekerjaan crawl, melakukan polling hingga mencapai status terminal, dan mengembalikan status/data crawl akhir.

Terbaik untuk:

• Mengekstrak konten dari beberapa halaman terkait, saat Anda membutuhkan cakupan yang komprehensif.

Tidak disarankan untuk:

• Mengekstrak konten dari satu halaman (gunakan scrape)
• Saat batas token menjadi perhatian (gunakan map + scrape untuk kontrol yang lebih ketat)
• Saat 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 + scrape untuk kontrol yang lebih ketat.

Kesalahan umum:

• Mengatur limit atau maxDiscoveryDepth terlalu tinggi (menyebabkan token overflow)
• Menggunakan crawl untuk satu halaman (gunakan scrape sebagai gantinya)

Contoh Prompt:

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

Contoh Penggunaan:

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

Mengembalikan:

• Status dan data crawl akhir setelah polling internal, termasuk id, status, completed, total, creditsUsed, expiresAt, next, dan data. Gunakan id yang dikembalikan dengan firecrawl_check_crawl_status jika Anda perlu memeriksa ulang pekerjaan nanti.

5. Periksa Status Crawl (firecrawl_check_crawl_status)

Periksa status dan hasil pekerjaan crawl yang ada berdasarkan ID.

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

Mengembalikan:

• Respons mencakup status pekerjaan crawl:

6. Alat Parse (firecrawl_parse)

Parse file lokal atau referensi unggahan yang dihosting dengan endpoint /v2/parse Firecrawl.

Terbaik untuk: PDF, dokumen Word, spreadsheet, file HTML, dan dokumen lain yang membutuhkan output markdown atau JSON terstruktur. MCP yang dihosting mendukung alur unggah-ref dua langkah; pembacaan file langsung lokal memerlukan FIRECRAWL_API_URL yang dihosting sendiri.

Tidak disarankan untuk: URL jarak jauh (gunakan scrape), banyak file dalam satu panggilan (panggil parse sekali per file), atau tindakan khusus browser seperti tangkapan layar dan klik.

Alur MCP yang dihosting: MCP yang dihosting tidak dapat membaca sistem file pemanggil secara langsung. Panggil firecrawl_parse dengan filePath untuk menerima perintah unggahan berumur pendek dan nextToolCall, unggah file secara lokal, lalu panggil firecrawl_parse lagi dengan uploadRef yang dikembalikan. Mencetak URL unggahan yang dihosting memerlukan auth Firecrawl atau kelayakan tanpa kunci. Dalam mode npx firecrawl-mcp lokal, parsing file langsung saat ini memerlukan FIRECRAWL_API_URL yang mengarah ke API Firecrawl yang dihosting sendiri; server lokal khusus kunci API cloud biasa tidak dapat membaca dan mengunggah file melalui alat ini.

Contoh Penggunaan:

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

Mengembalikan: Konten dokumen yang di-parse atau instruksi unggahan yang dihosting dengan nextToolCall.

7. Alat Extract (firecrawl_extract)

Mengekstrak informasi terstruktur dari halaman web menggunakan kemampuan LLM. Mendukung AI cloud dan ekstraksi LLM yang dihosting sendiri.

Terbaik untuk:

• Mengekstrak data terstruktur spesifik seperti harga, nama, detail.

Tidak disarankan untuk:

• Saat Anda membutuhkan konten penuh halaman (gunakan scrape)
• Saat 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 yang dihosting sendiri, ekstraksi akan menggunakan LLM yang Anda konfigurasikan. Untuk API cloud, ini 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 seperti yang ditentukan oleh skema Anda

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

8. 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 - langsung mengembalikan ID pekerjaan, dan Anda melakukan polling firecrawl_agent_status untuk memeriksa kapan selesai dan mengambil hasilnya.

Alur kerja asinkron:

1. Panggil firecrawl_agent dengan prompt/skema Anda → mengembalikan ID pekerjaan
2. Lakukan pekerjaan lain sementara agen meneliti (bisa memakan waktu beberapa menit untuk kueri kompleks)
3. Polling firecrawl_agent_status dengan ID pekerjaan untuk memeriksa kemajuan
4. Saat 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 satu halaman sederhana di mana Anda tahu URL-nya (gunakan scrape dengan format JSON - lebih cepat dan lebih 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.

9. Periksa Status Agen (firecrawl_agent_status)

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

Pola polling: Riset agen bisa memakan waktu beberapa 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 meneliti - periksa kembali nanti
• completed: Riset selesai - respons mencakup data yang diekstrak
• failed: Terjadi kesalahan

10. Alat Interact (firecrawl_interact)

Berinteraksi dengan URL baru atau dengan halaman yang sudah dibuka oleh firecrawl_scrape.

Terbaik untuk: Mengklik, mengetik, menavigasi, dan mengekstrak status dari halaman dinamis tanpa mengembalikan alat browser yang sudah tidak digunakan.

Opsi penggunaan:

• Berikan url untuk men-scrape dan membuka halaman untuk interaksi dalam satu panggilan MCP.
• Berikan scrapeId untuk melanjutkan interaksi dengan halaman yang sudah di-scrape.
• Berikan tepat salah satu dari url atau scrapeId, ditambah prompt atau code.

Contoh Penggunaan:

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

Mengembalikan: Hasil interaksi dan, untuk mode URL, scrapeId turunan untuk tindak lanjut atau pembersihan.

11. Alat Stop Interact (firecrawl_interact_stop)

Hentikan sesi interaksi untuk halaman yang di-scrape setelah Anda selesai berinteraksi.

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

12. Alat Riset (firecrawl_research_*)

Cari dan periksa makalah serta repositori GitHub melalui alat MCP riset.

Alat riset yang tersedia:

• firecrawl_research_search_papers: mencari makalah penelitian.
• firecrawl_research_inspect_paper: memeriksa satu makalah.
• firecrawl_research_related_papers: menemukan makalah terkait.
• firecrawl_research_read_paper: membaca konten makalah.
• firecrawl_research_search_github: mencari repositori GitHub.

Terbaik untuk: Tinjauan literatur, pencarian makalah, dan alur kerja penemuan repositori di mana agen membutuhkan permukaan riset yang terfokus alih-alih scraping web umum.

13. Alat Monitor (firecrawl_monitor_*)

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

Terbaik untuk:

• Memantau satu halaman atau beberapa halaman dari waktu ke waktu
• Memberi peringatan tentang perubahan yang berarti menggunakan tujuan bahasa Inggris sederhana
• Melacak riwayat pemeriksaan dan perbedaan tingkat halaman

Pola pembuatan yang disarankan:

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

Penilaian perubahan berarti berjalan secara otomatis saat goal diatur. Webhook halaman mengekspos isMeaningful dan judgment pada peristiwa monitor.page.

Tulis tujuan sebagai instruksi monitor ringkas 2-3 kalimat. Katakan apa yang harus memicu peringatan, pertahankan cakupan apa pun yang diberikan pengguna, dan sertakan pengecualian spesifik maksud hanya jika jelas dari permintaan. Gangguan umum seperti spasi, 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, jaga 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 saat 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 pemantau.
• firecrawl_monitor_get: dapatkan satu pemantau.
• firecrawl_monitor_update: perbarui bidang termasuk goal, judgeEnabled, webhook, dan notification.
• firecrawl_monitor_run: picu pemeriksaan sekarang.
• firecrawl_monitor_delete: hapus pemantau (destruktif; hanya panggil jika pengguna bermaksud menghapusnya).
• 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 Pencatatan

Server menyertakan pencatatan yang komprehensif:

• Status dan kemajuan operasi
• Metrik kinerja
• Pelacakan batas laju
• Kondisi kesalahan

Contoh pesan log:

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

Penanganan Kesalahan

Server menyediakan penanganan kesalahan yang tangguh:

• Kesalahan batas laju API disampaikan ke klien MCP
• Pesan kesalahan terperinci
• Ketahanan jaringan

Contoh respons kesalahan:

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

Pengembangan

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Berkontribusi

1. Fork repositori
2. Buat cabang fitur Anda
3. Jalankan pengujian: npm test
4. 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