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 yang bersih dan siap pakai untuk agen.

Terima kasih besar kepada @vrknetha, @knacklabs atas implementasi awalnya!

Fitur

• Cari di web dan dapatkan konten halaman penuh
• Cari indeks yang dibangun untuk agen pengkodean: masalah GitHub, pull request yang digabungkan, README, dan dokumen
• Kikis URL apa pun menjadi data terstruktur yang bersih
• Berinteraksi dengan halaman — klik, navigasi, dan operasikan
• Riset mendalam dengan agen otonom
• Coba ulang otomatis dan pembatasan kecepatan
• Dukungan cloud dan self-hosted
• Dukungan SSE

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

Kapan Menggunakan Server Ini

• Gunakan firecrawl_scrape saat Anda memiliki URL yang diketahui dan menginginkan kontennya sebagai markdown atau sebagai JSON yang sesuai dengan skema yang Anda berikan.
• Gunakan firecrawl_map saat Anda perlu menemukan URL di situs tanpa mengambil kontennya.
• Gunakan firecrawl_crawl saat Anda memerlukan konten dari banyak halaman di bawah situs; atur limit, includePaths/excludePaths, atau maxDiscoveryDepth untuk membatasinya.
• Gunakan firecrawl_search saat Anda memulai dari kueri, bukan URL, dan menginginkan hasil web yang diperingkat; tambahkan scrapeOptions jika Anda juga ingin konten halaman diambil dalam panggilan yang sama (endpoint khusus pencarian tidak pernah mengambil konten).
• Gunakan firecrawl_interact saat halaman memerlukan tindakan klik, ketik, atau navigasi sebelum Anda dapat membacanya — berikan url untuk halaman baru atau scrapeId untuk melanjutkan di halaman yang sudah Anda kikis.
• Gunakan alat firecrawl_monitor_* saat halaman yang sama perlu diperiksa secara terjadwal berulang dengan diff dan peringatan perubahan, alih-alih diambil sekali.
• Pertimbangkan hal lain saat Anda perlu menjaga sesi browser tetap terbuka di banyak langkah Anda sendiri dengan logika coba ulang dan penghentian Anda sendiri: setiap panggilan firecrawl_interact menjalankan satu giliran prompt atau code hingga selesai dan mengembalikan kontrol — sesi dapat bertahan di seluruh panggilan melalui scrapeId dan berakhir dengan firecrawl_interact_stop, tetapi Anda tidak dapat mengendarainya secara interaktif langkah demi langkah dari sisi klien dalam satu panggilan.

