Firecrawl MCP

Firecrawl MCP Server

MCP uyumlu AI ajanlarına Firecrawl getiren bir Model Context Protocol (MCP) sunucusu — temiz, ajana hazır bağlam için canlı web'de arama, kazıma ve etkileşim.

İlk uygulama için @vrknetha ve @knacklabs'a büyük teşekkürler!

Özellikler

• Web'de arama yapın ve tam sayfa içeriği alın
• Kodlama ajanları için oluşturulmuş bir dizinde arama yapın: GitHub sorunları, birleştirilmiş pull request'ler, README'ler ve dokümanlar
• Herhangi bir URL'yi temiz, yapılandırılmış veriye dönüştürün
• Sayfalarla etkileşim kurun — tıklayın, gezinin ve işlem yapın
• Otonom ajan ile derin araştırma
• Otomatik yeniden denemeler ve hız sınırlama
• Bulut ve kendi kendine barındırma desteği
• SSE desteği

MCP.so'nun oyun alanındaki veya Klavis AI üzerindeki MCP Sunucumuzla denemeler yapın.

Kurulum

Barındırılan MCP (anahtarsız ücretsiz katman)

Kurulum gerektirmeden uzak barındırılan sunucuya bağlanın:

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

Anahtarsız ücretsiz katmanda, scrape, search ve parse API anahtarı olmadan çalışır (hız sınırlı). crawl, map ve agent gibi diğer araçlar hâlâ bir anahtar gerektirir.

İnsan kaydolabildiğinde OAuth veya API anahtarını tercih edin. Bu, tüm araç setini ve daha yüksek limitleri açar.

Etkileşimli bir hesap bağlantısı için MCP istemcinizi bu sunucu URL'sini kullanacak şekilde yapılandırın. Bu bir MCP uç noktasıdır, tarayıcı sayfası değildir; istemcinin hesap bağlantısı akışını kullanın ve yeniden bağlanırken ikinci bir Firecrawl sunucu girişi eklemeyin:

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

API anahtarı bağlantısı için (örneğin, gözetimsiz bir entegrasyon), sunucu URL'sini şu şekilde tutun:

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

Ardından istemcinin güvenli başlığını veya gizli ayarını şununla yapılandırın:

Authorization: Bearer <FIRECRAWL_API_KEY>

API anahtarını asla sunucu URL'sine koymayın. API anahtarını asla bir ajan sohbetine koymayın. Doğrudan istemcide veya gizli yöneticide yapılandırın. İstemciye özel talimatlar için barındırılan MCP kurulum kılavuzuna ve ajan katılım kılavuzuna bakın.

Yalnızca arama uç noktası

Salt okunur, yalnızca arama yapılabilen bir yüzey de şurada barındırılır:

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

Sabit bir altı salt okunur araç seti sunar: firecrawl_search ve beş firecrawl_research_* aracı. Sayfa içeriği getirme işlemi yapmaz ve kendi OAuth kimliğine sahiptir; yukarıdaki tam uç nokta değişmemiştir. Tam sözleşme için docs/search-profile.md bölümüne bakın.

npx ile Çalıştırma

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

Manuel Kurulum

npm install -g firecrawl-mcp

Cursor'da Çalıştırma

Cursor'ı Yapılandırma 🖥️ Not: Cursor sürümü 0.45.6+ gerektirir En güncel yapılandırma talimatları için lütfen MCP sunucularını yapılandırma hakkındaki resmi Cursor belgelerine bakın: Cursor MCP Sunucu Yapılandırma Kılavuzu

Firecrawl MCP'yi Cursor v0.48.6'da yapılandırmak için

1. Cursor Ayarları'nı açın
2. Özellikler > MCP Sunucuları'na gidin
3. "+ Yeni genel MCP sunucusu ekle" seçeneğine tıklayın
4. Aşağıdaki kodu girin:

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

Firecrawl MCP'yi Cursor v0.45.6'da yapılandırmak için

1. Cursor Ayarları'nı açın
2. Özellikler > MCP Sunucuları'na gidin
3. "+ Yeni MCP Sunucusu Ekle" seçeneğine tıklayın
4. Aşağıdakileri girin:
   • Ad: "firecrawl-mcp" (veya tercih ettiğiniz ad)
   • Tür: "command"
   • Komut: env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

Windows kullanıyorsanız ve sorun yaşıyorsanız, cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp" deneyin

your-api-key değerini Firecrawl API anahtarınızla değiştirin. Henüz bir anahtarınız yoksa, bir hesap oluşturup https://www.firecrawl.dev/app/api-keys adresinden alabilirsiniz.

