Firecrawl MCP

Firecrawl MCP Server

Yapay Zekâ ajanları için bağlam API'si olan Firecrawl'ı MCP uyumlu istemcilere sunan bir Model Context Protocol (MCP) sunucusu: web'de arama yapın, sayfaları kazıyın ve etkileşim kurun; temiz Markdown veya yapılandırılmış veriler alın.

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

Özellikler

• Web'de arama yapın; isteğe bağlı olarak her sonuç için tam sayfa içeriğini alın
• Geliştirici kaynakları (GitHub sorunları, birleştirilmiş pull request'ler, README'ler ve belgeler), ABD hükümet kaynakları ve bilimsel makaleler (PubMed, bioRxiv, medRxiv, arXiv) için dizinlerde arama yapın
• Herhangi bir URL'yi temiz Markdown'a veya yapılandırılmış JSON'a dönüştürün
• PDF'leri ve belgeleri ayrıştırın
• Birçok sayfadaki içeriği almak için bir siteyi tarayın veya URL'lerini keşfetmek için haritasını çıkarın
• Sayfalarla gerçek bir tarayıcıda etkileşim kurun: tıklayın, yazın, formları doldurun ve dinamik sayfalarda gezinin
• Yapılandırılmış veriler döndüren çok kaynaklı araştırmalar için Agent işleri çalıştırın
• Sayfaları izleyin ve içerikleri değiştiğinde bildirim alın
• Mevcut ve geçmiş Firecrawl kredi kullanımını kontrol edin
• Otomatik yeniden denemeler ve hız sınırlama
• Bulut ve kendi sunucunuzda barındırma desteği
• SSE desteği

MCP.so oyun alanındaki MCP Sunucumuzu veya Klavis AI üzerinde deneyin.

Bu Sunucuyu Ne Zaman Kullanmalı?

• Bilinen bir URL'niz varsa ve içeriğini Markdown olarak veya sağladığınız bir şemaya uyan JSON olarak almak istiyorsanız firecrawl_scrape kullanın.
• Bir sitenin içeriğini almadan URL'lerini keşfetmeniz gerekiyorsa firecrawl_map kullanın.
• Bir sitedeki birçok sayfanın içeriğine ihtiyacınız varsa firecrawl_crawl kullanın; kapsamı sınırlamak için limit, includePaths/excludePaths veya maxDiscoveryDepth ayarlayın.
• Bir URL yerine sorguyla başlıyor ve sıralanmış web sonuçları istiyorsanız firecrawl_search kullanın. Sonuçlarda alıntılar bulunur; ihtiyacınız olan URL'lerdeki tam sayfaları almak için firecrawl_scrape kullanın. scrapeOptions aynı çağrıda her sonucun sayfasını getirir ve her birini sayfa kazıma olarak ücretlendirir; bu nedenle bunu birkaç sonucun tam metnine ihtiyaç duyduğunuzda kullanın (yalnızca arama yapan uç nokta hiçbir içeriği getirmez).
• Bir sayfayı okuyabilmeniz için tıklama, yazma veya gezinme eylemi gerekiyorsa firecrawl_interact kullanın: yeni bir sayfa için url, daha önce kazıdığınız bir sayfada devam etmek için scrapeId iletin.
• Aynı sayfanın bir kez getirilmesi yerine düzenli aralıklarla farklar ve değişiklik uyarılarıyla kontrol edilmesi gerekiyorsa firecrawl_monitor_* araçlarını kullanın.
• Kalan kredileri veya kredilerin neye harcandığını aya ya da güne göre, isteğe bağlı olarak uç nokta veya API anahtarına göre ayrıntılandırarak kontrol etmek için firecrawl_credit_usage kullanın.
• Kendi yeniden deneme ve sonlandırma mantığınızla birçok adım boyunca açık tutmanız gereken bir tarayıcı oturumuna ihtiyacınız varsa başka bir çözüm düşünün: her firecrawl_interact çağrısı bir prompt veya code turunu tamamlar ve denetimi geri verir. Oturum, çağrılar arasında scrapeId aracılığıyla devam edebilir ve firecrawl_interact_stop ile sona erer; ancak istemci tarafından tek bir çağrı içinde adım adım etkileşimli olarak yönetilemez.

Tam profil varsayılan ayarlarla kaydedildiğinde bu sunucu 29 araç listeler (geri bildirim araçları dâhil, yerel anahtarsız modda çalışmıyorsa). FIRECRAWL_NO_SEARCH_FEEDBACK=1 ve/veya FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 ayarlandığında ilgili geri bildirim araçları kaldırılır ve bu sayı azalır; yerel anahtarsız başlatma da aynı etkiyi yapar. 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ı gerekmez) yalnızca 3 araç (firecrawl_scrape, firecrawl_search, firecrawl_parse) sunar; özel yalnızca arama uç noktası (https://mcp.firecrawl.dev/v2/mcp-search) ise sabit bir 11 araçlık küme sunar (arama, geliştirici, hükümet ve araştırma araması, Alexandria katalog araması ve yürütme, ayrıca kişi ve şirket araması ve zenginleştirme).

Kurulum

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

Uzak barındırılan sunucuya kurulum yapmadan 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ıdır). crawl, map ve agent gibi diğer araçlar yine de anahtar gerektirir.

Kullanıcı kaydolabiliyorsa OAuth'u veya API anahtarını tercih edin. Bunlar tüm araç kümesinin ve daha yüksek sınırların kilidini açar.

Etkileşimli 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 girdisi eklemeyin:

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

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

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

Ardından istemcinin güvenli başlık veya gizli bilgi ayarını şu değerle yapılandırın:

Authorization: Bearer <FIRECRAWL_API_KEY>

API anahtarını asla sunucu URL'sine veya bir ajan sohbetine koymayın. Anahtarı doğrudan istemcide ya da gizli bilgi yöneticisinde yapılandırın. İstemciye özel talimatlar için barındırılan MCP kurulum kılavuzuna ve ajan başlangıç kılavuzuna bakın.

Entegrasyonunuzu adlandırma

HTTP üzerinden bağlanan bir entegrasyon, örneğin X-Firecrawl-Origin: my-agent gibi bir X-Firecrawl-Origin başlığıyla kendini adlandırabilir. Sunucu bunu, normalde bildireceği istemci adı veya User-Agent yerine, istek kaynağı mcp-my-agent@<server version> olarak Firecrawl'a bildirir. Harf, rakam ve tire kullanın: diğer karakterlerden oluşan her dizi tek bir tireye dönüştürülür, baştaki ve sondaki tireler kaldırılır ve ad 48 karakterde kesilir. Araç sonuçları etkilenmez; yalnızca Firecrawl API'sine gönderilen (ve bir gömücünün beforeKeylessRequest değerine aktarılan) kaynak değişir.

Yalnızca arama uç noktası

Sabit kapsamlı bir arama arayüzü şu adreste de barındırılır:

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

Sabit bir on bir araçlık küme sunar: firecrawl_search, firecrawl_developer_search, firecrawl_gov_search, dört firecrawl_research_* aracı, iki Alexandria aracı firecrawl_find_tools ve firecrawl_scrape ile zenginleştirme araçları people_company_search ve people_company_enrich. firecrawl_search sayfa içeriği getirmez.

npx ile çalıştırma

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

Elle Kurulum

npm install -g firecrawl-mcp

Cursor'da çalıştırma

Cursor'ı yapılandırma 🖥️
Not: Cursor 0.45.6+ sürümü gerekir
En güncel yapılandırma talimatları için lütfen MCP sunucularını yapılandırmaya ilişkin resmi Cursor belgelerine bakın: Cursor MCP Sunucusu Yapılandırma Kılavuzu

Firecrawl MCP'yi Cursor v0.48.6 sürümünde yapılandırmak için

1. Cursor Ayarları'nı açın
2. Features > MCP Servers bölümüne gidin
3. "+ Add new global MCP server" 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 sürümünde yapılandırmak için

1. Cursor Ayarları'nı açın
2. Features > MCP Servers bölümüne gidin
3. "+ Add New MCP Server" seçeneğine tıklayın
4. Aşağıdakileri girin:
   • Name: "firecrawl-mcp" (veya tercih ettiğiniz ad)
   • Type: "command"
   • Command: 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 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 kullanır; ancak web'den neye ihtiyacınız olduğunu açıklayarak açıkça da isteyebilirsiniz. Command+L (Mac) ile Composer'ı açın, gönder düğmesinin yanından "Agent" seçeneğini belirleyin 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"
      }
    }
  }
}

Yerel Streamable HTTP Modunda Çalıştırma

Sunucuyu varsayılan stdio aktarımı 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

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

Bu modda sunucu yalnızca herhangi bir bağlantı noktasındaki localhost, 127.0.0.1 veya [::1] adreslerine ve HOST içindeki adrese (bu adres 0.0.0.0 veya :: değilse) yöneltilen isteklere yanıt verir. Host başlığı başka bir ana bilgisayar adı belirten veya Origin başlığı başka bir site belirten istekler 403 alır; CORS başlıkları da * yerine izin verilen bir kaynağı yansıtır. /health adresine gönderilen GET ve HEAD istekleri ana bilgisayar adı ne olursa olsun yanıtlanır; böylece sağlık kontrolleri çalışmaya devam eder. Sunucu, reddettiği her istek için FIRECRAWL_MCP_ALLOWED_HOSTS adını belirten bir satır kaydeder. Bu, ziyaret ettiğiniz web sayfalarının DNS yeniden bağlama veya çapraz kaynak istekleri yoluyla yerel sunucuyu çağırıp FIRECRAWL_API_KEY değerini kullanmasını önler.