Server ini mencantumkan 25 alat saat profil penuh terdaftar dengan pengaturan default (termasuk alat umpan balik, tidak berjalan dalam mode tanpa kunci lokal). Menyetel FIRECRAWL_NO_SEARCH_FEEDBACK=1 dan/atau FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 menghapus alat umpan balik yang sesuai dan mengurangi jumlah ini, begitu juga dengan startup tanpa kunci lokal. Untuk klien dengan batas slot alat: endpoint tanpa kunci yang dihosting (https://mcp.firecrawl.dev/v2/mcp, tanpa kunci API) hanya mengekspos 3 — firecrawl_scrape, firecrawl_search, firecrawl_parse — dan endpoint khusus pencarian (https://mcp.firecrawl.dev/v2/mcp-search) mengekspos 6 alat hanya-baca tetap.

Instalasi

MCP yang Dihosting (tingkat gratis tanpa kunci)

Hubungkan ke server yang dihosting jarak jauh tanpa pengaturan:

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

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

Pilih OAuth atau kunci API kapan pun manusia dapat mendaftar. Ini membuka set alat penuh dan batas yang lebih tinggi.

Untuk koneksi akun interaktif, konfigurasikan klien MCP Anda untuk menggunakan URL server ini. Ini adalah endpoint MCP, bukan halaman browser; gunakan alur koneksi akun klien dan jangan tambahkan entri server Firecrawl kedua saat menyambungkan kembali:

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

Untuk koneksi kunci API (misalnya, integrasi tanpa pengawasan), pertahankan URL server sebagai:

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

Kemudian konfigurasikan pengaturan header aman atau rahasia klien dengan:

Authorization: Bearer <FIRECRAWL_API_KEY>

Jangan pernah menaruh kunci API di URL server. Jangan pernah menaruh kunci API di obrolan agen. Konfigurasikan langsung di klien atau pengelola rahasia. Lihat panduan pengaturan MCP yang dihosting dan panduan orientasi agen untuk instruksi khusus klien.

Endpoint khusus pencarian

Permukaan hanya-baca dan khusus pencarian juga dihosting di:

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

Ini mengekspos set tetap enam alat hanya-baca: firecrawl_search, firecrawl_developer_search, dan empat 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 lengkap.

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 "+ Tambah 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 "+ Tambah 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 memintanya secara eksplisit dengan menjelaskan kebutuhan pengikisan 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 transport 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 (Warisan)

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 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 khusus 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 yang dihosting dapat menerbitkan token akses OAuth (fco_…) melalui server otorisasi di firecrawl.dev. Server MCP ini meneruskan kredensial apa pun yang diselesaikannya ke Firecrawl API sebagai Authorization: Bearer ….

• Transport aliran 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 saat keduanya ada.
• stdio: Gunakan FIRECRAWL_OAUTH_TOKEN untuk token akses statis, atau terus gunakan FIRECRAWL_API_KEY untuk kunci API.

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

Permukaan khusus pencarian (dihosting)

Dalam mode dihosting (CLOUD_SERVICE=true) instance dalam-proses kedua melayani endpoint khusus pencarian. Layanan yang digabungkan memiliki kontrak penerapan tetap: nginx merutekan /v2/mcp-search ke instance di 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 sakelar operasional yang didukung; setel 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. Penimpaan tersebut tidak mengonfigurasi ulang rute nginx yang digabungkan atau daftar izin server otorisasi dan tidak boleh digunakan secara independen dalam penerapan yang dihosting.

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 mengetahui 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 khusus memerlukan satu operasi API massal, gunakan endpoint batch Firecrawl API di luar MCP.
• Jika Anda perlu menemukan URL di situs: gunakan map
• Jika Anda ingin mencari web untuk informasi: gunakan search
• Jika Anda memiliki pertanyaan pemrograman (pustaka, kontrak API, pesan kesalahan, bug yang diketahui): gunakan developer search
• Jika Anda memerlukan makalah ilmiah (literatur biomedis, ilmu hayati, klinis, atau arXiv): gunakan alat riset — alat tersebut mencari abstrak dan teks lengkap makalah. search dengan categories: ["research"] adalah hal yang berbeda: filter situs web atas hasil web biasa.
• Jika Anda memerlukan riset multi-sumber yang mengembalikan data terstruktur, tidak mengetahui URL, atau jawabannya mencakup beberapa situs (entitas plus bidangnya, daftar, kumpulan data): gunakan agent
• Jika Anda ingin menganalisis seluruh situs atau bagian: gunakan crawl (dengan batas!)
• Jika Anda memerlukan otomatisasi browser interaktif (klik, ketik, navigasi): gunakan interact dengan URL untuk halaman baru, atau scrape + interact saat 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 situs	URL[]
crawl	Ekstraksi multi-halaman (dengan batas)	status/data crawl akhir setelah polling internal
parse	File dan referensi unggahan yang dihosting	markdown, JSON, atau output dokumen
search	Pencarian web untuk informasi	results[]
developer	Pertanyaan pemrograman atas sumber pengembang	results[] dengan bagian
agent	Riset multi-sumber, situs tidak diketahui atau banyak	JSON (data terstruktur)
monitor	Pemeriksaan halaman berulang	metadata monitor/check dan diff
research	Riset makalah dan repositori GitHub	hasil riset dan kecocokan repositori

Panduan Pemilihan Format

Saat menggunakan scrape, pilih format yang tepat:

• Format JSON (disarankan untuk sebagian besar kasus): Gunakan saat Anda memerlukan data spesifik dari sebuah halaman. Definisikan skema berdasarkan apa yang perlu Anda ekstrak. Ini menjaga respons tetap kecil dan menghindari luapan konteks.
• Format Markdown (gunakan secukupnya): Hanya saat Anda benar-benar memerlukan konten halaman penuh, seperti membaca seluruh artikel untuk diringkas 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, saat Anda tahu persis halaman mana yang berisi informasi tersebut.

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)
• Saat Anda tidak yakin halaman mana yang berisi informasi tersebut (gunakan pencarian)