Ekledikten sonra yeni araçları görmek için MCP sunucu listesini yenileyin. Composer Agent, uygun olduğunda Firecrawl MCP'yi otomatik olarak kullanacaktır, ancak web kazıma ihtiyaçlarınızı açıklayarak bunu açıkça talep edebilirsiniz. Composer'a Command+L (Mac) ile erişin, gönder düğmesinin yanındaki "Agent" seçeneğini seçin ve sorgunuzu girin.

Windsurf'da Çalıştırma

Bunu ./codeium/windsurf/model_config.json dosyanıza ekleyin:

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

Streamable HTTP Yerel Modu ile Çalıştırma

Sunucuyu varsayılan stdio taşıması yerine yerel olarak Streamable HTTP kullanarak çalıştırmak için:

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

URL'yi kullanın: http://localhost:3000/mcp

Smithery ile Kurulum (Eski)

Firecrawl'ı Smithery aracılığıyla Claude Desktop için otomatik olarak kurmak için:

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

VS Code'da Çalıştırma

Tek tıklamayla kurulum için aşağıdaki kurulum düğmelerinden birine tıklayın...

Manuel kurulum için aşağıdaki JSON bloğunu VS Code'daki Kullanıcı Ayarları (JSON) dosyanıza ekleyin. Bunu Ctrl + Shift + P tuşlarına basıp Preferences: Open User Settings (JSON) yazarak yapabilirsiniz.

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

İsteğe bağlı olarak, çalışma alanınızda .vscode/mcp.json adlı bir dosyaya ekleyebilirsiniz. Bu, yapılandırmayı başkalarıyla paylaşmanıza olanak tanır:

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

Yapılandırma

Ortam Değişkenleri

Bulut API'si için Gerekli

• FIRECRAWL_API_KEY: Firecrawl API anahtarınız
  • Bulut API'sini kullanırken gerekli (varsayılan)
  • FIRECRAWL_API_URL ile kendi kendine barındırılan örnek kullanılırken isteğe bağlı
• FIRECRAWL_API_URL (İsteğe bağlı): Kendi kendine barındırılan örnekler için özel API uç noktası
  • Örnek: https://firecrawl.your-domain.com
  • Sağlanmazsa bulut API'si kullanılır (API anahtarı gerektirir)

MCP OAuth (Bearer erişim belirteçleri)

Barındırılan Firecrawl, firecrawl.dev üzerindeki yetkilendirme sunucusu aracılığıyla OAuth erişim belirteçleri (fco_…) verebilir. Bu MCP sunucusu, çözdüğü kimlik bilgisini Firecrawl API'sine Authorization: Bearer … olarak iletir.

• HTTP akış taşımaları (CLOUD_SERVICE=true, HTTP_STREAMABLE_SERVER=true veya SSE_LOCAL=true): İstemciler MCP isteklerinde Authorization: Bearer <fco_access_token> göndermelidir. Her ikisi de mevcut olduğunda OAuth bearer belirteci x-firecrawl-api-key / x-api-key üzerinde önceliğe sahiptir.
• stdio: Statik bir erişim belirteci için FIRECRAWL_OAUTH_TOKEN kullanın veya bir API anahtarı için FIRECRAWL_API_KEY kullanmaya devam edin.

Yalnızca erişim belirteçlerini (fco_…) kullanın. Yenileme belirteçleri (fcr_…) belirteç uç noktasında değiştirilmelidir, kazıma/arama API'sine iletilmemelidir.

Yalnızca arama yüzeyi (barındırılan)

Barındırılan modda (CLOUD_SERVICE=true), ikinci bir işlem içi örnek yalnızca arama uç noktasına hizmet verir. Paketlenmiş hizmetin sabit bir dağıtım sözleşmesi vardır: nginx, /v2/mcp-search yolunu yerel bağlantı noktası 3001 üzerindeki örneğe yönlendirir ve OAuth korumalı kaynak tanımlayıcısı https://mcp.firecrawl.dev/v2/mcp-search'tir.

FIRECRAWL_MCP_SEARCH_ENABLED (varsayılan true) desteklenen operasyonel geçiştir; arama örneğinin başlamasını önlemek için false olarak ayarlayın. Node süreci ayrıca izole testler için FIRECRAWL_MCP_SEARCH_PORT, FIRECRAWL_MCP_SEARCH_ENDPOINT ve FIRECRAWL_MCP_SEARCH_RESOURCE_URL değerlerini kabul eder. Bu geçersiz kılmalar, paketlenmiş nginx yollarını veya yetkilendirme sunucusu izin listesini yeniden yapılandırmaz ve barındırılan dağıtımda bağımsız olarak kullanılmamalıdır.