Sunucuya ters proxy arkasındaki bir ana bilgisayar adı veya LAN IP'si gibi başka bir ad ya da adres üzerinden erişmek için bunu FIRECRAWL_MCP_ALLOWED_HOSTS içine ekleyin (virgülle ayrılır; bağlantı noktaları dikkate alınmaz). Aynı liste, hangi tarayıcı kaynaklarının sunucuyu çağırabileceğini de belirler. Aynı makinedeki bir ters proxy varsayılan bağlama adresini kullanabilir:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  FIRECRAWL_MCP_ALLOWED_HOSTS=mcp.home.lan npx -y firecrawl-mcp

Diğer makinelerdeki istemcilerin de sunucunun döngüsel olmayan bir adreste dinlemesi gerekir; bu nedenle HOST değerini de ayarlayın. Bağlantı noktasına erişebilen her istemciye sunucunun FIRECRAWL_API_KEY değeri sunulur; bu nedenle bunu yalnızca güvendiğiniz bir ağda yapın:

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY HOST=0.0.0.0 \
  FIRECRAWL_MCP_ALLOWED_HOSTS=192.168.1.20 npx -y firecrawl-mcp

FIRECRAWL_MCP_ALLOWED_HOSTS=* denetimi kapatır ve joker karakterli CORS başlığını geri yükler. Bunu yalnızca sunucunun önündeki bir bileşen ana bilgisayar adlarını ve kaynakları kendisi denetliyorsa yapın.

Docker ile çalıştırma

ghcr.io/firecrawl/firecrawl-mcp-server imajı, npx -y firecrawl-mcp ile aynı sunucuyu çalıştırır. main üzerinden yapılan her derleme latest, v<package version> ve sha-<commit sha> olarak etiketlenir. v<package version> ilgili sürümün en yeni derlemesine işaret eder; bu nedenle sabit bir imaj gerektiğinde sha-<commit sha> (veya bir özet) kullanın.

stdio (varsayılan), sunucuyu komut olarak başlatan MCP istemcileri için:

docker run -i --rm -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY ghcr.io/firecrawl/firecrawl-mcp-server:latest

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "FIRECRAWL_API_KEY", "ghcr.io/firecrawl/firecrawl-mcp-server:latest"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Streamable HTTP, http://localhost:3000/mcp adresinde sunulur:

docker run --rm -p 127.0.0.1:3000:3000 \
  -e HTTP_STREAMABLE_SERVER=true \
  -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  ghcr.io/firecrawl/firecrawl-mcp-server:latest

İmaj HOST=0.0.0.0 ve PORT=3000 değerlerini ayarlar; başka bir adreste dinlemek için PORT değerini (ve -p eşlemesini) geçersiz kılın. Kendi kimlik bilgilerini göndermeyen isteklerde sunucu kapsayıcının FIRECRAWL_API_KEY değerini kullanır; bu nedenle örnek bağlantı noktasını yalnızca 127.0.0.1 üzerinde yayımlar. İstemcilerin kendi anahtarlarını sağlaması gerekmiyorsa bağlantı noktasını daha geniş bir ağa açmayın. Kendi sunucunuzda barındırılan bir Firecrawl API'si kullanmak için FIRECRAWL_API_URL ayarlayın. Kapsayıcı ayrıcalıksız node kullanıcısı olarak çalışır. Sunucu, Host ve Origin başlıklarında yalnızca localhost, 127.0.0.1 ve [::1] değerlerine yanıt verir; bu nedenle -p 127.0.0.1:3000:3000 eşlemesi olduğu gibi çalışır. Başka bir ad üzerinden erişmek için -e FIRECRAWL_MCP_ALLOWED_HOSTS=<host> ayarlayın (Yerel Streamable HTTP modu bölümüne bakın).

VS Code'da çalıştırma

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

Elle 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 bunu çalışma alanınızdaki .vscode/mcp.json adlı bir dosyaya ekleyebilirsiniz. Böylece yapılandırmayı başkalarıyla paylaşabilirsiniz:

{
  "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'si kullanılırken gereklidir (varsayılan)
  • FIRECRAWL_API_URL ile kendi sunucunuzda barındırılan bir örnek kullanılırken isteğe bağlıdır
• FIRECRAWL_API_URL (İsteğe bağlı): Kendi sunucunuzda 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ı gerekir)
• FIRECRAWL_INTEGRATION (İsteğe bağlı): Bu sunucuyu başlatan uygulamalar (ör. bir düzenleyici uzantısı) için entegrasyon etiketi
  • Kazıma, toplu kazıma, tarama, haritalama, arama, çıkarma, agent, ayrıştırma, etkileşim ve geri bildirim isteklerinin integration alanı olarak gönderilir
  • _ ile başlayan bir değer kullanın; örneğin _zed

Yerel HTTP modu

• FIRECRAWL_MCP_ALLOWED_HOSTS (İsteğe bağlı): Sunucunun HTTP_STREAMABLE_SERVER=true veya SSE_LOCAL=true ile yanıt verdiği, virgülle ayrılmış ek ana bilgisayar adları veya adresleri
  • localhost, 127.0.0.1, [::1] ve joker karakter içermeyen bir HOST her zaman izinlidir; bağlantı noktaları yok sayılır
  • Host veya Origin başlığı başka bir ana bilgisayar adı belirten istekler, GET ve HEAD isteklerinin /health adresine gönderilmesi dışında, 403 alır
  • * denetimi kapatır; her ana bilgisayara yanıt veren CLOUD_SERVICE=true ile birlikte kullanılmaz

MCP OAuth (Bearer erişim belirteçleri)

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

• HTTP akış aktarımları (CLOUD_SERVICE=true, HTTP_STREAMABLE_SERVER=true veya SSE_LOCAL=true): İstemciler MCP isteklerinde Authorization: Bearer <fco_access_token> göndermelidir. Her ikisi de mevcutsa OAuth bearer belirteci, x-firecrawl-api-key / x-api-key değerlerine öncelik tanır.
• stdio: Statik erişim belirteci için FIRECRAWL_OAUTH_TOKEN kullanın veya API anahtarı için FIRECRAWL_API_KEY kullanmaya devam edin.

Yalnızca erişim belirteçlerini (fco_…) kullanın. Yenileme belirteçleri (fcr_…), token uç noktasında değiştirilmelidir; scrape/search API'sine gönderilmemelidir.

CLOUD_SERVICE=true

CLOUD_SERVICE=true, araçları PORT üzerinde akış destekli HTTP ile sunar (varsayılan 3000, 0.0.0.0 adresine bağlanır) ve daha katı varsayılanlara sahiptir: her istekte bir kimlik bilgisi (API anahtarı veya OAuth erişim belirteci) bulunmalıdır, scrape salt okunurdur (aşağıdaki scrape aracına bakın) ve firecrawl_parse yalnızca yüklemeleri kabul eder.

FASTMCP_ENDPOINT araç yüzeyini seçer: tam araç kümesi için /v2/mcp (varsayılan), hesap yüzeyi için /v2/mcp-oauth veya yalnızca arama araçları için /v2/mcp-search (bu seçenek ayrıca FIRECRAWL_MCP_SEARCH_OAUTH_ONLY=true gerektirir). Tam yüzey kullanıldığında, yalnızca arama araçlarını içeren bir örnek de 3001 bağlantı noktasında başlatılır; kapatmak için FIRECRAWL_MCP_SEARCH_ENABLED=false ayarlayın.

Yapılandırma Örnekleri

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

export FIRECRAWL_API_KEY=your-api-key

Kendi barındırdığınız ö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ç Seçme

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ı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 sorunuz varsa (bir kitaplık, API sözleşmesi, hata iletisi veya bilinen bir hata): developer search kullanın
• Hukuki veya düzenleyici bir sorunuz varsa (bir yasa, yönetmelik, kanun, mahkeme görüşü veya başka bir ABD hükümeti yayını): Firecrawl Government Index kullanın
• Bilimsel makalelere ihtiyacınız varsa (biyomedikal, yaşam bilimleri, klinik veya arXiv literatürü): Makale özetlerini ve tam metinlerini arayan research tools kullanın. search ile categories: ["research"] farklı bir şeydir: sıradan web sonuçlarına uygulanan bir web sitesi filtresidir.
• Yapılandırılmış veri döndüren, URL'lerini bilmediğiniz veya yanıtı birden fazla siteyi kapsayan çok kaynaklı araştırmaya ihtiyacınız varsa (bir varlık ve alanları, bir liste, bir veri kümesi): agent kullanın
• Bir sitenin tamamını veya bir bölümünü analiz etmek istiyorsanız: crawl kullanın (sınırlara dikkat edin!)
• Etkileşimli tarayıcı otomasyonuna (tıklama, yazma, gezinme) ihtiyacınız varsa: Yeni bir sayfa için URL ile interact kullanın veya sayfayı zaten scrape ettiyseniz ya da scrape denetimini daha sıkı tutmanız gerekiyorsa scrape + interact kullanın
• Kataloglanmış bir sağlayıcıdan (Alexandria) veri almanız gerekiyorsa: sources: ["alexandria"] ile arama yapın, seçilen sözleşmeyi find_tools ile inceleyin ve scrape alexandria ile çalıştırın

