Firecrawl

Firecrawl MCP Sunucusu

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

@vrknetha ve @knacklabs'a ilk uygulama için 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ş çekme istekleri, README'ler ve dokümanlar
• Herhangi bir URL'yi temiz, yapılandırılmış verilere kazıyı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ında MCP Sunucumuzu veya Klavis AI üzerinde deneyin.

Bu Sunucuyu Ne Zaman Kullanmalı

• Bilinen bir URL'niz olduğunda ve içeriğini markdown veya sağladığınız bir şemayla eşleşen JSON olarak istediğinizde firecrawl_scrape kullanın.
• Bir sitedeki URL'leri içeriklerini getirmeden keşfetmeniz gerektiğinde firecrawl_map kullanın.
• Bir site altındaki birçok sayfadan içerik almanız gerektiğinde firecrawl_crawl kullanın; sınırlamak için limit, includePaths/excludePaths veya maxDiscoveryDepth ayarlayın.
• Bir URL'den değil de bir sorgudan başlayıp sıralanmış web sonuçları istediğinizde firecrawl_search kullanın; aynı çağrıda sayfa içeriğinin de getirilmesini istiyorsanız scrapeOptions ekleyin (yalnızca arama uç noktası asla içerik getirmez).
• Bir sayfayı okuyabilmeniz için tıklama, yazma veya gezinme eylemi gerektiğinde firecrawl_interact kullanın — yeni bir sayfa için url veya daha önce kazıdığınız bir sayfada devam etmek için scrapeId iletin.
• Aynı sayfanın tek seferlik getirilmesi yerine, farklar ve değişiklik uyarılarıyla yinelenen bir programda kontrol edilmesi gerektiğinde firecrawl_monitor_* araçlarını kullanın.
• Kendi yeniden deneme ve sonlandırma mantığınızla bir tarayıcı oturumunu birçok kendi adımınız boyunca açık tutmanız gerektiğinde başka bir şey düşünün: her firecrawl_interact çağrısı bir prompt veya code turunu tamamlanana kadar çalıştırır ve kontrolü geri verir — oturum scrapeId aracılığıyla çağrılar arasında devam edebilir ve firecrawl_interact_stop ile sona erer, ancak tek bir çağrı içinde istemci tarafından adım adım etkileşimli olarak süremezsiniz.