Arama örneği her istek için kimlik doğrulaması gerektirir (tools/list dahil) ve hedef kitlesi kendi kaynağıyla eşleşmeyen OAuth belirteçlerini reddeder.

Yapılandırma Örnekleri

Bulut API'si kullanımı için:

export FIRECRAWL_API_KEY=your-api-key

Kendi kendine barındırılan örnek için:

# 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

Claude Desktop ile Kullanım

Bunu claude_desktop_config.json dosyanıza ekleyin:

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

Araç Nasıl Seçilir

Göreviniz için doğru aracı seçmek üzere bu kılavuzu kullanın:

• İstediğiniz URL'yi tam olarak biliyorsanız: scrape kullanın (yapılandırılmış veriler için JSON biçimiyle)
• Birden fazla bilinen URL'niz varsa: her URL için scrape çağırın. Özellikle tek bir toplu API işlemine ihtiyacınız varsa, MCP dışında Firecrawl API toplu uç noktasını kullanın.
• Bir sitedeki URL'leri keşfetmeniz gerekiyorsa: map kullanın
• Web'de bilgi aramak istiyorsanız: search kullanın
• Bir programlama sorunuz varsa (bir kitaplık, bir API sözleşmesi, bir hata mesajı, bilinen bir hata): developer search kullanın
• Bilimsel makalelere ihtiyacınız varsa (biyomedikal, yaşam bilimleri, klinik veya arXiv literatürü): research araçlarını kullanın — makale özetlerini ve tam metinlerini ararlar. categories: ["research"] ile search farklı bir şeydir: sıradan web sonuçları üzerinde bir web sitesi filtresi.
• Birden fazla bilinmeyen kaynakta karmaşık araştırmaya ihtiyacınız varsa: agent kullanın
• Tüm bir siteyi veya bölümü analiz etmek istiyorsanız: crawl kullanın (limitlerle!)
• Etkileşimli tarayıcı otomasyonuna ihtiyacınız varsa (tıklama, yazma, gezinme): yeni bir sayfa için bir URL ile interact kullanın veya sayfayı zaten kazıdıysanız ya da daha sıkı kazıma kontrolüne ihtiyacınız varsa scrape + interact kullanın

Hızlı Referans Tablosu

Araç	En uygun olduğu durumlar	Döndürür
scrape	Tek sayfa içeriği	JSON (tercih edilen) veya markdown
interact	Bir URL veya kazınmış sayfayla etkileşim	Yürütme sonucu + URL modu için scrapeId
map	Bir sitedeki URL'leri keşfetme	URL[]
crawl	Çok sayfalı çıkarma (limitlerle)	dahili yoklama sonrası nihai crawl durumu/verisi
parse	Dosyalar ve barındırılan yükleme referansları	markdown, JSON veya belge çıktısı
search	Bilgi için web araması	results[]
developer	Geliştirici kaynakları üzerinde programlama soruları	pasajlarla birlikte results[]
agent	Karmaşık çok kaynaklı araştırma	JSON (yapılandırılmış veri)
monitor	Tekrarlayan sayfa kontrolleri	monitor/check meta verileri ve farklar
research	Makale ve GitHub deposu araştırması	araştırma sonuçları ve depo eşleşmeleri

Biçim Seçim Kılavuzu

scrape kullanırken doğru biçimi seçin:

• JSON biçimi (çoğu durumda önerilir): Bir sayfadan belirli verilere ihtiyacınız olduğunda kullanın. Çıkarmanız gerekenlere göre bir şema tanımlayın. Bu, yanıtları küçük tutar ve bağlam penceresi taşmasını önler.
• Markdown biçimi (idareli kullanın): Yalnızca gerçekten tam sayfa içeriğine ihtiyacınız olduğunda, örneğin özetleme için tüm bir makaleyi okumak veya sayfa yapısını analiz etmek gibi durumlarda.

Mevcut Araçlar

1. Scrape Aracı (firecrawl_scrape)

Gelişmiş seçeneklerle tek bir URL'den içerik kazıyın.

En uygun olduğu durumlar:

• Bilgiyi tam olarak hangi sayfanın içerdiğini bildiğinizde tek sayfa içeriği çıkarma.

Önerilmediği durumlar:

• Birden fazla sayfadan içerik çıkarma (bilinen URL'ler için tekrarlanan scrape çağrıları kullanın veya önce URL'leri keşfetmek için map + scrape kullanın veya tam sayfa içeriği için crawl kullanın)
• Bilginin hangi sayfada olduğundan emin olmadığınızda (search kullanın)