Hızlı Başvuru Tablosu

Araç	En uygun kullanım	Döndürülenler
scrape	Tek sayfa içeriği	JSON (tercih edilir) veya markdown
interact	Bir URL veya scrape edilmiş sayfayla etkileşim	URL modunda yürütme sonucu + scrapeId
map	Bir sitedeki URL'leri keşfetme	URL[]
crawl	Çok sayfalı çıkarım (sınırlı)	Dahili yoklamanın ardından son tarama durumu/verisi
parse	Dosyalar ve barındırılan yükleme referansları	markdown, JSON veya belge çıktısı
search	Web'de bilgi arama	results[]
find_tools	Alexandria kataloğunda gezinme ve URL arama	sağlayıcılar, araç sözleşmeleri ve nextTool gezinmesi
developer	Geliştirici kaynaklarında programlama soruları	pasajları içeren results[]
gov	ABD birincil hukuk ve düzenleyici materyalleri	parçacıkları içeren results[]
agent	Çok kaynaklı araştırma, bilinmeyen veya çok sayıda site	JSON (yapılandırılmış veri)
monitor	Yinelenen sayfa denetimleri	monitor/check meta verileri ve farklar
research	Makale araştırması (depolar için developer)	araştırma sonuçları

Biçim Seçme Kılavuzu

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

• JSON biçimi (çoğu durumda önerilir): Bir sayfadan belirli veriler gerektiğinde kullanın. Çıkarmak istediğiniz verilere göre bir şema tanımlayın. Bu, yanıtları küçük tutar ve bağlam penceresinin taşmasını önler.
• Markdown biçimi (seyrek kullanın): Yalnızca özetleme için bir makalenin tamamını okumak veya sayfa yapısını analiz etmek gibi, sayfanın tüm içeriğine gerçekten ihtiyaç duyduğunuzda kullanın.

Kullanılabilir Araçlar

1. Scrape Aracı (firecrawl_scrape)

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

En uygun kullanım:

• Bilginin hangi sayfada bulunduğunu tam olarak bildiğinizde tek sayfadan içerik çıkarma.

Önerilmez:

• Birden fazla sayfadan içerik çıkarırken (bilinen URL'ler için tekrarlanan scrape çağrıları yapın, URL'leri önce keşfetmek için map + scrape kullanın veya sayfanın tüm içeriği için crawl kullanın)
• Bilginin hangi sayfada bulunduğundan emin olmadığınızda (search kullanın)

Sık yapılan hatalar:

• Tek bir scrape çağrısına URL listesi vermek. MCP'de her URL için bir kez 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.
• Varsayılan olarak markdown biçimini 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 edilir): Çoğu kullanımda yalnızca gereken belirli verileri çıkarmak için şemalı JSON biçimini kullanın. Bu, yanıtları odaklı tutar ve bağlam penceresinin taşmasını önler.
• Markdown biçimi: Yalnızca görev sayfanın tüm içeriğini gerçekten gerektiriyorsa kullanın (ör. bir makalenin tamamını özetleme veya sayfa yapısını analiz etme).

İstem Örneği:

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

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

{
  "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 - tüm içerik gerektiğinde):

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

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

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

Marka kimliği biçimi: Tasarım analizi veya stilin yeniden oluşturulması için kapsamlı marka kimliğini (renkler, yazı tipleri, tipografi, boşluklar, logo, kullanıcı arayüzü bileşenleri) çıkarır. Gizlilik: Kişisel olarak tanımlanabilir bilgilerin sansürlendiği içerik döndürmek için redactPII: true ayarlayın. CLOUD_SERVICE=true ile: scrape salt okunurdur. Tarayıcı actions almaz ve sağlayıcı koşullarını kabul edemez. Adlandırılmış bir profile, değişiklikleri kaydetmeden kayıtlı tarayıcı durumunu yükler; tam uç noktanın firecrawl_search özelliği de scrapeOptions.profile için aynı şekilde davranır. Tarayıcı durumunu bir profile kaydetmek için sayfayı firecrawl_interact ile açın (aşağıya bakın). Bir kuruluş yöneticisi koşulları kontrol panelinde kabul eder.

Döndürülenler:

• Belirtildiği şekilde JSON yapılandırılmış verileri, markdown, marka profili veya diğer biçimler.

2. Map Aracı (firecrawl_map)

Sitedeki dizine eklenmiş tüm URL'leri keşfetmek için bir web sitesini haritalandırın.

En uygun kullanım:

• Neyi scrape edeceğinize karar vermeden önce bir web sitesindeki URL'leri keşfetme
• Bir web sitesinin belirli bölümlerini bulma

Önerilmez:

• İhtiyacınız olan belirli URL'yi zaten biliyorsanız (scrape kullanın)
• Sayfaların içeriğine ihtiyacınız varsa (haritalandırdıktan sonra scrape kullanın)

Sık yapılan hatalar:

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

İstem Örneği:

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

Kullanım Örneği:

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

Döndürülenler:

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

En uygun kullanım:

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

Önerilmez:

• Scrape edilecek web sitesini zaten biliyorsanız (scrape kullanın)
• Tek bir web sitesinin kapsamlı içeriğine ihtiyacınız varsa (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"
  }
}

Aynı çağrıda birkaç sonucun tam metnini almak için "scrapeOptions": { "formats": ["markdown"], "onlyMainContent": true } ekleyin. Alınan her sonuç scrape olarak ücretlendirilir; bu nedenle çoğu soru için alıntıları kullanın ve yalnızca ihtiyacınız olan URL'leri firecrawl_scrape.

Sorguyla ilgili öne çıkan bölümleri istemek için highlights değerini true olarak ayarlayın veya özgün arama parçacıklarını korumak için false kullanın. API'nin varsayılan davranışını kullanmak için bu ayarı belirtmeyin.

data.tools içinde anlamsal araç keşfi için "sources": ["alexandria"] ekleyin; bunu isteğe bağlı olarak web/haber/görsel aramasıyla birleştirebilirsiniz. Sorgu gereklidir. Bağlamsal arama ve aşamalı açıklama için firecrawl_find_tools kullanın; bkz. Alexandria Tools.

Bilimsel makaleler için Research Tools bölümüne bakın: bu araçlar makale özetlerini ve tam metinlerini ararken, buradaki categories: ["research"] sıradan web sonuçlarını araştırmayla ilişkili web sitelerine göre filtreler.

Döndürülenler:

• Kaynağa göre gruplandırılmış arama sonuçları (data.web, data.images, data.news), isteğe bağlı olarak scrape edilmiş içerik ve bir id alanı. Her sonuç bir source ve 1'den başlayan bir position taşır; numaralandırma kendi grubu içinde 1'den başlar. Dizi öğelerini saymak yerine bu ikiliyi doğrudan firecrawl_search_feedback aracının valuableResults alanına kopyalayın. Sonuçları kullandıktan sonra 1 krediyi iade etmek (search 2 krediye mal olur) ve arama kalitesini artırmak için bu id değerini firecrawl_search_feedback aracına iletin.

İstem Örneği:

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

3b. Search Feedback Aracı (firecrawl_search_feedback)

Önceki bir firecrawl_search sonucuyla ilgili yapılandırılmış geri bildirim gönderir. Her arama kimliği için gönderilen ilk geri bildirim 1 krediyi iade eder ve Firecrawl'ın arama kalitesini artırır. Arama kimliği başına yinelenen işlemler etkisizdir.

Gerçekten kullandığınız (veya yardımcı olmayan) her aramadan sonra bunu çağırın. missingContent içeren kötü/kısmi geri bildirim de 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, dolayısıyla aracı çağrılamaz. Ekip yöneticileri geri bildirimi sunucu tarafında da devre dışı bırakabilir; bu durumda araç kaydedilir ancak her zaman feedbackErrorCode: "TEAM_OPTED_OUT" döndürür. En önemli alan: missingContent. Bu, ajanın bulmayı beklediği ancak bulamadığı belirli içerik parçalarının bir dizisidir. Eksik her konu için bir girdi bulunur; bunlar ekipler genelinde bir araya getirilir ve sırada neyi dizine eklememiz gerektiğini gösterir. Yararlı sonuçlar elde etmek için her sonuca eklenmiş source/position çiftiyle birlikte valuableResults kullanın — sonuçlar gruplandırılır ve her grup bağımsız olarak 1'den başlayarak numaralandırılır; bu nedenle ikisi de gereklidir. Yararlı olan tüm sonuçları listeleyin (listelenmeyen sonuçlar yararlı değilmiş gibi değerlendirilir) ve valuableSources alanını döndürülen sonuçlar arasında bulunmayan yararlı URL'ler için ayırın.

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 bildirim kaydetmeye devam eder ancak artık kredi iadesi yapılmaz. Yanıt dailyCapReached: true değerini ayarlar. Bu işareti gördüklerinde ajanlar, UTC gününün geri kalanında 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",
    "valuableResults": [
      { "source": "web", "position": 1 },
      { "source": "web", "position": 3 },
      { "source": "news", "position": 2, "reason": "Broke the pricing change." }
    ],
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/pricing",
        "reason": "Not in the results; found via a result's pricing link. Answered the question."
      }
    ],
    "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ülenler:

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

