SerpApi MCP

SerpApi MCP Server

Kapsamlı arama motoru sonuçları ve veri çıkarma özellikleri için SerpApi ile entegre olan bir Model Context Protocol (MCP) sunucusu uygulaması.

Özellikler

• Çoklu Arama Motoru Desteği: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay ve daha fazlası
• Arama Motoru Kaynakları: MCP kaynakları üzerinden her arama motoruna özel parametre şemaları (Search Tool bölümüne bakın)
• Gerçek Zamanlı Hava Durumu Verileri: Arama sorguları aracılığıyla konuma dayalı hava durumu ve tahminler
• Borsa Verileri: Arama entegrasyonu üzerinden şirket finansalları ve piyasa verileri
• Dinamik Sonuç İşleme: Farklı sonuç türlerini otomatik olarak algılar ve biçimlendirir
• Esnek Yanıt Modları: Tam veya kompakt JSON yanıtları
• JSON Yanıtları (varsayılan): Tam veya kompakt modlarda yapılandırılmış JSON çıktısı
• Markdown Yanıtları: Belirteç kullanımını ortalama %50, karmaşık iç içe JSON içeren API'lerde ise %90'dan fazla azaltır.
• Etkileşimli Arayüz (MCP Apps): Sonuçları destekleyen ana bilgisayarlarda etkileşimli arayüz olarak görüntüleyen, isteğe bağlı search_table ve search_dashboard araçları
• Claude Desktop Uzantısı: MCP Bundle (.mcpb) üzerinden tek tıklamayla yerel kurulum; aşağıya bakın

Hızlı başlangıç

SerpApi MCP Server, barındırılan bir hizmet olarak mcp.serpapi.com adresinde kullanılabilir. Bağlanmak için bir API anahtarı sağlamanız gerekir. API anahtarınızı SerpApi kontrol panelinizde bulabilirsiniz.

Claude Desktop'ı barındırılan sunucuyu kullanacak şekilde yapılandırabilirsiniz:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

Barındırılan sunucuyu şu MCP istemcilerine de ekleyebilirsiniz:

OpenClaw

openclaw mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp --transport streamable-http

Claude Code

claude mcp add --transport http serpapi https://mcp.serpapi.com/mcp --header "Authorization: Bearer YOUR_SERPAPI_API_KEY"

Hermes

hermes mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Codex (anahtarı kabuğunuzdaki SERPAPI_API_KEY değişkeninden okur)

codex mcp add serpapi --url https://mcp.serpapi.com/mcp --bearer-token-env-var SERPAPI_API_KEY

Kendi sunucunuzu barındırma

git clone https://github.com/serpapi/serpapi-mcp.git
cd serpapi-mcp
uv sync && uv run src/server.py

Claude Desktop'ı yapılandırın:

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "http://localhost:8000/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

API anahtarınızı alın: serpapi.com/manage-api-key

Claude Desktop Uzantısı (MCP bundle)

Yerel olarak tek tıklamayla kurmak için en son sürümden .mcpb bundle'ını indirin ve Claude Desktop ile açın (veya Settings → Extensions üzerine bırakın). Claude Desktop kurulum sırasında SerpApi API anahtarınızı ister, anahtarı hassas bir ayar olarak saklar ve sunucuyu yerel olarak stdio üzerinden çalıştırır. Kurulum sırasında uv ile Python ve bağımlılıkları yükler. Aynı bundle macOS, Windows ve Linux'ta çalışır.

Aynı stdio giriş noktası, sunucuları alt süreç olarak başlatan tüm yerel MCP ana bilgisayarlarında çalışır:

{
  "mcpServers": {
    "serpapi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/serpapi-mcp", "--frozen", "--no-dev", "src/stdio.py"],
      "env": { "SERPAPI_API_KEY": "YOUR_SERPAPI_API_KEY" }
    }
  }
}

Kimlik doğrulama

İki yöntem desteklenir:

• Üstbilgi tabanlı: Authorization: Bearer YOUR_API_KEY (önerilir: anahtar URL'lerde ve günlüklerde yer almaz)
• Yol tabanlı: /YOUR_API_KEY/mcp; üstbilgi ayarlayamayan istemciler için

Örnekler:

# Header-based
curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'

# Path-based
curl "https://mcp.serpapi.com/your_key/mcp" -d '...'

Bağlanmak, araçları listelemek veya kaynakları okumak için anahtar gerekmez. search ve App araçları anahtar gerektirir ve anahtar olmadan hata döndürür.

Search tool

MCP sunucusunda tüm SerpApi arama motorlarını ve sonuç türlerini destekleyen bir ana arama aracı bulunur. Kullanılabilir tüm parametreleri SerpApi API başvurusunda bulabilirsiniz. Arama motoru parametre şemaları MCP kaynakları olarak da sunulur: serpapi://engines (dizin) ve serpapi://engines/<engine>. Bağımsız değişken tamamlama özelliğini destekleyen istemciler, serpapi://engines/{engine_name} için arama motoru adı önerileri isteyebilir. Örneğin, google_f öneki eşleşen arama motoru tanımlayıcılarını önerir. Bu özellik, rastgele arama sorgularını değil, kaynak URI parametresini tamamlar.

Sağlayabileceğiniz parametreler her API arama motoruna özeldir. Aşağıda bazı örnek parametreler verilmiştir:

• params.q (gerekli): Arama sorgusu
• params.engine: Arama motoru (varsayılan: "google_light")
• params.location: Coğrafi filtre
• params.output: Yanıt biçimi; JSON için boş bırakın (varsayılan) veya Markdown için "md" olarak ayarlayın
• mode: Yanıt modu; "compact" JSON'dan meta verileri kaldırırken Markdown'ı değiştirmeden döndürür
• ...diğer parametreler için SerpApi API başvurusuna bakın

Örnekler:

{"name": "search", "arguments": {"params": {"q": "coffee shops", "location": "Austin, TX"}}}
{"name": "search", "arguments": {"params": {"q": "weather in London"}}}
{"name": "search", "arguments": {"params": {"q": "AAPL stock"}}}
{"name": "search", "arguments": {"params": {"q": "news"}, "mode": "compact"}}
{"name": "search", "arguments": {"params": {"q": "detailed search"}, "mode": "complete"}}
{"name": "search", "arguments": {"params": {"q": "news", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "amazon", "k": "mechanical keyboards", "amazon_domain": "amazon.com", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "google_scholar", "q": "retrieval augmented generation"}}}
{"name": "search", "arguments": {"params": {"engine": "youtube", "search_query": "how to make espresso"}}}
{"name": "search", "arguments": {"params": {"engine": "apple_app_store", "term": "habit tracker"}}}
{"name": "search", "arguments": {"params": {"engine": "ebay", "_nkw": "vintage mechanical keyboard"}}}

Desteklenen arama motorları: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay ve daha fazlası (serpapi://engines bölümüne bakın).

Sonuç türleri: Yanıt kutuları, organik sonuçlar, haberler, görseller, alışveriş sonuçları — otomatik olarak algılanır ve biçimlendirilir.

Arama yanıtları mevcut MCP structuredContent.result dizesini korur ve aynı dizeyi metin içeriğine ekler. JSON çıktısında result serileştirilmiş JSON içerir; mevcut istemciler bunu JSON.parse(response.structuredContent.result) ile ayrıştırmaya devam edebilir. Markdown çıktısında değiştirilmemiş Markdown bulunur. Hatalar ve iptaller de aynı sarmalayıcıyı kullanır. Arama yürütme hatalarında isError: true ayarlanır; FastMCP'nin üst düzey call_tool() özelliğini kullanan istemciler ToolError durumunu işlemeli veya sonuç bayrağını incelemek için call_tool_mcp() kullanmalıdır. MCP araç sonuçları bölümüne bakın.

search, eksik parametreleri belirlemek için arama motoru kataloğunu ve arama motoruna özel kuralları kullanır. MCP 2026-07-28'i destekleyen istemcilere herhangi bir arama çalıştırılmadan önce bir form sunulur. Kabul edilen yanıtlar doğrulanır; reddetme veya iptal durumunda arama yapılmaz. Eski istemciler ve form isteme özelliği olmayan istemciler, aracının konuşma sırasında sorabilmesi için eksik parametreleri listeleyen bir hata alır. MCP girdi istekleri bölümüne bakın.

• Google Flights: kalkış ve varış tanımlayıcıları, kalkış tarihi ve gidiş-dönüş seyahatleri için dönüş tarihi. Tarihler ve havaalanı tanımlayıcıları doğrulanır. Belirteç tabanlı aramalar, çok şehirli seyahat planları ve selected_flights_json mevcut davranışlarını korur.
• Google Hotels: varış noktası veya otel sorgusu, giriş tarihi ve çıkış tarihi. Çıkış tarihi giriş tarihinden sonra olmalıdır. Konuk sayıları ve diğer isteğe bağlı filtreler, çağıranın değerlerini veya API varsayılanlarını kullanır.
• Google Maps Directions: eksik başlangıç ve varış adresleri. Önceden sağlanan koordinatlar veya yer verisi kimlikleri, ilgili uç noktayı karşılar.
• Katalogdaki diğer arama motorları, YouTube'un search_query, Yelp'in find_loc ve Amazon'un k gibi gerekli alanlarını kullanır. Arama motoru kuralları, Amazon kategori düğümleri, eBay kategorileri ve Google Scholar atıf aramaları dahil olmak üzere bilinen varsayılanları ve alternatifleri dikkate alır.

Bir yanıt başka bir gereksinim ortaya çıkarırsa araç, aracının yeni bir çağrıda sağlaması için kalan alanları listeler. Formlar dizeleri, sayıları, boole değerlerini ve tek seçenekli alanları destekler; desteklenmeyen karmaşık alanlar eksik parametre hatası döndürür. Bilinmeyen arama motorları SerpApi'ye olduğu gibi iletilir.

Extract tool

extract aracı web sayfalarını okur ve içeriklerini yapılandırılmış JSON veya Markdown olarak döndürür. Tek bir sayfadan içerik çıkarabilir, bir web sitesinin URL'lerini bulabilir veya birden fazla sayfayı tarayabilirsiniz. Kullanılabilir tüm parametreleri Extract API başvurusunda veya serpapi://engines/extract kaynağında bulabilirsiniz.

Sağlayabileceğiniz bazı parametreler:

• params.url (gerekli): Sayfa veya web sitesi URL'si
• params.mode: Çıkarma modu; "scrape" (varsayılan) tek bir sayfayı okur, "map" URL'leri bulur ve "crawl" birden fazla sayfadan içerik çıkarır
• params.include_markdown: Sayfa içeriğini Markdown olarak ekler; scrape ve crawl için varsayılan değer true olur veya devre dışı bırakmak için false olarak ayarlanır
• params.output: Yanıt biçimi; tam modda varsayılan olarak "json", kompakt modda ise "md" kullanılır. Biçimi geçersiz kılmak için açıkça ayarlayın.
• params.max_pages: Başlangıç sayfası dahil taranacak en fazla sayfa sayısı (varsayılan: 10, en fazla: 100)
• params.json_restrictor: Döndürülecek alanları seçin; örneğin "markdown,error"
• mode: Yanıt modu; "complete" (varsayılan) yanıtın tamamını döndürür. "compact" varsayılan olarak yerel Markdown'ı döndürür. Açıkça belirtilen bir params.output="json" ile tek sayfalı kompakt çıkarma, mevcut olduğunda üst düzey markdown alanını korur ve API hatalarını muhafaza eder. Markdown içermeyen yanıtlar, başka bir arama motoruna yönlendirilen sonuçlar dahil, meta veriler kaldırılarak verilerini korur. JSON kullanılırken açıkça belirtilen params.json_restrictor değerleri ve params.include_markdown=false önceliklidir. Map ve crawl için kompakt JSON meta verileri kaldırır. Markdown çıktısı değiştirilmeden döndürülür.

Örnekler:

{"name": "extract", "arguments": {"params": {"url": "https://example.com"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com"}, "mode": "compact"}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "output": "md"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "map"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "crawl", "max_pages": 2}}}

Tek bir sayfanın içeriğini yerel Markdown olarak almak için mode="compact" kullanın. Bunun yerine markdown alanını içeren JSON almak için params.output="json" ekleyin. Tam JSON bu alanı varsayılan olarak içerir; crawl JSON ise her pages girdisinde içerir. params.output="json" ve params.include_markdown=false ayarlandığında Markdown dışındaki yapılandırılmış alanlar korunur.

Önbelleğe alınmamış bir istekte tarama, başarıyla çıkarılan her sayfa için bir arama kredisi kullanır. Çıkarılacak sayfa sayısını sınırlamak için params.max_pages kullanın.

Etkileşimli arayüz (MCP apps)

search aracı varsayılan olarak JSON döndürür. MCP Apps uzantısını (SEP-1865) destekleyen ana bilgisayarlar için isteğe bağlı iki araç, sonuçları doğrudan konuşmada etkileşimli bir arayüz olarak görüntüler; böylece SERP JSON verilerinin büyük bölümü modelin bağlam penceresine girmez:

• search_table: Sıralanabilir ve aranabilir bir tabloda organik sonuçlar.
• search_dashboard: Özet metrikler, kaynak dağılım grafiği ve tıklayarak genişletilebilen ayrıntı paneline sahip bir sonuç tablosu.

Her ikisi de search ile aynı params değerini kabul eder. MCP Apps'i desteklemeyen ana bilgisayarlar bu araçları yok sayar.

Sorun giderme

• "Missing API key": Anahtarı URL yoluna /{YOUR_KEY}/mcp veya üstbilgiye Bearer YOUR_KEY ekleyin
• "Invalid key": serpapi.com/dashboard adresinde doğrulayın
• "Rate limit exceeded": Bekleyin veya SerpApi planınızı yükseltin
• "No results": Farklı bir sorgu veya arama motoru deneyin

Gizlilik politikası

• Gönderilenler: Yalnızca MCP ana bilgisayarının araç çağrısına ilettiği parametreler. Sunucu konuşmanın geri kalanını, ana bilgisayardaki dosyaları, belleği veya geçmişi hiçbir zaman görmez.
• İletilenler: Her arama, API anahtarınızla birlikte serpapi.com adresine gönderilir; sonuçlar değiştirilmeden geri döner. SerpApi'nin aramaları ve hesapları nasıl işlediği hakkında bilgi için SerpApi Gizlilik Politikası'na bakın.
• Saklananlar: mcp.serpapi.com istek ölçümlerini (yöntem, durum kodu, süre) kaydeder; sorguları veya sonuçları saklamaz. URL yolundaki bir anahtar istek günlüklerinde görünebilir; bu nedenle üstbilgi kullanmanız önerilir.
• Yerel bundle: Claude Desktop uzantısı makinenizde çalışır, anahtarı Claude Desktop ayarlarında saklar ve doğrudan serpapi.com adresini çağırır. Hiçbir veri mcp.serpapi.com üzerinden geçmez.
• İletişim: privacy@serpapi.com adresine yazın veya bir sorun açın.

Katkıda bulunma

Geliştirme kurulumu, şema yenileme komutları, testler, Docker ve MCP Bundle derlemeleri ile sürümler hakkında bilgi için CONTRIBUTING.md dosyasına bakın.

Lisans

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