Firecrawl

Firecrawl MCP Server

Server Model Context Protocol (MCP) yang menghadirkan Firecrawl ke agen AI yang kompatibel dengan MCP — cari, kikis (scrape), dan berinteraksi dengan web langsung untuk konteks yang bersih dan siap digunakan 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 pengodean: issue GitHub, pull request yang digabung, README, dan dokumentasi
• 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 (rate limiting)
• Dukungan cloud dan self-hosted
• Dukungan SSE

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

Instalasi

MCP Hosted (tingkat gratis tanpa kunci)

Hubungkan ke server remote hosted tanpa pengaturan apa pun:

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

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

Utamakan OAuth atau kunci API jika memungkinkan manusia mendaftar. Ini membuka seluruh rangkaian alat 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 menyambung ulang:

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 hosted dan panduan orientasi agen untuk petunjuk khusus klien.

Endpoint khusus pencarian

Permukaan khusus pencarian yang hanya-baca juga dihosting di:

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

Ini mengekspos satu set tetap dari 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 petunjuk konfigurasi terbaru, silakan merujuk ke dokumentasi resmi Cursor tentang konfigurasi server MCP: Panduan Konfigurasi Server MCP Cursor

Untuk mengonfigurasi Firecrawl MCP di Cursor v0.48.6

1. Buka Pengaturan Cursor
2. Buka Features > MCP Servers
3. Klik "+ Add new global MCP server"
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 Features > MCP Servers
3. Klik "+ Add New MCP Server"
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, muat ulang daftar server MCP untuk melihat alat baru. Composer Agent akan 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 pertanyaan 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 Streamable HTTP Local Mode

Untuk menjalankan server menggunakan Streamable HTTP 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 (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 User Settings (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 workspace 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 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 apa pun yang diselesaikannya ke Firecrawl API sebagai Authorization: Bearer ….

• Transport 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 memiliki prioritas di atas 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 penyegar (fcr_…) harus ditukar di endpoint token, bukan 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 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; 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. Penimpaan tersebut tidak mengonfigurasi ulang rute nginx yang dibundel atau daftar izin server otorisasi dan tidak boleh digunakan secara independen dalam penerapan 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 diinginkan: 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 sebuah situs: gunakan map
• Jika Anda ingin mencari info di web: 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 research tools — alat ini 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 kompleks di berbagai sumber yang tidak diketahui: 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 pengikisan yang lebih ketat

Tabel Referensi Cepat

Alat	Terbaik untuk	Mengembalikan
scrape	Konten satu halaman	JSON (disarankan) atau markdown
interact	Berinteraksi dengan URL atau halaman yang dikikis	Hasil eksekusi + scrapeId untuk mode URL
map	Menemukan URL di sebuah 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 info	results[]
developer	Pertanyaan pemrograman atas sumber pengembang	results[] dengan passages
agent	Riset multi-sumber yang kompleks	JSON (data terstruktur)
monitor	Pemeriksaan halaman berulang	metadata monitor/check dan diff
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 memerlukan data spesifik dari sebuah halaman. Definisikan 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 memerlukan konten halaman penuh, seperti membaca seluruh artikel untuk diringkas atau menganalisis struktur halaman.

Alat yang Tersedia

1. Alat Scrape (firecrawl_scrape)

Kikis konten dari satu URL dengan opsi lanjutan.

Terbaik untuk:

• Ekstraksi konten satu halaman, 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 search)

Kesalahan umum:

• Meneruskan daftar URL ke satu panggilan scrape. Panggil scrape sekali per URL di MCP. Jika Anda secara khusus memerlukan 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 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 yang ditentukan.

2. Alat Map (firecrawl_map)

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

Terbaik untuk:

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

Tidak direkomendasikan untuk:

• Ketika Anda sudah tahu URL spesifik yang Anda butuhkan (gunakan scrape)
• Ketika Anda membutuhkan konten dari halaman-halaman tersebut (gunakan scrape setelah mapping)

Kesalahan umum:

• Menggunakan crawl untuk menemukan URL, bukan 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. Search Tool (firecrawl_search)

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

Terbaik untuk:

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

Tidak direkomendasikan untuk:

• Ketika Anda sudah tahu situs web mana yang akan di-scrape (gunakan scrape)
• Ketika Anda membutuhkan cakupan menyeluruh 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": "remote work stipend policies at tech companies",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true,
      "redactPII": true
    }
  }
}

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

Untuk makalah ilmiah, lihat Research Tools: alat-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 di-scrape secara opsional), plus kolom id. Teruskan id tersebut ke firecrawl_search_feedback setelah Anda menggunakan hasilnya untuk mengembalikan 1 kredit (search memakan biaya 2) dan meningkatkan kualitas pencarian.

Contoh Prompt:

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