3c. Genel Geri Bildirim Aracı (firecrawl_feedback)

Tamamlanmış bir v2 uç nokta işi için /v2/feedback üzerinden yapılandırılmış geri bildirim gönderir. scrape, parse, map veya search işleriyle ilgili uç nokta düzeyinde geri bildirim için bunu kullanın. Özellikle arama sonucu kalitesiyle ilgili geri bildirim için aramaya özgü yönergeler içerdiğinden firecrawl_search_feedback aracını tercih edin.

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

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 ve bu nedenle ajanlar aracı ç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ülenler:

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

4. Tarama Aracı (firecrawl_crawl)

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

En uygun kullanım:

• Kapsamlı içerik gerektiğinde birbiriyle ilişkili birden fazla sayfadan içerik çıkarmak.

Önerilmez:

• Tek bir sayfadan içerik çıkarmak için (scrape kullanın)
• Belirteç sınırlarının sorun olduğu durumlarda (daha sıkı denetim için map + scrape kullanın)
• Hızlı sonuç gerektiğinde (tarama yavaş olabilir)

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

Yaygın hatalar:

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

İstem Örneği:

"example.com/blog adresindeki ilk iki düzeydeki tüm blog gönderilerini 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ülenler:

• id, status, completed, total, creditsUsed, expiresAt, next ve data dahil olmak üzere, dahili durum sorgulaması sonrasında son tarama durumu ve verileri. İşi daha sonra yeniden kontrol etmeniz gerekirse döndürülen id değerini firecrawl_check_crawl_status ile kullanın.

5. Tarama Durumunu Kontrol Etme (firecrawl_check_crawl_status)

Mevcut bir tarama işinin durumunu ve sonuçlarını kimliğine göre kontrol edin.

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

Döndürülenler:

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

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

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

En uygun kullanım: 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 uç nokta iki adımlı bir yükleme akışı kullanır; yerel dosyaların doğrudan okunması için kendi barındırdığınız bir FIRECRAWL_API_URL gerekir.

Önerilmez: Uzak URL'ler için (scrape kullanın), tek çağrıda birden fazla dosya için (her dosya için parse aracını bir kez çağırın) veya ekran görüntüsü alma ve tıklama gibi yalnızca tarayıcıda yapılabilen işlemler için.

Barındırılan uç nokta: Dosya sisteminizi okuyamaz. Kısa süreli bir yükleme komutu ve nextToolCall almak için filePath ile firecrawl_parse çağrısını yapın, dosyayı yerel olarak yükleyin, ardından döndürülen uploadRef ile firecrawl_parse çağrısını yeniden yapın. Yükleme adımı Firecrawl kimlik doğrulaması veya anahtarsız katman gerektirir. Yerel npx firecrawl-mcp modunda, doğrudan dosya ayrıştırma şu anda kendi barındırdığınız bir Firecrawl API'sine işaret eden FIRECRAWL_API_URL gerektirir; yalnızca bulut API anahtarı kullanan standart bir yerel sunucu bu araç üzerinden dosyaları okuyup 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ülenler: Ayrıştırılmış belge içeriği veya nextToolCall içeren barındırılan yükleme yönergeleri.

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

Bilinen bir sayfadan yapılandırılmış veri almak için her URL için formats: ["json"] ile birlikte firecrawl_scrape aracını 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 bilinmiyorsa veya veriler birden fazla siteye yayılıyorsa, çok kaynaklı araştırma için firecrawl_agent kullanın.

8. Ajan 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 ajanı. İhtiyacınız olan alanları açıklayın, isteğe bağlı olarak bir JSON şeması ve başlangıç URL'leri sağlayın; ajan arama yapar, sayfalarda gezinir, sayfaları okur ve kaynaklar genelinde derlediği JSON'u döndürür. Bir varlık ve ona ait alanlar, listeler ve veri kümeleri için ve verilere ulaşmak üzere gezinme gerektiren sayfalar için kullanın. Bilinen tek bir URL için bunun yerine JSON biçimiyle firecrawl_scrape kullanın.

Nasıl çalışır:

Ajan web'de arama yapar, bağlantıları izler, sayfaları okur ve verileri otonom olarak toplar. Bu işlem eşzamansızdır — hemen bir iş kimliği döndürür; tamamlanma durumunu kontrol etmek ve sonuçları almak için firecrawl_agent_status aracını sorgularsınız.

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

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

En uygun kullanım:

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

Önerilmez:

• URL'sini bildiğiniz tek bir sayfayı basitçe taramak için (daha hızlı ve daha ucuz olan JSON biçimli scrape kullanın)

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

• prompt: İstediğiniz verilerin doğal dilde açıklaması (gerekli, en fazla 10.000 karakter)
• urls: Ajanı belirli sayfalara yönlendirmek için isteğe bağlı URL dizisi
• schema: Yapılandırılmış çıktı için isteğe bağlı JSON şeması
• effort: İsteğe bağlı. Ajan görevi için "low", "medium" veya "high" akıl yürütme bütçesi.
• maxCredits: İsteğe bağlı pozitif tam sayı. Bu çalıştırmanın kredi harcama sınırı. Belirtilmediğinde API varsayılan olarak 2,500 kullanır ve ücretsiz bir isteği 2,500 ile sınırlar.
• strictConstrainToURLs: İsteğe bağlı boole değeri. true ise ajan yalnızca urls içindeki URL'leri ziyaret eder.
• threadId: İsteğe bağlı. Mevcut bir ileti dizisini sürdürür: önceki bir firecrawl_agent veya firecrawl_agent_status sonucundan alınan threadId. Yeni bir ileti dizisi başlatmak için belirtmeyin. Takip çağrısında belirtilmeyen mode, urls, schema ve exchange ayarları önceki turdan devralınır.
• mode: İsteğe bağlı. "extract" (varsayılan), her turda yapılandırılmış sonucun tamamını döndürür. "chat", yeni veri istemeyen bir takip çağrısının yeniden çalıştırma yerine message içinde kısa bir yanıt döndürmesini sağlar; exchange.requireApproval bunu gerektirir.
• exchange: İsteğe bağlı. Bu tur için Alexandria sağlayıcı ayarları; olduğu gibi POST /v2/agent öğesine iletilir:
  • enabled, toolkits (en fazla 5 sağlayıcı kısa adı), maxCalls (1 ile 30 arası), requireApproval (ücretli çağrılar turu bir pendingApproval ile bitirir; takip çağrısı olsa bile aynı çağrıda mode: "chat" gerekir)
  • onTermsRequired: Ajanın kullanacağı bir Alexandria sağlayıcısı, ekibinizin kabul etmediği veri koşullarını gerektirdiğinde ne yapılacağı. Kısıtlı sağlayıcılar hiçbir modda çağrılmaz. Takip çağrısında belirtilmezse önceki turun değeri korunur.
    • "skip" (varsayılan): Yalnızca kabul edilmiş sağlayıcılarla yanıt ver. Durum sonucundaki exchange.skippedProviders, yardımcı olabilecek ancak kısıtlı olan sağlayıcıları listeler.
    • "ask": Aynı davranışa ek olarak, onay kimliğini ve sağlayıcı gereksinimlerini içeren koşullar için bir pendingApproval ve exchange.requiresAction. Koşulları terms/show ile okuyun; kuruluş yöneticisi bunları Firecrawl panosunda kabul eder.
  • approve: { approvalId, callIds?, always? }, önceki turun sona erdiği pendingApproval sorusuna evet yanıtı verir. callIds ve always yalnızca ücretli çağrı onayları için geçerlidir.
  • decline: { approvalId }, hayır yanıtı verir. Koşul teklifini reddetmek, bu sağlayıcıları ileti dizisinin geri kalanında devre dışı bırakır.
  • approve ve decline için threadId gerekir ve bunlardan yalnızca biri gönderilebilir.

Sağlayıcı koşulları (sorma modu): Otomatik kabul modu yoktur. Bir tur koşul teklifiyle sona erdiğinde, durum sonucu pendingApproval (kind: "terms") ve approvalId ile sağlayıcı gereksinimlerini içeren exchange.requiresAction değerini taşır. Bu API yükündeki herhangi bir terms/accept tanımlayıcısına MCP üzerinden erişilemez. Sağlayıcıyı kullanmak için:

1. Koşulları kullanıcıya gösterin (alexandria ile birlikte terms/show ile firecrawl_scrape arasındakileri).
2. Kuruluş yöneticisinden koşulları sağlayıcının URL'sinde veya veri kaynakları ayarlarında kabul etmesini isteyin. Veri isteği, onay anlamına gelmez.
3. Yöneticinin panoda kabul ettiğini doğrulamasını bekleyin.
4. Aynı ileti dizisini sürdürün: aynı threadId ve exchange.approve: { "approvalId": "..." } ile firecrawl_agent çağrısını yapın. Bu, araştırmayı sürdürür; koşulları kabul etmez.