Kesalahan umum:

• Mengoper daftar URL ke satu panggilan scrape. Panggil scrape satu kali per URL di MCP. Jika Anda secara khusus memerlukan satu operasi API massal, gunakan endpoint batch API Firecrawl 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 konteks.
• Format Markdown: Hanya saat tugas benar-benar memerlukan konten halaman penuh (misalnya, 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 diperlukan):

{
  "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 spesifikasi.

2. 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 dikikis
• Menemukan bagian tertentu dari situs web

Tidak disarankan untuk:

• Saat Anda sudah tahu URL spesifik yang Anda butuhkan (gunakan scrape)
• Saat Anda memerlukan 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 tersebut

3. Alat Pencarian (firecrawl_search)

Mencari di web dan secara opsional mengekstrak konten dari hasil pencarian.

Terbaik untuk:

• Menemukan informasi spesifik di berbagai situs web, saat Anda tidak tahu situs web mana yang memiliki informasi tersebut.
• Saat Anda memerlukan konten yang paling relevan untuk sebuah kueri

Tidak disarankan untuk:

• Saat Anda sudah tahu situs web mana yang akan dikikis (gunakan scrape)
• Saat Anda memerlukan cakupan komprehensif dari satu situs web (gunakan map atau crawl)

Kesalahan umum:

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

Contoh Penggunaan:

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "remote work stipend policies at tech companies",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

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

Untuk makalah ilmiah, lihat Alat Riset: alat tersebut mencari abstrak dan teks lengkap makalah, sementara categories: ["research"] di sini memfilter hasil web biasa ke situs web yang berafiliasi dengan riset.

Mengembalikan:

• Array hasil pencarian (dengan konten yang dikikis secara opsional), plus bidang id. Teruskan id tersebut ke firecrawl_search_feedback setelah Anda menggunakan hasilnya untuk mengembalikan 1 kredit (pencarian berbiaya 2) dan meningkatkan kualitas pencarian.

Contoh Prompt:

"Bandingkan kebijakan tunjangan kerja jarak jauh di perusahaan teknologi."

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 yang baik.

Keluar: 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 terdaftar tetapi selalu mengembalikan feedbackErrorCode: "TEAM_OPTED_OUT".

Bidang terpenting: missingContent. Ini adalah array dari bagian konten spesifik yang diharapkan agen temukan tetapi tidak ditemukan. Satu entri per topik yang hilang — ini dikumpulkan 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 masih mencatat umpan balik tetapi tidak lagi mengembalikan kredit. Respons menetapkan dailyCapReached: true. Agen harus berhenti memanggil alat ini selama sisa hari UTC saat mereka melihat bendera 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? }.