3b. Search Feedback Tool (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 yang buruk/sebagian dengan missingContent sama berharganya dengan umpan balik yang baik.

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

Kolom terpenting: missingContent. Ini adalah array dari bagian-bagian 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 sebuah tim mencapai dailyRefundCap, pengiriman selanjutnya tetap mencatat umpan balik tetapi tidak lagi mengembalikan kredit. Respons menetapkan dailyCapReached: true. Agen harus berhenti memanggil tool ini selama sisa hari UTC ketika mereka melihat tanda 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. Generic Feedback Tool (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 menggunakan firecrawl_search_feedback karena menyertakan 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.

Menonaktifkan: setel FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 (atau FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1) di lingkungan saat memulai server MCP. Tool 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. Crawl Tool (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, ketika Anda membutuhkan cakupan yang menyeluruh.

Tidak direkomendasikan untuk:

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

Kesalahan umum:

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

Contoh Prompt:

"Ambil semua posting 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 tersebut nanti.

5. Check Crawl Status (firecrawl_check_crawl_status)

Memeriksa status dan hasil dari pekerjaan crawl yang ada berdasarkan ID.

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

Mengembalikan:

• Respons menyertakan status pekerjaan crawl:

6. Parse Tool (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 membutuhkan keluaran markdown atau JSON terstruktur. MCP yang dihosting mendukung alur unggah-ref dua langkah; pembacaan file langsung secara lokal memerlukan FIRECRAWL_API_URL yang dihosting sendiri.

Tidak direkomendasikan 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 unggah berumur pendek dan nextToolCall, unggah file secara lokal, lalu panggil firecrawl_parse lagi dengan uploadRef yang dikembalikan. Membuat 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 dengan hanya kunci API cloud biasa tidak dapat membaca dan mengunggah file melalui tool 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 sekali 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"]
      }
    }
  }
}

Untuk URL yang tidak diketahui atau riset multi-sumber, gunakan firecrawl_search atau firecrawl_agent sebelum Scrape.

8. Agent Tool (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 ke firecrawl_agent_status untuk memeriksa kapan selesai dan mengambil hasilnya.

Alur asinkron:

1. Panggil firecrawl_agent dengan prompt/skema Anda → mengembalikan ID pekerjaan
2. Lakukan pekerjaan lain sementara agen melakukan riset (dapat memakan waktu beberapa menit untuk kueri yang kompleks)
3. Polling firecrawl_agent_status dengan ID pekerjaan untuk memeriksa kemajuan
4. Ketika status "completed", 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 direkomendasikan 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, maksimal 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" }
            }
          }
        }
      }
    }
  }
}

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

9. Check Agent Status (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 yang kompleks. Polling endpoint ini secara berkala (misalnya, setiap 10-30 detik) hingga status menjadi "completed" atau "failed".

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

Status yang mungkin:

• processing: Agen masih melakukan riset - periksa lagi nanti
• completed: Riset selesai - respons menyertakan data yang diekstrak
• failed: Terjadi kesalahan

10. Interact Tool (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 tool browser yang tidak digunakan lagi.

Opsi penggunaan:

• Teruskan url untuk melakukan scrape dan membuka halaman untuk interaksi dalam satu panggilan MCP.
• Teruskan scrapeId untuk melanjutkan interaksi dengan halaman yang sudah di-scrape.
• Teruskan tepat satu dari url atau scrapeId, plus 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. Stop Interact Tool (firecrawl_interact_stop)

Menghentikan sesi interaksi untuk halaman yang di-scrape ketika Anda selesai berinteraksi.

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

12. Research Tools (firecrawl_research_*)

Mencari dan memeriksa makalah serta repositori GitHub melalui tool MCP riset.

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

Tool riset yang tersedia:

• firecrawl_research_search_papers: mencari metadata dan abstrak makalah dengan kueri bahasa alami, dengan filter penulis, kategori, dan tanggal opsional.
• firecrawl_research_inspect_paper: mengambil metadata kanonik untuk satu ID makalah (arXiv, PMC, PMID, atau DOI).
• firecrawl_research_related_papers: memperluas dari satu atau lebih makalah jangkar melalui grafik kutipan.
• firecrawl_research_read_paper: membaca bagian teks lengkap dari makalah tertentu.
• firecrawl_research_search_github: mencari konten issue GitHub publik yang diindeks, pull-request, dan README.

Terbaik untuk: Tinjauan literatur, pencarian makalah, dan alur kerja penemuan repositori di mana agen membutuhkan permukaan riset yang terfokus alih-alih scraping 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 tool ini ketika pertanyaannya tentang literatur itu sendiri, dan teruskan beberapa kerangka berbeda dari pertanyaan yang sama — mereka memunculkan makalah yang berbeda daripada satu kueri tunggal.

13. Monitor Tools (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 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 berbahasa Inggris sederhana
• Melacak riwayat pemeriksaan dan perbedaan tingkat halaman

Pola pembuatan yang direkomendasikan: Use page atau pages plus goal. Server MCP membangun permintaan monitor dengan jadwal 30 menit dan API memungkinkan 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 yang ringkas dalam 2-3 kalimat. Sebutkan apa yang seharusnya memicu peringatan, pertahankan cakupan apa pun yang diberikan pengguna, dan sertakan pengecualian spesifik-intensi hanya jika jelas dari permintaan. Kebisingan umum seperti spasi, perubahan format saja, 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 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 perayapan, pelacakan perubahan JSON, retensi kustom, atau kontrol judgeEnabled yang 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: ambil 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: ambil 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 ini 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. Defaultnya adalah 10 dan maksimumnya 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-bagian tersebut dan tanpa hasil web. Titik akhir khusus pencarian tidak mengekspos alat ini; ia mempertahankan set tetap enam alatnya, dan firecrawl_search menjangkau indeks pengembang di sana.

Sistem Pencatatan Log

Server mencakup pencatatan log yang komprehensif:

• Status dan kemajuan operasi
• Metrik kinerja
• Pelacakan batas kecepatan
• 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 kecepatan API disampaikan ke klien MCP
• Pesan kesalahan yang 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