Kullanıcı hayır derse bunun yerine aynı threadId ve exchange.decline: { "approvalId": "..." } ile firecrawl_agent çağrısını yapın.

İstem Örneği:

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

Kullanım Örneği (ajanı başlatma, ardından sonuçları sorgulama):

{
  "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 sorgulayın.

Kullanım Örneği (URL'lerle — ajan 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"
  }
}

Kullanım Örneği (aynı ileti dizisinde takip çağrısı):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Only keep the startups based in Europe",
    "threadId": "0199a1b2-0000-7000-8000-000000000031"
  }
}

Kullanım Örneği (yönetici panoda kabulü onayladıktan sonra ileti dizisini sürdürme):

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "The admin confirmed acceptance of the Apollo terms in the dashboard. Continue.",
    "threadId": "0199a1b2-0000-7000-8000-000000000031",
    "exchange": { "approve": { "approvalId": "0199a1b2-0000-7000-8000-000000000033" } }
  }
}

Döndürülenler:

• Durum kontrolü için iş kimliği ve ayrıca threadId ile threadTurn. Sonuçları sorgulamak için firecrawl_agent_status kullanın.

9. Ajan Durumunu Kontrol Etme (firecrawl_agent_status)

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

Sorgulama düzeni: Ajan araştırması, karmaşık sorgularda birkaç dakika sürebilir. Durum "completed" veya "failed" olana kadar bu uç noktayı düzenli aralıklarla (ör. her 10-30 saniyede bir) sorgulayın.

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

Olası durumlar:

• processing: Ajan araştırmaya devam ediyor — daha sonra yeniden 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 kullanım: Kullanımdan kaldırılmış tarayıcı araçlarını yeniden etkinleştirmeden dinamik sayfalarda tıklama, yazma, gezinme ve durum çıkarma.

Kullanım seçenekleri:

• Tek bir MCP çağrısında sayfayı tarayıp açarak etkileşim kurmak için url iletin.
• Daha önce taranmış bir sayfayla etkileşimi sürdürmek için scrapeId iletin.
• Tarayıcı durumunu (çerezler, localStorage) adlandırılmış bir profile kaydetmek için scrapeOptions: { "profile": { "name": "my-profile", "saveChanges": true } } ile birlikte url iletin. Durum, firecrawl_interact_stop oturumu sonlandırdığında kaydedilir.
• url veya scrapeId değerlerinden tam olarak birini ve 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ülenler: Etkileşim sonucu ve URL modunda, takip işlemi veya temizleme için türetilen scrapeId.

11. Etkileşimi Durdurma Aracı (firecrawl_interact_stop)

Etkileşim tamamlandığında, taranmış bir sayfaya ait 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ıyla makaleleri arayın ve inceleyin. GitHub depoları, sorunlar ve pull request'ler için firecrawl_developer_search kullanın.

Kapsam: PubMed, bioRxiv ve medRxiv'deki biyomedikal, yaşam bilimleri ve klinik literatürün makale özetleri ve tam metinlerinin yanı sıra arXiv ve diğer bilimsel kaynaklar.

Kullanılabilir araştırma araçları:

• firecrawl_research_search_papers: İsteğe bağlı yazar, kategori ve tarih filtreleriyle doğal dil sorgusu kullanarak makale üst verilerini ve özetlerini arar.
• firecrawl_research_inspect_paper: Tek bir makale kimliği (arXiv, PMC, PMID veya DOI) için standart üst verileri getirir.
• firecrawl_research_related_papers: Atıf grafiği üzerinden bir veya daha fazla referans makaleden ilerler.
• firecrawl_research_read_paper: Belirli bir makaleden tam metin bölümlerini okur.

En uygun kullanım: Aracının genel web araması yerine odaklı bir araştırma yüzeyine ihtiyaç duyduğu literatür taraması, makale bulma ve depo keşfi iş akışları.

firecrawl_search ile categories: ["research"] farklı bir yüzey sunar: sıradan web sonuçlarını araştırmayla ilişkili web sitelerine göre filtreler ve makale kayıtları yerine sayfa parçacıkları döndürür. Soru doğrudan literatürle ilgili olduğunda bu araçları kullanın ve aynı soruyu birkaç farklı biçimde ifade ederek iletin; çünkü bu araçlar tek bir sorgudan farklı makaleler bulabilir.

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

Düzenli sayfa izleyicileri oluşturun ve yönetin. İzleyiciler zamanlanmış taramalar veya gezinmeler yürütür, her sonucu saklanan son anlık görüntüyle karşılaştırır ve webhook ya da e-posta yoluyla bildirim gönderebilir.

En uygun kullanım:

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

Önerilen oluşturma kalıbı:

page veya pages ile birlikte goal kullanın. MCP sunucusu izleyici isteğini 30 dakikalık bir zamanlamayla 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 webhook'ları, monitor.page olaylarında isMeaningful ve judgment alanlarını sunar.

Hedefleri, 2-3 cümlelik kısa izleme talimatları olarak yazın. Uyarıyı neyin tetiklemesi gerektiğini belirtin, kullanıcının verdiği kapsamı koruyun ve yalnızca istekten açıkça anlaşılan amaca özgü hariç tutmaları ekleyin. Boşluk, yalnızca biçimlendirme değişiklikleri, istek kimlikleri, izleme parametreleri, genel üst veriler ve ilgisiz sayfa öğeleri gibi genel gürültüler değerlendirme tarafından zaten ele alınır; bu nedenle bunları her hedefte tekrarlamayın. Kullanıcı belirsiz konuşuyorsa hedefi geniş tutun; geniş kapsamlı izleme veya "herhangi bir değişiklik" istiyorsa bunu koruyun. Kullanıcı bir şeyi önemsemediğini söylüyorsa bunu açıkça belirtin.

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

Webhook kullanan 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 hedeflerine, JSON değişiklik takibine, özel saklama ayarlarına veya açık judgeEnabled denetimine ihtiyaç duyduğunuzda body 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: İzleyicileri 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 başlatır.
• firecrawl_monitor_delete: Bir izleyiciyi siler (yıkıcı işlem; yalnızca kullanıcı kaldırılmasını istediğinde çağırın).
• firecrawl_monitor_checks: İsteğe bağlı olarak duruma göre filtrelenmiş kontrolleri listeler.
• firecrawl_monitor_check: diff, snapshot, judgment.meaningful ve judgment.meaningfulChanges dahil sayfa düzeyindeki sonuçları getirir.

14. Geliştirici Arama Aracı (firecrawl_developer_search)

Kodlama aracıları için oluşturulmuş bir dizinde arama yapar. Dizin; GitHub sorunlarını, birleştirilmiş pull request'leri, depo README dosyalarını ve kod belgelerini kapsar.

En uygun kullanım: Kod davranışı, bir kitaplık veya çerçeve, API sözleşmesi, hata mesajı ya da bilinen bir hata hakkındaki programlama soruları.

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 değer 10, en yüksek değer 100'dür.
• skills: Yalnızca aracı becerisi dosyalarında arama yapmak için "only" olarak ayarlayın.

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

firecrawl_search ile categories: ["developer"], aynı dizinde web sonuçlarının yanında arama yapar. Eşleşen bölümleri, skills filtresini veya yanıtta web sonucu olmamasını istediğinizde bunun yerine bu aracı kullanın. Yalnızca arama yapan uç nokta her iki aracı da sunar ve aynı seçim orada da geçerlidir.

14b. Devlet Dizini Arama Aracı (firecrawl_gov_search)

ABD federal, eyalet ve yerel yönetim kaynaklarındaki birincil hukuk ve düzenleyici materyalleri arar: yasalar, yönetmelikler, kanun derlemeleri, mahkeme kararları ve diğer devlet yayınları.

En uygun kullanım: Geçerli metne veya resmî bir devlet kaynağına ihtiyaç duyan hukuki ya da düzenleyici sorular.

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

{
  "name": "firecrawl_gov_search",
  "arguments": {
    "query": "excessive force claims against police officers",
    "k": 10,
    "courtType": "federal-appellate",
    "cites": "42 U.S.C. § 1983"
  }
}

• query (gerekli): Hukuki veya düzenleyici soru ya da arama ifadesi.
• k: Sıralanmış sonuç sayısı. Varsayılan değer 10, en yüksek değer 100'dür.
• jurisdiction: Yalnızca tek bir yargı bölgesindeki sayfaları tutar: federal için "us" veya iki harfli bir eyalet ya da bölge koduyla birlikte "us-"; örneğin "us-ca" veya "us-dc".
• court: CourtListener mahkeme kimliğine göre yalnızca tek bir mahkeme için etiketlenmiş sayfaları tutar; örneğin "scotus", "ca9" veya "nysd".
• courtType: Yalnızca tek bir mahkeme türündeki sayfaları tutar: federal-supreme, federal-appellate, federal-district, federal-bankruptcy, federal-special, military, state-supreme, state-appellate, state-trial, state-special veya state-attorney-general.
• cites: Basılı bir atıf (örneğin "42 U.S.C. § 1983" veya "5 U.S. 137") ya da bir atıf kimliği (örneğin "us:usc:42:1983") kullanarak yalnızca tek bir yasaya veya davaya atıfta bulunan sayfaları tutar.
• domain: Yalnızca tek bir sitedeki sayfaları tutar; örneğin "irs.gov".