Yaygın hatalar:

• Tek bir scrape çağrısına URL listesi geçmek. MCP'de her URL için scrape'i bir kez çağırın. Özellikle tek bir toplu API işlemine ihtiyacınız varsa, MCP dışında Firecrawl API toplu uç noktasını kullanın.
• Varsayılan olarak markdown biçimi kullanmak (yalnızca ihtiyacınız olanı çıkarmak için JSON biçimini kullanın).

Doğru biçimi seçme:

• JSON biçimi (tercih edilen): Çoğu kullanım durumunda, yalnızca gereken belirli verileri çıkarmak için bir şemayla JSON biçimini kullanın. Bu, yanıtları odaklı tutar ve bağlam penceresi taşmasını önler.
• Markdown biçimi: Yalnızca görev gerçekten tam sayfa içeriği gerektirdiğinde (ör. tüm bir makaleyi özetleme, sayfa yapısını analiz etme).

İstem Örneği:

"https://example.com/product. adresinden ürün ayrıntılarını al"

Kullanım Örneği (JSON biçimi - tercih edilen):

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

Kullanım Örneği (markdown biçimi - tam içerik gerektiğinde):

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

Kullanım Örneği (marka biçimi - marka kimliğini çıkarma):

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

Marka biçimi: Tasarım analizi veya stil kopyalama için kapsamlı marka kimliğini (renkler, yazı tipleri, tipografi, boşluklar, logo, UI bileşenleri) çıkarır. Gizlilik: Kişisel olarak tanımlanabilir bilgileri gizlenmiş içerik döndürmek için redactPII: true değerini ayarlayın.

Döndürür:

• JSON yapılandırılmış veri, markdown, marka profili veya belirtilen diğer biçimler.

2. Map Aracı (firecrawl_map)

Sitedeki tüm dizinlenmiş URL'leri keşfetmek için bir web sitesini haritalayın.

En uygun olduğu durumlar:

• Bir web sitesini kazımadan önce URL'leri keşfetmek
• Bir web sitesinin belirli bölümlerini bulmak

Şunlar için önerilmez:

• Hangi belirli URL'ye ihtiyacınız olduğunu zaten bildiğinizde (scrape kullanın)
• Sayfaların içeriğine ihtiyacınız olduğunda (haritalamadan sonra scrape kullanın)

Sık yapılan hatalar:

• URL'leri keşfetmek için crawl yerine map kullanmak

İstek Örneği:

"example.com'daki tüm URL'leri listele."

Kullanım Örneği:

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

Döndürür:

• Sitede bulunan URL dizisi

3. Arama Aracı (firecrawl_search)

Web'de arama yapın ve isteğe bağlı olarak arama sonuçlarından içerik çıkarın.

Şunlar için en uygun:

• Hangi web sitesinin bilgiye sahip olduğunu bilmediğinizde, birden fazla web sitesinde belirli bilgileri bulmak.
• Bir sorgu için en alakalı içeriğe ihtiyacınız olduğunda

Şunlar için önerilmez:

• Hangi web sitesini kazıyacağınızı zaten bildiğinizde (scrape kullanın)
• Tek bir web sitesinin kapsamlı kapsamına ihtiyacınız olduğunda (map veya crawl kullanın)

Sık yapılan hatalar:

• Açık uçlu sorular için crawl veya map kullanmak (bunun yerine search kullanın)

Kullanım Örneği:

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

Sorguyla ilgili vurguları istemek için highlights değerini true olarak ayarlayın veya orijinal arama parçacıklarını korumak için false olarak ayarlayın. API'nin varsayılan davranışını kullanmak için boş bırakın.

Bilimsel makaleler için Araştırma Araçları bölümüne bakın: bunlar makale özetlerini ve tam metinleri arar; buradaki categories: ["research"] ise normal web sonuçlarını araştırma bağlantılı web sitelerine göre filtreler.

Döndürür:

• (İsteğe bağlı kazınmış içerikle birlikte) arama sonuçları dizisi ve bir id alanı. Sonuçları kullandıktan sonra bu id değerini firecrawl_search_feedback aracına iletin; böylece 1 kredi iadesi alırsınız (arama 2 kredi tutar) ve arama kalitesini artırırsınız.

İstek Örneği:

"Teknoloji şirketlerindeki uzaktan çalışma ödeneği politikalarını karşılaştır."

3b. Arama Geri Bildirim Aracı (firecrawl_search_feedback)