Bu sunucu, tam profil varsayılan ayarlarla kaydedildiğinde 25 araç listeler (geri bildirim araçları dahil, yerel anahtarsız modda çalışmıyor). FIRECRAWL_NO_SEARCH_FEEDBACK=1 ve/veya FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 ayarlamak ilgili geri bildirim araçlarını kaldırır ve bu sayıyı azaltır; yerel anahtarsız başlatma da aynı şekilde. Araç yuvası sınırı olan istemciler için: barındırılan anahtarsız uç nokta (https://mcp.firecrawl.dev/v2/mcp, API anahtarı yok) yalnızca 3'ünü sunar — firecrawl_scrape, firecrawl_search, firecrawl_parse — ve özel yalnızca arama uç noktası (https://mcp.firecrawl.dev/v2/mcp-search) sabit 6 salt okunur araç sunar.

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 bir API anahtarını tercih edin. Tam 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ğil; istemcinin hesap bağlantı akışını kullanın ve yeniden bağlanırken ikinci bir Firecrawl sunucu girişi eklemeyin:

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

Bir 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ık 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 istemciye veya gizli yöneticiye yapılandırın. İstemciye özel talimatlar için barındırılan MCP kurulum kılavuzuna ve ajan yerleştirme kılavuzuna bakın.

Yalnızca arama uç noktası

Salt okunur, yalnızca arama yüzeyi de şurada barındırılır:

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

Sabit altı salt okunur araç seti sunar: firecrawl_search, firecrawl_developer_search ve dört firecrawl_research_* aracı. Sayfa içeriği getirme yapmaz ve kendi OAuth kimliğine sahiptir; yukarıdaki tam uç nokta değişmez. Tam sözleşme için docs/search-profile.md dosyasına 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 dokümantasyonuna bakın: Cursor MCP Sunucu Yapılandırma Kılavuzu

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

1. Cursor Ayarları'nı açın
2. Özellikler > MCP Sunucuları'na gidin
3. "+ Yeni genel MCP sunucusu ekle"ye 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 içinde yapılandırmak için

1. Cursor Ayarları'nı açın
2. Özellikler > MCP Sunucuları'na gidin
3. "+ Yeni MCP Sunucusu Ekle"ye tıklayın
4. Aşağıdakileri girin:
   • Ad: "firecrawl-mcp" (veya tercih ettiğiniz ad)
   • Tür: "komut"
   • 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 Ajanı, uygun olduğunda Firecrawl MCP'yi otomatik olarak kullanacaktır, ancak web kazıma ihtiyaçlarınızı açıklayarak açıkça talep edebilirsiniz. Composer'a Command+L (Mac) ile erişin, gönder düğmesinin yanında "Ajan"ı seçin ve sorgunuzu girin.

Windsurf'te Ç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 Mod ile Çalıştırma

Sunucuyu varsayılan stdio taşıma 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, VS Code'daki Kullanıcı Ayarları (JSON) dosyanıza aşağıdaki JSON bloğunu ekleyin. Bunu Ctrl + Shift + P tuşuna basarak ve 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 için Gerekli

• FIRECRAWL_API_KEY: Firecrawl API anahtarınız
  • Bulut API kullanılı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 kullanılacaktı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. Bir OAuth bearer belirteci, her ikisi de mevcut olduğunda x-firecrawl-api-key / x-api-key üzerinde öncelik alır.
• 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_…), kazıma/arama API'sine iletilmemeli, belirteç uç noktasında değiştirilmelidir.

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ını sunar. Paketlenmiş hizmetin sabit bir dağıtım sözleşmesi vardır: nginx, /v2/mcp-search adresini 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'dir.

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 işlemi ayrıca izole testler için FIRECRAWL_MCP_SEARCH_PORT, FIRECRAWL_MCP_SEARCH_ENDPOINT ve FIRECRAWL_MCP_SEARCH_RESOURCE_URL kabul eder. Bu geçersiz kılmalar, paketlenmiş nginx yollarını veya yetkilendirme sunucusu beyaz 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ğrulama gerektirir (tools/list dahil) ve hedef kitlesi kendi kaynağıyla eşleşmeyen OAuth belirteçlerini reddeder.

Yapılandırma Örnekleri

Bulut API 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:

• Tam URL'yi biliyorsanız: scrape kullanın (yapılandırılmış veriler için JSON formatıyla)
• Birden çok bilinen URL'niz varsa: her URL için scrape çağrısı yapın. Özellikle tek bir toplu API işlemi gerekiyorsa, 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
• Programlama sorununuz 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 metnini ararlar. search ile categories: ["research"] farklı bir şeydir: sıradan web sonuçları üzerinde bir web sitesi filtresi.
• Yapılandırılmış veri döndüren çok kaynaklı araştırmaya ihtiyacınız varsa, URL'leri bilmiyorsanız veya yanıt birden çok siteye yayılıyorsa (bir varlık ve alanları, bir liste, bir veri kümesi): 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 veya daha sıkı kazıma kontrolüne ihtiyacınız varsa scrape + interact kullanın

Hızlı Referans Tablosu

Araç	En İyi Kullanım Alanı	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 yoklamadan sonra son crawl durumu/verileri
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ı	passages içeren results[]
agent	Çok kaynaklı araştırma, bilinmeyen veya çok sayıda site	JSON (yapılandırılmış veri)
monitor	Yinelenen 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

Format Seçim Kılavuzu

scrape kullanırken doğru formatı seçin:

• JSON formatı (çoğu durum için önerilir): Bir sayfadan belirli verilere ihtiyaç duyduğunuzda kullanın. Çıkarmak istediğiniz verilere göre bir şema tanımlayın. Bu, yanıtları küçük tutar ve bağlam penceresi taşmasını önler.
• Markdown formatı (idareli kullanın): Yalnızca bir makalenin tamamını özetlemek veya sayfa yapısını analiz etmek gibi gerçekten tam sayfa içeriğine ihtiyaç duyduğunuzda kullanın.

Mevcut Araçlar

1. Scrape Aracı (firecrawl_scrape)

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

Şunlar için en iyisi:

• Bilginin hangi sayfada olduğunu tam olarak bildiğinizde, tek sayfalık içerik çıkarma.