Filtreler isteğe bağlıdır ve birlikte kullanılabilir: bir sonucun ayarlanan tüm filtrelerle eşleşmesi gerekir. Filtreler yalnızca dizinin etiketlediği sayfaları tutar; bu nedenle filtreli bir arama ilgili sayfaları dışarıda bırakabilir ve sonuç bulunmaması, hiçbir sonucun olmadığı anlamına gelmez. Mahkeme etiketleri en kapsamlı biçimde federal mahkemeler ve içtihat koleksiyonları için mevcuttur.

Döndürülenler: Sıralanmış sonuçlar. Her sonuçta bir sıra numarası, başlık, URL ve eşleşen bir alıntı bulunur. Yalnızca arama yapan uç nokta da bu aracı sunar.

firecrawl_search ile categories: ["gov"], aynı kaynaklarda arama yapar ve eşleşmeleri data.web içinde category: "gov" ile döndürür. gov kategorisi bu filtreleri kabul etmez ve diğer kategorilerle birleştirilemez.

15. Alexandria Araçları

Firecrawl Alexandria, Alexandria erişimi olan bir ekipte Firecrawl API anahtarıyla Firecrawl API üzerinden erişilebilen veri sağlayıcılarının kataloğudur. Anahtarsız oturumlarda (barındırılan veya yerel) Alexandria requires an API key on a team with Alexandria access bulunur; barındırılan anahtarsız oturumlarda Alexandria keşif araçları listelenmez.

Anlamsal keşif (firecrawl_search):

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "podcast conversations about AI agents",
    "sources": ["web", "alexandria"],
    "domainTools": true,
    "limit": 2
  }
}

data.tools, sağlayıcı, yetenek ve açıklama içeren kısa önerileri varsayılan olarak sunar. Üst veriler ve gezinme için toolDetail: "summary", girdiler, yanıt alanları ve örnekleri içeren sözleşmeler için toolDetail: "full" ayarlayın. domainTools: true, aynı dizide sorgu ifadeleri ve sonuç URL'leri için bağlamsal eşleşmeler ekler. Keşif kullanılamıyorsa warning değerini kontrol edin. Arama bir sorgu gerektirir ve katalogda gezinme filtrelerini kabul etmez. Bu keşif hem tam hem de yalnızca arama yapan MCP yüzeylerinde çalışır.

Aşamalı açıklama (firecrawl_find_tools):

{
  "name": "firecrawl_find_tools",
  "arguments": {
    "providers": ["particle"],
    "capabilities": ["podcasts/episodes/search"],
    "expand": ["options", "response", "examples"],
    "limit": 2
  }
}

Kategorileri görmek için bağımsız değişken olmadan başlayın, ardından kataloğu aşamalı olarak daraltın:

Bağımsız değişkenler	Sonuç
{}	Kategoriler ve kısa açıklamalar
{"categories":["podcasts"]}	Bu kategorideki sağlayıcılar
{"categories":["podcasts"],"providers":["particle"]}	Kısa araç adları ve açıklamaları
{"providers":["particle"],"capabilities":["podcasts/episodes/search"]}	Seçilen girdilerin, kısıtlamaların, yanıtın ve örneklerin tamamı

Grup adımları arasında geçiş gerekmez. Açıkça belirtilen level, categories, providers, groups veya tools değerlerini destekler; açıkça belirtilen expand ise sözleşme bölümlerini seçer. expand: [], bir yetenek seçildiğinde bile sonuçları kısa tutar. Geniş kapsamlı tam sözleşmeler için açıkça level: "tools" ve expand: ["options", "response", "examples"] isteyin. URL'ler sayfayı getirmeden bağlamsal keşif sağlar. includeCosts: true ayarlanmadıkça araç sonuçlarında yetenek başına kredi ücretleri gösterilmez; sonraki çağrılarda da nextTool bağımsız değişkenleri bu ayarı korur.

Sonuçlar data.alexandria[0].data içindedir. Bir öğenin nextTool değerini izleyerek, öğenin arguments değeriyle birlikte name aracını çağırın; sayfanın nextTool değeri sayfalandırmayı ilerletir. Mevcut next nesneleri, firecrawl_scrape üzerinden kullanılabilen Alexandria keşif çağrıları olarak kalır. Keşif sıfır krediye mal olur ve sağlayıcı araçlarını hiçbir zaman çalıştırmaz. Yürütmeden önce seçilen tam sözleşmeyi okuyun.

Bu denetimler, eşleşen Alexandria API dağıtımını gerektirir.

Yürütme (firecrawl_scrape ile alexandria): url yerine alexandria iletin (ikisinden tam olarak biri; requestId ve timeout da sağlanabilir). Tek bir çağrı veya en fazla on çağrıdan oluşan bir dizi kabul edilir.

{
  "name": "firecrawl_scrape",
  "arguments": {
    "alexandria": [
      {
        "provider": "fred",
        "capability": "series/observations",
        "options": { "series_id": "CPIAUCSL" }
      }
    ]
  }
}

Döndürülenler: { success, scrape_id, requestId, data: { alexandria: [...], creditsCost } }. Her öğe ya bir sonuçtur (provider, capability, data, records, upstreamStatus) ya da code içeren bir error; sağlayıcı hatası tüm toplu isteğin başarısız olmasına yol açmaz ve data.creditsCost, istek için alınan toplam ücrettir. Alexandria hata gövdeleri (Alexandria erişimi olmaması durumunda 403 ve faturalandırma durumları olan 402/409), code ile birlikte satır içi olarak iletilir.

Yürütme tek bir x-request-id oluşturur ve bunu başarı veya başarısızlık durumunda döndürür. Belirsiz bir sonuçtan sonra yeni bir kimlik oluşturmayın; aynı requestId ile aynı yükü yeniden deneyin. Kullanılabilir krediler API tarafından kontrol edilir.

Ekibin koşullarını kabul etmediği bir Alexandria sağlayıcısı, herhangi bir işlem yürütülmeden önce HTTP 403 ve şu gövdeyle başarısız olur:

{
  "success": false,
  "code": "THIRD_PARTY_DATA_TERMS_REQUIRED",
  "error": "An organization admin must accept the benzinga provider's terms (version 2026-09-12-placeholder) before this request can run. Accept them at https://www.firecrawl.dev/app/alexandria/benzinga",
  "requiresAction": {
    "type": "accept_terms",
    "terms": "benzinga",
    "version": "2026-09-12-placeholder",
    "url": "https://www.firecrawl.dev/app/alexandria/benzinga"
  }
}

Araç sonucu bunu, structuredContent içeren bir hata olarak iletir; bu hata code, status: 403, requestId, değiştirilmeden bırakılan requiresAction nesnesini ve next_actions değerini taşır (human_action_required, ardından retry_same_request). Koşulları kabul etmek yasal bir işlemdir; bu nedenle bir kuruluş yöneticisi bunları MCP üzerinden değil, Firecrawl panosunda kabul eder. Döndürülen nextTool çağrısını kullanarak, sağlayıcı yürütmesinden ayrı olarak alexandria: [{provider: "firecrawl", capability: "terms/show", options: {provider: "<provider>"}}] ile firecrawl_scrape üzerinden sözleşmeyi okuyun ve kullanıcıya sunun. Ardından bir kuruluş yöneticisi sözleşmeyi requiresAction.url adresinde veya https://www.firecrawl.dev/app/settings?tab=data-sources. firecrawl_scrape adresinde kabul eder; diğer tüm terms/* yeteneklerini reddeder, dolayısıyla hesapta hiçbir değişiklik yapmaz. Veri isteği onay anlamına gelmez; otomatik kabul veya sonucu belirsiz yeniden denemeler yapılmaz. Engellenen veri alımı için kredi alınmaz. Yönetici kabulü onayladıktan sonra aynı aracı aynı yük ve requestId ile yeniden çağırın.

15b. Zenginleştirme Araçları

Alexandria'nın B2B veri sağlayıcıları (Apollo, FullEnrich, People Data Labs ve Data Legion) üzerinden kişi ve şirket arama ve zenginleştirme. Her iki araç da sunucunun kimlik bilgisine sahip olduğu her yerde listelenir: yerel anahtarsız modda veya anahtarsız oturumlarda listelenmez. Yalnızca arama yapan uç nokta bunları da içerir. Alexandria erişimi olan bir ekipte Firecrawl kimlik bilgisi (API anahtarı veya OAuth erişimi) gerekir.

Araç	Kullanım amacı	Sağlayıcılar
people_company_search	Kişileri (entity: "person") unvan, işveren, konum ve daha fazlasına göre veya şirketleri (entity: "company") sektör, çalışan sayısı, konum, teknoloji ya da kuruluş yılına göre bulma	apollo, fullenrich, people_data_labs
people_company_enrich	Bilinen kişileri profillere ve iş geçmişlerine, bilinen şirketleri ise firma bilgilerine eşleme. contact_fields ile bilinen kişiler için iş e-postası, kişisel e-posta veya cep telefonu bulma	fullenrich, apollo, people_data_labs, datalegion