Önceki bir firecrawl_search sonucu hakkında yapılandırılmış geri bildirim gönderir. Arama kimliği başına ilk geri bildirim 1 kredi iadesi sağlar ve Firecrawl'ın arama kalitesini artırır. Arama kimliği başına idempotenttir.

Gerçekten kullandığınız her aramadan sonra bunu çağırın (veya işe yaramayanlardan sonra). missingContent ile kötü/kısmi geri bildirim, iyi geri bildirim kadar değerlidir.

Devre dışı bırakma: MCP sunucusunu başlatırken ortamda FIRECRAWL_NO_SEARCH_FEEDBACK=1 (veya FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1) ayarlayın. firecrawl_search_feedback aracı kaydedilmez, böylece aracılar onu çağıramaz. Ekip yöneticileri ayrıca geri bildirimi sunucu tarafında devre dışı bırakabilir; bu durumda araç kayıtlıdır ancak her zaman feedbackErrorCode: "TEAM_OPTED_OUT" döndürür.

En önemli alan: missingContent. Aracının bulmayı beklediği ancak bulamadığı belirli içerik parçalarının bir dizisidir. Eksik konu başına bir girdi — bunlar ekipler arasında toplanır ve bize sırada neyi dizine ekleyeceğimizi söyler.

Günlük iade limiti (ekip başına, UTC günü başına, varsayılan 100 kredi). Bir ekibin creditsRefundedToday değeri dailyRefundCap değerine ulaştığında, sonraki gönderimler geri bildirimi yine kaydeder ancak kredi iadesi yapmaz. Yanıt dailyCapReached: true değerini ayarlar. Aracılar, bu bayrağı gördüklerinde UTC gününün geri kalanı için bu aracı çağırmayı bırakmalıdır.

Kullanım Örneği:

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

Döndürür:

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

3c. Genel Geri Bildirim Aracı (firecrawl_feedback)

Tamamlanmış bir v2 uç noktası işi için /v2/feedback aracılığıyla yapılandırılmış geri bildirim gönderir. scrape, parse, map veya search işleri için uç nokta düzeyinde geri bildirim için bunu kullanın. Özellikle arama sonucu kalitesi için firecrawl_search_feedback aracını tercih edin çünkü aramaya özel yönergeler içerir.

Geri bildirimi kısa tutun: sorun kodları, etiketler, kısa notlar, URL'ler, sayfa numaraları ve küçük meta veri nesneleri kullanın. Ham kazıma/ayrıştırma çıktılarını dahil etmeyin.

Devre dışı bırakma: MCP sunucusunu başlatırken ortamda FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 (veya FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1) ayarlayın. firecrawl_feedback aracı kaydedilmez, böylece aracılar onu çağıramaz.

Kullanım Örneği:

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

Döndürür:

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

4. Crawl Aracı (firecrawl_crawl)

Bir crawl işi başlatır, son duruma ulaşana kadar yoklar ve son crawl durumunu/verilerini döndürür.

Şunlar için en uygun:

• Kapsamlı kapsama ihtiyacınız olduğunda, birden fazla ilgili sayfadan içerik çıkarmak.

Şunlar için önerilmez:

• Tek bir sayfadan içerik çıkarmak (scrape kullanın)
• Token limitlerinin endişe verici olduğu durumlarda (daha sıkı kontrol için map + scrape kullanın)
• Hızlı sonuçlara ihtiyacınız olduğunda (crawl yavaş olabilir)

Uyarı: Crawl yanıtları çok büyük olabilir ve token limitlerini aşabilir. Crawl derinliğini ve sayfa sayısını sınırlayın veya daha sıkı kontrol için map + scrape kullanın.

Sık yapılan hatalar:

• limit veya maxDiscoveryDepth değerini çok yüksek ayarlamak (token taşmasına neden olur)
• Tek bir sayfa için crawl kullanmak (bunun yerine scrape kullanın)

İstek Örneği:

"example.com/blog adresinin ilk iki seviyesindeki tüm blog yazılarını al."

Kullanım Örneği:

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

Döndürür:

• Dahili yoklama sonrası nihai crawl durumu ve verileri; id, status, completed, total, creditsUsed, expiresAt, next ve data dahil. İşi daha sonra yeniden kontrol etmeniz gerekirse döndürülen id değerini firecrawl_check_crawl_status ile birlikte kullanın.

5. Crawl Durumunu Kontrol Et (firecrawl_check_crawl_status)

Kimliğe göre mevcut bir crawl işinin durumunu ve sonuçlarını kontrol edin.

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

Döndürür:

• Yanıt, crawl işinin durumunu içerir:

6. Ayrıştırma Aracı (firecrawl_parse)