Şunlar için önerilmez:

• 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. Toplu bir API işlemine özel olarak ihtiyacınız varsa, MCP dışında Firecrawl API toplu uç noktasını kullanın.
• Varsayılan olarak markdown formatını kullanmak (yalnızca ihtiyacınız olanı çıkarmak için JSON formatını kullanın).

Doğru formatı seçme:

• JSON formatı (tercih edilen): Çoğu kullanım durumu için, yalnızca ihtiyaç duyulan belirli verileri çıkarmak üzere bir şemayla JSON formatını kullanın. Bu, yanıtları odaklanmış tutar ve bağlam penceresi taşmasını önler.
• Markdown formatı: 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 formatı - 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 formatı - tam içerik gerektiğinde):

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

Kullanım Örneği (marka formatı - marka kimliğini çıkar):

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

Marka formatı: Tasarım analizi veya stil kopyalama için kapsamlı marka kimliğini (renkler, yazı tipleri, tipografi, boşluk, 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:

• Belirtildiği gibi JSON yapılandırılmış veri, markdown, marka profili veya diğer formatlar.

2. Map Aracı (firecrawl_map)

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

Şunlar için en iyisi:

• Neyi kazıyacağınıza karar vermeden önce bir web sitesindeki URL'leri keşfetme
• Bir web sitesinin belirli bölümlerini bulma

Şunlar için önerilmez:

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

Yaygın hatalar:

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

İstem Ö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. Search 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 iyisi:

• Bilginin hangi web sitesinde olduğunu bilmediğinizde, birden fazla web sitesinde belirli bilgileri bulma.
• Bir sorgu için en alakalı içeriğe ihtiyaç duyduğunuzda

Şunlar için önerilmez:

• Hangi web sitesini kazıyacağınızı zaten bildiğinizde (scrape kullanın)
• Tek bir web sitesinin kapsamlı kapsamına ihtiyaç duyduğunuzda (map veya crawl kullanın)

Yaygın 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 bunu atlayı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ırmayla ilgili web sitelerine göre filtreler.

Döndürür:

• Arama sonuçları dizisi (isteğe bağlı kazınmış içerikle birlikte) ve bir id alanı. Sonuçları kullandıktan sonra bu id değerini firecrawl_search_feedback öğesine iletin; 1 kredi iadesi alın (arama 2 krediye mal olur) ve arama kalitesini artırın.

İstem Örneği:

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

3b. Search 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ç kaydedilir 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 giriş — bunlar ekipler arasında toplanır ve sırada neyi dizine ekleyeceğimizi söyler.

Günlük iade sınırı (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 de kaydeder ancak artık 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)

/v2/feedback aracılığıyla tamamlanan bir v2 uç noktası işi için 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 öğesini 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 scrape/parse çı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 iyisi:

• Kapsamlı kapsama ihtiyaç duyduğunuzda, birden fazla ilgili sayfadan içerik çıkarma.

Şunlar için önerilmez:

• Tek bir sayfadan içerik çıkarma (scrape kullanın)
• Token sınırları bir endişe olduğunda (daha sıkı kontrol için map + scrape kullanın)
• Hızlı sonuçlara ihtiyaç duyduğunuzda (crawl yavaş olabilir)

Uyarı: Crawl yanıtları çok büyük olabilir ve token sınırlarını 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.

Yaygın 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)

İstem Ö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ı son 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 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. Parse 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 iyisi: 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 parse'i bir kez çağırın) veya ekran görüntüleri ve tıklamalar gibi yalnızca tarayıcıya özgü eylemler.

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 öğesini filePath ile çağırın, dosyayı yerel olarak yükleyin, ardından döndürülen uploadRef ile firecrawl_parse öğesini 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 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, her URL için firecrawl_scrape öğesini formats: ["json"] ile bir kez ç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"]
      }
    }
  }
}

URL'ler bilinmediğinde veya veriler birden fazla siteye yayıldığında, çok kaynaklı araştırma için firecrawl_agent kullanın.

8. Agent Aracı (firecrawl_agent)