3c. Alat Umpan Balik Umum (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 khusus, 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 keluaran scrape/parse mentah.

Keluar: 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 memerlukan cakupan 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 memerlukan hasil cepat (crawl 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 luapan token)
• Menggunakan crawl untuk satu halaman (gunakan scrape sebagai gantinya)

Contoh Prompt:

"Dapatkan semua posting blog dari dua tingkat 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)

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

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

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

Tidak disarankan untuk: URL jarak jauh (gunakan scrape), beberapa file dalam satu panggilan (panggil parse satu kali 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 unggah berumur pendek dan nextToolCall, unggah file secara lokal, lalu panggil firecrawl_parse lagi dengan uploadRef yang dikembalikan. Mencetak URL unggahan yang dihosting memerlukan autentikasi Firecrawl atau kelayakan tanpa kunci. Dalam mode npx firecrawl-mcp lokal, penguraian file langsung saat ini memerlukan FIRECRAWL_API_URL yang menunjuk ke API Firecrawl yang dihosting sendiri; server lokal biasa dengan hanya kunci API cloud 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 diurai atau instruksi unggahan yang dihosting dengan nextToolCall.

7. Data terstruktur dengan Scrape JSON

Untuk data terstruktur dari halaman yang diketahui, panggil firecrawl_scrape satu kali per URL dengan formats: ["json"]. Tempatkan prompt ekstraksi dan skema JSON di jsonOptions.

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

Saat URL tidak diketahui atau data mencakup beberapa situs, gunakan firecrawl_agent untuk riset multi-sumber.

8. Alat Agen (firecrawl_agent)

Agen riset web otonom yang mengembalikan data terstruktur saat Anda tidak tahu URL atau jawabannya mencakup beberapa situs. Jelaskan bidang yang Anda butuhkan, secara opsional berikan skema JSON dan URL benih, dan agen mencari, menavigasi, membaca halaman, dan mengembalikan JSON yang disusun dari berbagai sumber. Gunakan untuk entitas beserta bidangnya, untuk daftar dan kumpulan data, dan untuk halaman yang memerlukan navigasi untuk mencapai data. Untuk satu URL yang diketahui gunakan firecrawl_scrape dengan format JSON sebagai gantinya.

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

1. Panggil firecrawl_agent dengan prompt/skema Anda → mengembalikan ID pekerjaan
2. Lakukan pekerjaan lain sementara agen meneliti (dapat memakan waktu beberapa menit untuk kueri kompleks)
3. Polling firecrawl_agent_status dengan ID pekerjaan untuk memeriksa kemajuan
4. Saat status "selesai", respons menyertakan data yang diekstrak

Terbaik untuk:

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

Tidak disarankan untuk:

• Pengikisan halaman tunggal sederhana di mana Anda tahu URL (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 URL opsional untuk memfokuskan agen pada halaman tertentu
• schema: Skema JSON opsional untuk keluaran terstruktur

Contoh Prompt:

"Temukan pendiri Firecrawl dan latar belakang mereka"

Contoh Penggunaan (mulai agen, lalu polling untuk 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" }
            }
          }
        }
      }
    }
  }
}

Lalu 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 pemeriksaan status. Gunakan firecrawl_agent_status untuk polling hasil.

9. Periksa Status Agen (firecrawl_agent_status)

Memeriksa status pekerjaan agen dan mengambil hasil saat selesai. Gunakan ini untuk polling hasil setelah memulai agen.

Pola polling: Riset agen dapat memakan waktu beberapa menit untuk kueri kompleks. Polling endpoint ini secara berkala (misalnya, setiap 10-30 detik) hingga status "selesai" atau "gagal".

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

Status yang mungkin:

• processing: Agen masih meneliti - periksa lagi nanti
• completed: Riset selesai - respons menyertakan 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 memulihkan alat browser yang tidak digunakan lagi.

Opsi penggunaan:

• Berikan url untuk mengikis dan membuka halaman untuk interaksi dalam satu panggilan MCP.
• Berikan scrapeId untuk melanjutkan interaksi dengan halaman yang sudah dikikis.
• Berikan tepat satu dari url atau scrapeId, ditambah salah satu dari 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 yang diturunkan untuk tindak lanjut atau pembersihan.

11. Alat Stop Interact (firecrawl_interact_stop)