Firecrawl'ın /v2/parse uç noktasıyla yerel dosyaları veya barındırılan yükleme referanslarını ayrıştırın.

Şunlar için en uygun: Markdown veya yapılandırılmış JSON çıktısı gerektiren PDF'ler, Word belgeleri, elektronik tablolar, HTML dosyaları ve diğer belgeler. Barındırılan MCP, iki adımlı bir yükleme-başvuru akışını destekler; yerel doğrudan dosya okumaları, kendi kendine barındırılan bir FIRECRAWL_API_URL gerektirir.

Şunlar için önerilmez: Uzak URL'ler (scrape kullanın), tek çağrıda birden fazla dosya (dosya başına bir kez parse çağırın) veya ekran görüntüleri ve tıklamalar gibi yalnızca tarayıcı eylemleri.

Barındırılan MCP akışı: Barındırılan MCP, çağıranın dosya sistemini doğrudan okuyamaz. Kısa ömürlü bir yükleme komutu ve nextToolCall almak için firecrawl_parse aracını filePath ile çağırın, dosyayı yerel olarak yükleyin, ardından döndürülen uploadRef ile firecrawl_parse aracını tekrar çağırın. Barındırılan yükleme URL'sinin basılması Firecrawl kimlik doğrulaması veya anahtarsız uygunluk gerektirir. Yerel npx firecrawl-mcp modunda, doğrudan dosya ayrıştırma şu anda kendi kendine barındırılan bir Firecrawl API'sine işaret eden FIRECRAWL_API_URL gerektirir; yalnızca bulut API anahtarına sahip yerel bir sunucu bu araç aracılığıyla dosyaları okuyamaz ve yükleyemez.

Kullanım Örneği:

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

Döndürür: Ayrıştırılmış belge içeriği veya bir nextToolCall içeren barındırılan yükleme talimatları.

7. Scrape JSON ile yapılandırılmış veri

Bilinen bir sayfadan yapılandırılmış veri için, URL başına bir kez firecrawl_scrape aracını formats: ["json"] ile çağırın. Çıkarma istemini ve JSON şemasını jsonOptions içine koyun.

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

Bilinmeyen URL'ler veya çok kaynaklı araştırma için, Scrape'ten önce firecrawl_search veya firecrawl_agent kullanın.

8. Aracı Aracı (firecrawl_agent)

Otonom web araştırma aracısı. Bu, bağımsız olarak internette gezen, bilgi arayan, sayfalarda gezinen ve sorgunuza dayalı yapılandırılmış veri çıkaran ayrı bir AI aracı katmanıdır.

Nasıl çalışır:

Aracı web aramaları yapar, bağlantıları takip eder, sayfaları okur ve verileri otonom olarak toplar. Bu asenkron çalışır - hemen bir iş kimliği döndürür ve tamamlanıp tamamlanmadığını kontrol etmek ve sonuçları almak için firecrawl_agent_status aracını yoklarsınız.

Asenkron iş akışı:

1. İsteminiz/şemanızla firecrawl_agent aracını çağırın → iş kimliği döndürür
2. Aracı araştırırken başka işler yapın (karmaşık sorgular dakikalar sürebilir)
3. İlerlemeyi kontrol etmek için iş kimliğiyle firecrawl_agent_status aracını yoklayın
4. Durum "completed" olduğunda, yanıt çıkarılan verileri içerir

Şunlar için en uygun:

• Tam URL'leri bilmediğiniz karmaşık araştırma görevleri
• Çok kaynaklı veri toplama
• Web'e dağılmış bilgileri bulma
• Sonuçları beklerken başka işler yapabileceğiniz görevler

Şunlar için önerilmez:

• URL'yi bildiğiniz basit tek sayfa kazıma (JSON formatıyla scrape kullanın - daha hızlı ve daha ucuz)

Bağımsız değişkenler:

• prompt: İstediğiniz verinin doğal dil açıklaması (zorunlu, en fazla 10.000 karakter)
• urls: Aracıyı belirli sayfalara odaklamak için isteğe bağlı URL dizisi
• schema: Yapılandırılmış çıktı için isteğe bağlı JSON şeması

İstek Örneği:

"Firecrawl'ın kurucularını ve geçmişlerini bul"

Kullanım Örneği (aracıyı başlat, ardından sonuçlar için yokla):

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

Ardından döndürülen iş kimliğini kullanarak firecrawl_agent_status ile yoklayın.