URL'leri bilmediğinizde veya yanıt birden fazla siteye yayıldığında yapılandırılmış veri döndüren otonom web araştırma aracısı. İhtiyacınız olan alanları tanımlayın, isteğe bağlı olarak bir JSON şeması ve başlangıç URL'leri iletin; aracı arar, gezinir, sayfaları okur ve kaynaklar arasında derlenmiş JSON döndürür. Bir varlık ve alanları, listeler ve veri kümeleri ve verilere ulaşmak için gezinme gerektiren sayfalar için kullanın. Bilinen tek bir URL için bunun yerine JSON formatıyla firecrawl_scrape kullanın.

Nasıl çalışır:

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

Eşzamansız iş akışı:

1. İsteminiz/şemanızla firecrawl_agent öğesini ç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 için dakikalar sürebilir)
3. İlerlemeyi kontrol etmek için iş kimliğiyle firecrawl_agent_status öğesini yoklayın
4. Durum "completed" olduğunda, yanıt çıkarılan verileri içerir

Şunlar için en iyisi:

• 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 sayfalık 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ı (gerekli, 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ı

İstem Örneği:

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

Kullanım Örneği (aracı 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ğiyle firecrawl_agent_status kullanarak 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. Agent Durumunu Kontrol Et (firecrawl_agent_status)

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

Yoklama deseni: Agent 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: Agent hâlâ araştırıyor - daha sonra tekrar kontrol edin
• completed: Araştırma tamamlandı - 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. En uygun olduğu durumlar: Kullanımdan kaldırılmış tarayıcı araçlarını geri yüklemeden dinamik sayfalarda tıklama, yazma, gezinme ve durum çıkarma işlemleri.

Kullanım seçenekleri:

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

Kullanım Örneği:

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

Dönüş: Etkileşim sonucu ve URL modu için, takip veya temizlik amacıyla türetilen scrapeId değeri.

11. Etkileşimi Durdurma 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: Biyomedikal, yaşam bilimleri ve klinik literatürdeki (PubMed, bioRxiv, medRxiv) makale özetleri ve tam metinlerin yanı sıra arXiv ve diğer bilimsel kaynaklar.

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

En uygun olduğu durumlar: Ajanı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 ortaya çıkarırlar.

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

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

En uygun olduğu durumlar:

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

Önerilen oluşturma deseni:

page veya pages artı goal kullanın. MCP sunucusu, 30 dakikalık bir zamanlamayla izleyici isteğini oluşturur ve API, anlamlı değişiklik değerlendirmesini otomatik olarak etkinleştirir.

goal ayarlandığında anlamlı değişiklik değerlendirmesi otomatik olarak çalışır. Sayfa web kancaları, monitor.page olaylarında isMeaningful ve judgment değerlerini açığa çıkarır.

Hedefleri kısa 2-3 cümlelik izleyici talimatları olarak yazın. Bir uyarıyı neyin tetiklemesi gerektiğini söyleyin, 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 çerçevesi gibi genel gürültü zaten değerlendirici tarafından 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."
  }
}

Web kancalı birden çok 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 izleme, özel saklama veya açık judgeEnabled kontrolü gerektiğinde body değerini geçirin.

{
  "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 izleyici araçları:

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

14. Geliştirici Arama Aracı (firecrawl_developer_search)

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

En uygun olduğu durumlar: Bir programlama sorusu — kod davranışı, bir kitaplık 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 ve maksimum 100'dür.
• skills: yalnızca ajan beceri dosyalarını aramak için "only" olarak ayarlayın.

Dönüş: Sıralanmış sonuçlar. Her sonuç bir kimlik, bir 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. Bunun yerine, eşleşen pasajları, skills filtresini veya yanıtta web sonucu olmamasını istediğinizde bu aracı kullanın. Yalnızca arama uç noktası her iki aracı da açığa çıkarır ve aynı seçim orada da geçerlidir.

Günlük Kaydı Sistemi

Sunucu kapsamlı günlük kaydı içerir:

• İşlem durumu ve ilerleme
• Performans ölçümleri
• Hız sınırı izleme
• 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 İşleme

Sunucu sağlam hata işleme 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ığı için MCP.so ve Klavis AI'ye ve entegre ettiği için @gstarwd, @xiangkaiz ve @zihaolin96 adlı kişilere teşekkürler.

Lisans

MIT Lisansı - ayrıntılar için LİSANS dosyasına bakın