Hentikan sesi interaksi untuk halaman yang dikikis setelah 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.

Mencakup: Abstrak dan teks lengkap makalah di literatur biomedis, ilmu hayati, dan klinis (PubMed, bioRxiv, medRxiv) bersama arXiv dan sumber ilmiah lainnya.

Alat riset yang tersedia:

• firecrawl_research_search_papers: cari metadata dan abstrak makalah dengan kueri bahasa alami, dengan filter opsional penulis, kategori, dan tanggal.
• firecrawl_research_inspect_paper: ambil metadata kanonik untuk satu ID makalah (arXiv, PMC, PMID, atau DOI).
• firecrawl_research_related_papers: perluas dari satu atau lebih makalah jangkar melalui grafik kutipan.
• firecrawl_research_read_paper: baca bagian teks lengkap dari makalah tertentu.

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

firecrawl_search dengan categories: ["research"] adalah permukaan yang berbeda: ia memfilter hasil web biasa ke situs web yang berafiliasi dengan riset dan mengembalikan cuplikan halaman, bukan catatan makalah. Gunakan alat ini ketika pertanyaan tentang literatur itu sendiri, dan berikan beberapa kerangka berbeda dari pertanyaan yang sama — alat ini menampilkan makalah yang berbeda daripada satu kueri tunggal.

13. Alat Monitor (firecrawl_monitor_*)

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

Terbaik untuk:

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

Pola pembuatan yang direkomendasikan:

Gunakan page atau pages plus 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 peristiwa monitor.page.

Tulis tujuan sebagai instruksi monitor ringkas 2-3 kalimat. Sebutkan apa yang harus memicu peringatan, pertahankan ruang lingkup apa pun yang diberikan pengguna, dan sertakan pengecualian khusus-intensi hanya jika jelas dari permintaan. Kebisingan umum seperti spasi, perubahan hanya format, ID permintaan, parameter pelacakan, metadata umum, dan elemen halaman yang tidak terkait sudah ditangani oleh penilai, jadi jangan ulangi di setiap tujuan. Jika pengguna tidak jelas, pertahankan tujuan yang 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 perayapan, 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 bidang termasuk goal, judgeEnabled, webhook, dan notification.
• firecrawl_monitor_run: picu pemeriksaan sekarang.
• firecrawl_monitor_delete: hapus monitor (destruktif; hanya panggil ketika 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.

14. Alat Pencarian Pengembang (firecrawl_developer_search)

Cari indeks yang dibangun untuk agen pengkodean. Indeks mencakup masalah GitHub, permintaan tarik yang digabungkan, README repositori, dan situs dokumentasi terkurasi.

Terbaik untuk: Pertanyaan pemrograman — perilaku kode, pustaka atau kerangka kerja, kontrak API, pesan kesalahan, atau bug yang diketahui.

Argumen:

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

• query (wajib): pertanyaan pengembang atau frasa pencarian.
• k: jumlah hasil yang diperingkat. Default adalah 10 dan maksimum adalah 100.
• skills: atur ke "only" untuk mencari file keterampilan agen saja.

Mengembalikan: Hasil yang diperingkat. Setiap hasil membawa ID, jenis sumber (issue, pull_request, readme, atau doc), URL, judul, dan bagian yang cocok dalam markdown.

firecrawl_search dengan categories: ["developer"] mencari indeks yang sama di samping hasil web. Gunakan alat ini sebagai gantinya ketika Anda menginginkan bagian yang cocok, filter skills, atau tanpa hasil web dalam respons. Titik akhir khusus pencarian mengekspos kedua alat, dan pilihan yang sama berlaku di sana.

Sistem Pencatatan Log

Server mencakup pencatatan log yang komprehensif:

• Status dan kemajuan operasi
• Metrik kinerja
• Pelacakan batas tarif
• 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 kuat:

• Kesalahan batas tarif 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 tes: npm test
4. Kirim permintaan tarik

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 detail