Kullanım Örneği (URL'lerle - aracı belirli sayfalara odaklanır):

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

Döndürür:

• Durum kontrolü için iş kimliği. Sonuçları yoklamak için firecrawl_agent_status kullanın.

9. Aracı Durumunu Kontrol Et (firecrawl_agent_status)

Bir aracı işinin durumunu kontrol edin ve tamamlandığında sonuçları alın. Bir aracıyı başlattıktan sonra sonuçları yoklamak için bunu kullanın.

Yoklama düzeni: Aracı araştırması karmaşık sorgular için dakikalar sürebilir. Durum "completed" veya "failed" olana kadar bu uç noktayı periyodik olarak (ör. her 10-30 saniyede bir) yoklayın.

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

Olası durumlar:

• processing: Aracı hâlâ araştırıyor - daha sonra tekrar kontrol edin
• completed: Araştırma bitti - yanıt çıkarılan verileri içerir
• failed: Bir hata oluştu

10. Etkileşim Aracı (firecrawl_interact)

Yeni bir URL ile veya firecrawl_scrape tarafından daha önce açılmış bir sayfayla etkileşim kurun.

Şunlar için en uygun: Kullanımdan kaldırılmış tarayıcı araçlarını geri yüklemeden dinamik sayfalarda tıklama, yazma, gezinme ve durum çıkarma.

Kullanım seçenekleri:

• Tek bir MCP çağrısında bir sayfayı kazımak ve etkileşim için açmak üzere url iletin.
• Mevcut bir kazınmış sayfayla etkileşime devam etmek için scrapeId iletin.
• url veya scrapeId değerlerinden tam olarak birini, ayrıca prompt veya code değerlerinden birini iletin.

Kullanım Örneği:

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

Döndürür: Etkileşim sonucu ve URL modunda, takip veya temizlik için türetilen scrapeId.

11. Etkileşimi Durdur Aracı (firecrawl_interact_stop)

Etkileşiminiz bittiğinde kazınmış bir sayfa için etkileşim oturumunu durdurun.

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

12. Araştırma Araçları (firecrawl_research_*)

Araştırma MCP araçları aracılığıyla makaleleri ve GitHub depolarını arayın ve inceleyin.

Kapsar: PubMed, bioRxiv, medRxiv ile arXiv ve diğer bilimsel kaynaklar dahil biyomedikal, yaşam bilimleri ve klinik literatürdeki makale özetleri ve tam metinler.

Mevcut araştırma araçları:

• firecrawl_research_search_papers: isteğe bağlı yazar, kategori ve tarih filtreleriyle doğal dil sorgusu kullanarak makale meta verilerini ve özetlerini arayın.
• firecrawl_research_inspect_paper: bir makale kimliği (arXiv, PMC, PMID veya DOI) için kurallı meta verileri alın.
• firecrawl_research_related_papers: alıntı grafiği aracılığıyla bir veya daha fazla çapa makalesinden genişletin.
• firecrawl_research_read_paper: belirli bir makaleden tam metin pasajlarını okuyun.
• firecrawl_research_search_github: dizine eklenmiş genel GitHub sorun, çekme isteği ve README içeriğini arayın.

Şunlar için en uygun: Aracının genel web kazıma yerine odaklanmış bir araştırma yüzeyine ihtiyaç duyduğu literatür taraması, makale arama ve depo keşfi iş akışları.

firecrawl_search ile categories: ["research"] farklı bir yüzeydir: normal web sonuçlarını araştırma bağlantılı web sitelerine göre filtreler ve makale kayıtları yerine sayfa parçacıkları döndürür. Soru literatürün kendisiyle ilgiliyse bu araçları kullanın ve aynı sorunun birkaç farklı çerçevesini iletin — tek bir sorgudan farklı makaleler yüzeye çıkarırlar.

13. İzleme Araçları (firecrawl_monitor_*)

Yinelenen sayfa izleyicileri oluşturun ve yönetin. İzleyiciler zamanlanmış kazımalar veya taramalar çalıştırır, her sonucu son saklanan anlık görüntüyle karşılaştırır ve webhook veya e-posta ile bildirim gönderebilir.

Şunlar için en uygun:

• Zaman içinde bir sayfayı veya birkaç sayfayı izlemek
• Düz İngilizce bir hedef kullanarak anlamlı değişiklikler hakkında uyarı vermek
• Kontrol geçmişini ve sayfa düzeyinde farkları takip etmek

Önerilen oluşturma düzeni: Use page veya pages artı goal kullanın. MCP sunucusu, 30 dakikalık bir zamanlama ile izleme isteğini oluşturur ve API, anlamlı değişiklik değerlendirmesini otomatik olarak etkinleştirir.

Anlamlı değişiklik değerlendirmesi, goal ayarlandığında otomatik olarak çalışır. Sayfa webhook'ları, monitor.page olaylarında isMeaningful ve judgment değerlerini açığa çıkarır.

Hedefleri, 2-3 cümlelik kısa izleme talimatları olarak yazın. Hangi durumun uyarı tetiklemesi gerektiğini belirtin, kullanıcının verdiği kapsamı koruyun ve yalnızca istekten açıkça anlaşıldığında amaca özel hariç tutmalar ekleyin. Boşluk, yalnızca biçimlendirme değişiklikleri, istek kimlikleri, izleme parametreleri, genel meta veriler ve ilgisiz sayfa öğeleri gibi genel gürültü, değerlendirici tarafından zaten ele alınır; bu nedenle bunları her hedefte tekrarlamayın. Kullanıcı belirsizse hedefi geniş tutun; geniş izleme veya "herhangi bir değişiklik" isterse bunu koruyun. Kullanıcı bir şeyi umursamadığını söylerse, bunu açıkça ekleyin.

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

Webhook'lu birden fazla sayfa:

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

Gelişmiş oluşturma istekleri:

Tarama hedefleri, JSON değişiklik takibi, özel saklama süresi veya açık judgeEnabled kontrolü gerektiğinde body değerini iletin.

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

Diğer izleme araçları:

• firecrawl_monitor_list: izleyicileri listeler.
• firecrawl_monitor_get: tek bir izleyiciyi getirir.
• firecrawl_monitor_update: goal, judgeEnabled, webhook ve notification dahil alanları günceller.
• firecrawl_monitor_run: hemen bir kontrol tetikler.
• firecrawl_monitor_delete: bir izleyiciyi siler (yıkıcıdır; yalnızca kullanıcı kaldırmayı amaçladığında çağırın).
• firecrawl_monitor_checks: isteğe bağlı olarak duruma göre filtrelenmiş kontrolleri listeler.
• firecrawl_monitor_check: diff, snapshot, judgment.meaningful ve judgment.meaningfulChanges dahil sayfa düzeyinde sonuçları getirir.

14. Geliştirici Arama Aracı (firecrawl_developer_search)

Kodlama ajanları için oluşturulmuş bir dizinde arama yapın. Dizin, GitHub sorunlarını, birleştirilmiş çekme isteklerini, depo README dosyalarını ve seçilmiş dokümantasyon sitelerini kapsar.

En uygun: Bir programlama sorusu — kod davranışı, bir kütüphane veya çerçeve, bir API sözleşmesi, bir hata mesajı veya bilinen bir hata.

Bağımsız değişkenler:

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

• query (gerekli): geliştirici sorusu veya arama ifadesi.
• k: sıralanmış sonuç sayısı. Varsayılan 10, maksimum 100'dür.
• skills: yalnızca ajan beceri dosyalarını aramak için "only" olarak ayarlayın.

Döndürür: Sıralanmış sonuçlar. Her sonuç bir kimlik, kaynak türü (issue, pull_request, readme veya doc), bir URL, bir başlık ve markdown biçiminde eşleşen pasajlar taşır.

firecrawl_search ile categories: ["developer"], web sonuçlarının yanında aynı dizini arar. Pasajları isteyip web sonuçları istemediğinizde bunun yerine bu aracı kullanın. Yalnızca arama uç noktası bu aracı açığa çıkarmaz; sabit altı araçlık setini korur ve firecrawl_search orada geliştirici dizinine ulaşır.

Günlükleme Sistemi

Sunucu kapsamlı günlükleme içerir:

• İşlem durumu ve ilerleme
• Performans metrikleri
• Hız sınırı takibi
• Hata koşulları

Örnek günlük mesajları:

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

Hata Yönetimi

Sunucu sağlam hata yönetimi sağlar:

• MCP istemcisine yansıtılan API hız sınırı hataları
• Ayrıntılı hata mesajları
• Ağ dayanıklılığı

Örnek hata yanıtı:

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

Geliştirme

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Katkıda Bulunma

1. Depoyu çatallayın
2. Özellik dalınızı oluşturun
3. Testleri çalıştırın: npm test
4. Bir çekme isteği gönderin

Katkıda bulunanlara teşekkürler

İlk uygulama için @vrknetha, @cawstudios adlı kişilere teşekkürler!

Sunucumuzu barındırdıkları için MCP.so ve Klavis AI'ye ve entegre ettikleri için @gstarwd, @xiangkaiz ve @zihaolin96 adlı kişilere teşekkürler.

Lisans

MIT Lisansı - ayrıntılar için LICENSE dosyasına bakın