Sağlayıcılar arasında hiçbir parametre paylaşılmaz. Her sağlayıcı bloğu, o sağlayıcıya özgü parametreleri kendi adlarıyla alır (Apollo'nun person_titles parametreleri, FullEnrich'in current_position_titles parametreleri, People Data Labs sql sorgusu veya Elasticsearch query sorgusu); dolayısıyla bir sağlayıcının desteklemediği filtre, bloğunda yer almaz. Bir sağlayıcı yalnızca çağrı kendi bloğunu içerdiğinde çalışır; sağlayıcı bloğu içermeyen bir çağrı (people_company_search için firecrawl_search bloğu da yoksa) no_provider ve aracın kabul ettiği bloklarla başarısız olur.

people_company_search, entity alır ve her sağlayıcı bloğu, ardından kişiler veya şirketler için o sağlayıcıya özgü arama filtrelerini alır. İsteğe bağlı bir firecrawl_search bloğu, sağlayıcılarla birlikte Firecrawl web araması çalıştırır; firecrawl_search sorgu parametrelerini kullanır ancak sayfa getirmez ve sonuçlarını kendi providers girdisinde bildirir. people_company_enrich, her sağlayıcı bloğunda tam olarak people veya companies seçeneklerinden birini alır: sağlayıcıya özgü girdi listesi; çağrı başına 1 ila 50 girdi ve her blokta aynı tür. Kişi zenginleştirmesine contact_fields (work_email, personal_email, mobile) eklemek, profil araması yerine aynı kişiler üzerinde iletişim bilgisi sağlayıcılarını çalıştırır; People Data Labs iletişim bilgisi araması sunmaz ve skipped bildirir.

{
  "name": "people_company_enrich",
  "arguments": {
    "fullenrich": { "companies": [{ "domain": "example.com" }] },
    "datalegion": { "companies": [{ "domain": "example.com" }, { "name": "Example Labs" }] }
  }
}

{
  "name": "people_company_enrich",
  "arguments": {
    "contact_fields": ["work_email"],
    "fullenrich": { "people": [{ "person_name": "Jane Doe", "company_domain": "example.com" }] },
    "apollo": { "people": [{ "name": "Jane Doe", "domain": "example.com" }] }
  }
}

Etkinleştirilmiş sağlayıcılar paralel çalışır ve sonuçlar birleştirilmez. Yanıt, her sağlayıcı için status değerini, returned kayıtlarını, credits değerini ve kendine ait results değerini içeren bir providers girdisi barındırır; people_company_enrich sonuçları, input_index değerini ilgili sağlayıcının girdi listesine taşır ve unmatched bulunamayan girdileri listeler. Başarısız bir sağlayıcıda note bulunur; sağlayıcının sonraki bir denemede başarılı olma olasılığı varsa retryable: true da bulunur. contact_fields ile, istenen bir alanı içermeyen Apollo veya Data Legion eşleşmesi (eşleşme başına ücretlendirilir) bu alanı missing içinde listeler; FullEnrich yalnızca bulduğu değerler için ücret alır ve bunları döndürür. Üst sistemde hâlâ çalışan bir FullEnrich iletişim bilgisi araması, unmatched altında değil, pending altında listelenir (daha sonra okumak için kullanılabilir olduğunda bir next_tool ile birlikte). credits_total ücretleri toplar. Araç açıklamalarında her sağlayıcının kredi ücreti listelenir.

Her iki araç da max_credits alır (varsayılan 1000). Herhangi bir sağlayıcı çalışmadan önce çağrının olası en yüksek maliyeti, her kayıt bulunmuş gibi bu fiyatlar üzerinden tahmin edilir; tahmini bu sınırı aşan çağrı, sağlayıcı başına tahmini içeren max_credits_exceeded ile başarısız olur. Çalışan bir çağrı ise credits_estimate ve max_credits değerlerini bildirir. Her iki araç da ajanların Firecrawl araçları arasında taşıdığı conversationId ve objective alanlarını kabul eder ve yok sayar; ayrıca doğrulamadan önce sık görülen, neredeyse doğru biçimleri düzeltir: liste beklenen yerde tek öğe, FullEnrich {"value"} filtreleri için düz dizeler, FullEnrich aralıkları için "51-200" ve tek öğelik liste olarak ya da fazladan bir anahtar altında gönderilen sağlayıcı bloğu. Hâlâ geçersiz olan bir bağımsız değişken, alanın adını, bloğunun kabul ettiği alanları ve örnek bir çağrıyı belirtir.

16. Kredi Kullanımı Aracı

Araç, kimliği doğrulanmış bir Firecrawl hesabı gerektirir ve salt okunurdur.

• firecrawl_credit_usage varsayılan olarak { "view": "current" } değerini alır ve remainingCredits, planCredits, billingPeriodStart ve billingPeriodEnd değerlerini döndürür. Ekipte ek kredi veya hibe varsa kalan krediler plan kredilerini aşabilir.
• { "view": "historical" } değerini, startDate, endDate ve creditsUsed içeren takvim ayı dönemleri için iletin. { "byApiKey": true } değerini iletmek geçmiş görünümünü de seçer ve dönemleri API anahtarına göre ayırır; her satırda apiKey bulunur. Bunun yerine { "byEndpoint": true } değerini iletmek, dönemleri kredileri kullanan uç noktaya göre ayırır (scrape, search, crawl, map, agent, ...); her satırda endpoint bulunur. Takvim ayı başına bir dönem yerine UTC günü başına bir dönem için { "bin": "day" } değerini iletin. byApiKey değerini byEndpoint ile veya bunlardan herhangi birini { "view": "current" } ile birlikte kullanmayın. En son dönemin endDate değeri null olabilir. Firecrawl API henüz uç nokta ayrımını veya günlük dönemleri sunmuyorsa sonuçta bir notice ve aylık rakamlar yer alır.

Programatik kullanım (kararsız)

Paket, sunucuyu başka bir çalışma ortamına gömmek için bir kitaplık giriş noktası da sunar. Bu özellik kararsızdır: API, seçenekleri ve türleri küçük ve yama sürümleri de dahil olmak üzere herhangi bir sürümde değişebilir; bu nedenle tam bir sürüme sabitleyin.

npm install --save-exact firecrawl-mcp zod

Örnek, araç parametrelerini zod ile tanımlar; bu nedenle gömme projesi bunu kendi bağımlılığı olarak yükler.

import { createFirecrawlMcpServer } from 'firecrawl-mcp/server';
import { z } from 'zod';

const server = createFirecrawlMcpServer({
  transport: 'httpStream',
  apiKey: process.env.FIRECRAWL_API_KEY,
  unstable_hooks: {
    registerExtraTools: (registrar) => {
      registrar.addTool({
        name: 'my_tool',
        description: 'An extra tool served next to the Firecrawl tools.',
        parameters: z.object({ text: z.string() }),
        execute: async ({ text }) => text,
      });
    },
  },
});

await server.start({
  transportType: 'httpStream',
  httpStream: { port: 3000, host: '127.0.0.1', endpoint: '/mcp', stateless: true },
});
// MCP endpoint: http://127.0.0.1:3000/mcp

host değerini açıkça ayarlayın. Bu değer olmadan sunucu localhost üzerinde dinler; Node bunu tek bir adrese bağlar (çoğu zaman yalnızca ::1), bu nedenle 127.0.0.1 adresine yapılan istekler reddedilir. Diğer makinelerden bağlantı kabul etmek için 0.0.0.0 veya :: kullanın; ancak bunu yalnızca ağ erişim denetimleri ya da bir unstable_hooks.authenticate kontrolü arkasında yapın. Böyle bir kontrol olmadan, bağlantı noktasına erişebilen her çağırana yapılandırılmış apiKey sunulur.

Kitaplık, istenmediği sürece Host veya Origin değerlerini denetlemez ve CORS üstbilgileri her kaynağa izin verir. Aynı makinedeki bir tarayıcıdan erişilebilen bir sunucu httpStream.allowedHosts değerini (örneğin ['localhost', '127.0.0.1', '[::1]']) iletmelidir: Host veya Origin üstbilgisi başka bir ana bilgisayar belirten istekler, sağlık yolu üzerindeki GET ve HEAD hariç, 403 alır; CORS üstbilgileri ise izin verilen kaynağı yansıtır. Komut satırı, yerel HTTP modunda bu listeyi ayarlar.

Seçenekler, CLI'ın ortam değişkenlerini yansıtır: apiUrl, apiKey, transport, logging, safeMode, fileAccess (local veya upload), requireCredential, searchFeedback ve endpointFeedback. unstable_hooks şunları kabul eder:

Kanca	Amaç
authenticate(request)	Bir istek için oturumu çözümler; isteği reddetmek için bir Response fırlatır.
wrapTool(tool)	Kayıtlı her araca ek özellikler uygular.
onToolResult(event)	Her araç çağrısının başlangıcını ve sonucunu gözlemler.
instructions	Sunucu yönergeleri veya varsayılanlar arasından seçim yapan bir işlev.
registerExtraTools(registrar, context)	Yerleşik araçlardan sonra araç ekler.
outboundRequest(session)	Her Firecrawl API isteği için kimlik bilgileri ve ek üstbilgiler.
beforeKeylessRequest(session, origin)	Anahtarsız bir isteği fırlatarak reddeder.
toolFilter(name)	Yerleşik araçları örneğe dahil etmez.
configureHttp(app)	HTTP rotaları ekler.
oauth.protectedResource	OAuth korumalı kaynak meta verilerini sunar.

Sunucu, resmi MCP TypeScript SDK'sı (@modelcontextprotocol/server) üzerine kurulmuştur. SDK'nın kendi türleri yerine firecrawl-mcp/server tarafından dışa aktarılan türleri (Session, ToolDefinition, ToolRegistrar, FirecrawlMcpServerHooks ve diğerleri) kullanın.

Giriş noktası ayrıca yerleşik araçların kullandığı recoveryPayload, normalizeHeader, requestOrigin, isRuntimeUserAgent, initializeClientSlug, searchToolBaseFields, searchOutputSchema ve structuredCompact gibi yardımcıları da dışa aktarır; böylece ek araçlar ve kancalar yerleşik davranışla eşleşebilir. Bunlar da kararsızdır.

Günlükleme Sistemi

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

• İşlem durumu ve ilerleme
• Performans ölçümleri
• Hız sınırı takibi
• Hata koşulları

Örnek günlük iletileri:

[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 sunar:

• API hız sınırı hataları MCP istemcisine iletilir
• Ayrıntılı hata iletileri
• 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 pull request gönderin

Katkıda bulunanlara teşekkürler

İlk uygulama için @vrknetha ve @cawstudios'a teşekkürler!

Sunucumuzu barındırdıkları için MCP.so ve Klavis AI'ya; sunucumuzu entegre ettikleri için @gstarwd, @xiangkaiz ve @zihaolin96'a teşekkürler.

Lisans

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

Yapılandırılmış veriler ve büyük sonuçlar

Kimliği doğrulanmış arama varsayılan olarak web sonuçlarını, anlamsal Alexandria araçlarını ve alan adı eşleşmelerini kullanır. Gerçek soruyla başlayın. Doğrudan anlamsal araç araması, seçili sözleşmeler veya aşamalı gezinme için firecrawl_find_tools kullanın: kategoriler → sağlayıcılar → kompakt araçlar → seçili sözleşme. Araçları firecrawl_scrape üzerinden çalıştırın; sıradan URL kazıma ve arama, sağlayıcı araçlarını hiçbir zaman otomatik olarak çalıştırmaz.

Seçili sözleşmeler için expand: ["options", "response"] tercih edin ve yalnızca girdi biçimi belirsizse örnek isteyin. İlgili yetenekleri birlikte inceleyin ve döndürülen sözleşmeleri yeniden kullanın.

Potansiyel olarak büyük bir iş akışı sonucu için, yürütmeden önce üst düzey bir requestId sağlayın ve bunu koruyun. İstemci yanıtı reddetse bile bu kimlik kullanılabilir durumda kalır. Normal URL kazımalarında bunun yerine döndürülen kazıma kimliğini kullanın.

Büyük ve saklanan bir iş akışı ya da normal kazıma sonucu için firecrawl_scrape çağrısını şu şekilde yapın:

{
  "alexandria": {
    "provider": "firecrawl",
    "capability": "bash",
    "options": {
      "requestId": "<source-request-or-scrape-id>",
      "command": "ls -lh"
    }
  }
}

stdout, stderr, exitCode ve workspaceId değerlerini data.alexandria[0].data içinde okuyun. jq kullanarak response.json değerini incelemek için options: {workspaceId, command} ile veya normal kazımalar için sınırlı metin komutlarıyla document.md ile devam edin. Çıktıyı seçici tutun. Kaynak yükleme bağımsız bir çağrı olmalıdır; iç içe geçmiş kaynak kimliği, üst düzey yürütme isteği kimliğinden farklıdır. Çalışma alanları beş dakika boyunca etkinlik olmazsa sona erer ve ZDR ile API sağlayıcısı iş akışı yükleri dahil her sonuç saklanmaz. Arama kimlikleri desteklenmez.

İş akışı kaynaklarında response.json, API zarfını korur: .data.alexandria[].data değerini, ardından boş değilse seçili sözleşmenin response.key değerini seçin. Biçim biliniyorsa anahtarları tekrar tekrar incelemek yerine ilgili sayımları ve projeksiyonları tek bir Bash komutunda birleştirin.

20.000 tahmini belirteci aşan başarılı Alexandria yürütme yanıtları (serileştirilmiş UTF-8 baytlarının dörde bölünmesiyle hesaplanır), uzak Bash tüm toplu veriye erişilebildiğini doğruladıktan sonra küçük bir devir yanıtı döndürür. Saklanan veriyi incelemek için nextTool yönergelerini izleyin. Bu, bir Bash çağrısı ekler ve beş dakikalık boşta kalma TTL'sine sahip bir çalışma alanı başlatır. Yükün tamamı korunur. Doğrulama başarısız olursa özgün yanıt satır içinde kalır. Arama, normal URL kazıma, hata yanıtları ve Firecrawl yardımcı programı çağrıları değişmez. Bu teslimat bütçesi, istemcinin kalan bağlamını ölçmez; işlem yerelinde sonuç önbelleği eklenmez. Yerel dosya sistemi araçları kullanılabiliyorsa CLI çıktısını kaydedip seçili bölümleri okumak da bir seçenektir.

CLI keşif sırası şu MCP çağrılarına karşılık gelir:

Amaç	Araç	Bağımsız değişkenler
Web + anlamsal + alan adı araçları	firecrawl_search	{"query":"<user question>"}
Yalnızca anlamsal araçlar	firecrawl_search	{"query":"<user question>","sources":["alexandria"]}
Kategoriler	firecrawl_find_tools	{}
Bir kategorideki sağlayıcılar	firecrawl_find_tools	{"categories":["<category-id>"]}
Kompakt sağlayıcı araçları	firecrawl_find_tools	{"providers":["<provider-id>"]}
Seçili sözleşme	firecrawl_find_tools	{"providers":["<provider-id>"],"capabilities":["<capability-id>"]}
Yürüt	firecrawl_scrape	{"alexandria":{"provider":"<provider-id>","capability":"<capability-id>","options":{"<required-field>":"<value>"}}}

Araç Bulma ve yürütme, hem tam yüzeyde hem de arama yüzeyinde kullanılabilir. Başka bir keşif çağrısı yapmak yerine, varsa aramadan gelen eksiksiz bir sözleşmeyi yeniden kullanın. Yalnızca daha fazla sonuç gerektiğinde döndürülen nextTool gezinme yönergelerini izleyin.

Alexandria oturum geri bildirimi

Mevcut firecrawl_feedback aracı endpoint: "alexandria" kabul eder:

{
  "endpoint": "alexandria",
  "rating": "partial",
  "requestedWebsite": {
    "url": "https://example.com",
    "requestedFunctionality": "Find records and download their attachments"
  },
  "objective": "Compare contract requirements across agencies before bidding",
  "rationale": "Found summaries but could not retrieve attachments"
}

İsteğe bağlı objective, oturumun temel amacıdır: aracının veya kullanıcısının, requestedWebsite içindeki tek bir web sitesinin ötesinde, nihayetinde neyi başarmaya çalıştığı.

Bu işlem, iş kimliği olmadan kimliği doğrulanmış POST /v2/feedback kullanır. Ekibin en son Alexandria arama, keşif veya yürütme işleminin üzerinden 20 dakika geçmeden ulaşmalıdır; daha sonra gönderilen geri bildirimler FEEDBACK_WINDOW_EXPIRED ile reddedilir. Uygun geri bildirimler, günlük sınırlara (web sitesi başına 10 kredi ve ekip başına 100 kredi, UTC günü) tabi olarak 1 krediyi iade edebilir. Bu sınırlardan herhangi biri aşıldığında geri bildirim kaydedilmeye devam eder ancak kredi iadesi yapılmaz ve yanıt websiteCapReached veya dailyCapReached değerini ayarlar. İsteğe bağlı providerFeedback ve capabilityFeedback dizileri, kapsam boşluklarını ve yürütme sorunlarını açıklar; araç şeması desteklenen sorun değerlerini listeler. Bir new_capability_request, requestedFunctionality gerektirir; missing_capability (sağlayıcı mevcut ancak gerekli yeteneğe sahip değil) gerektirmez. Mevcut geri bildirim devre dışı bırakma ve kimlik doğrulama denetimleri geçerlidir.

Uygun Alexandria yürütme ve keşif sonuçları, araç adını ve bağımsız değişkenlerin bir taslağını içeren bir feedbackTool işaretçisi içerir. bash gibi Firecrawl dahili çağrılarında ve firecrawl_feedback kayıtlı olmadığında (FIRECRAWL_NO_ENDPOINT_FEEDBACK veya anahtarsız başlatma) işaretçi eklenmez.