SerpApi MCP

SerpApi MCP Sunucusu

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

Özellikler

• Çoklu Motor Arama: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay ve daha fazlası
• Motor Kaynakları: Motor başına parametre şemaları MCP kaynakları aracılığıyla kullanılabilir (Arama Aracı'na bakın)
• Gerçek Zamanlı Hava Durumu Verileri: Arama sorguları aracılığıyla konum tabanlı hava durumu ve tahminler
• Borsa Piyasa Verileri: Arama entegrasyonu ile ş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 modlarla yapılandırılmış JSON çıktısı
• Markdown Yanıtları: Token kullanımını ortalama %50, karmaşık iç içe JSON içeren API'ler için %90'dan fazla azaltır.
• Etkileşimli Arayüz (MCP Uygulamaları): Sonuçları destekleyen ana bilgisayarlarda etkileşimli bir arayüz olarak gösteren search_table ve search_dashboard araçları
• Claude Desktop Uzantısı: Bir MCP Paketi (.mcpb) ile tek tıklamayla yerel kurulum, aşağıya bakın

Hızlı Başlangıç

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

Claude Desktop'u 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 öğesinden okur)

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

Kendi Kendine Barındırma

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

Claude Desktop'u 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 Paketi)

Yerel, tek tıklamayla kurulum için, en son sürümden .mcpb paketini indirin (veya aşağıdaki gibi derleyin) ve Claude Desktop ile açın (veya Ayarlar → Uzantılar üzerine sürükleyin). Claude Desktop kurulum sırasında SerpApi API anahtarınızı ister, bunu hassas bir ayar olarak saklar ve sunucuyu stdio üzerinden yerel olarak çalıştırır. Paket, MCPB uv çalışma zamanını kullanır: yalnızca kaynak kodu, pyproject.toml ve uv.lock dosyalarını içerir ve Claude Desktop kurulum sırasında Python ve kilitli bağımlılıkları uv ile sağlar; böylece hiçbir şey paketlenmez ve tek bir paket macOS, Windows ve Linux üzerinde çalışır.

uv run mcpb/build.py   # needs Node.js for the MCPB CLI; writes dist/serpapi-mcp-<version>.mcpb

Paketle ilgili her şey mcpb/ içinde ve proje kökünde .mcpbignore dosyasında bulunur. Derleme, motor şemalarını SerpApi Playground'dan yeniden oluşturur (--no-rebuild-engines çalışma ağacından engines/ paketler), mcpb/manifest.json dosyasını doğrular, git tarafından izlenen dosyaları .mcpbignore hariç manifest ile paket kökünde paketler, ardından geçici bir dizine kurar ve çalıştığından emin olmak için stdio üzerinden başlatır (--no-smoke son adımı atlar). Paket yalnızca sürüm zamanında derlenir: bir v<version> etiketi göndermek, test paketini çalıştıran ve ardından barındırılan sunucuyu dağıtan, MCP Kayıt girişini yayınlayan ve paketi derleyip GitHub sürümüne ekleyen sürüm iş akışını çalıştırır. Çekme istekleri, tests/test_mcpb.py içindeki manifest ve stdio giriş noktası testlerini çalıştırır ancak paket paketlemez.

Aynı stdio giriş noktası, sunucuları alt işlem olarak başlatan herhangi bir yerel MCP ana bilgisayarıyla ç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:

• Başlık tabanlı: Authorization: Bearer YOUR_API_KEY (önerilir: anahtar URL'lerden ve günlüklerden uzak kalır)
• Yol tabanlı: /YOUR_API_KEY/mcp, başlık 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 Uygulama araçları bir anahtar gerektirir ve olmadan hata döndürür.

Arama Aracı

MCP sunucusu, tüm SerpApi motorlarını ve sonuç türlerini destekleyen tek bir ana Arama Aracına sahiptir. Tüm kullanılabilir parametreleri SerpApi API referansında bulabilirsiniz. Motor parametre şemaları ayrıca MCP kaynakları olarak sunulur: serpapi://engines (dizin) ve serpapi://engines/<engine>. Argüman tamamlamayı destekleyen istemciler, serpapi://engines/{engine_name} için motor adı önerileri isteyebilir. Örneğin, google_f öneki eşleşen motor tanımlayıcılarını önerir. Bu, kaynak URI parametresini tamamlar, rastgele arama sorgularını değil.

Sağlayabileceğiniz parametreler her API motoruna özgüdür. 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 atlayı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şmeden döndürülür
• ...diğer parametreler için SerpApi API referansına 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 Motorlar: Google, Bing, Yahoo, DuckDuckGo, YouTube, eBay ve daha fazlası (bkz. serpapi://engines).

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

Arama yanıtları mevcut MCP structuredContent.result dizesini korur ve metin içeriğine aynı dizeyi dahil eder. JSON çıktısı için result serileştirilmiş JSON içerir; mevcut istemciler JSON.parse(response.structuredContent.result) ile ayrıştırmaya devam edebilir. Markdown çıktısı için değişmemiş Markdown'ı içerir. Hatalar ve iptaller aynı sarmalayıcıyı kullanır. Arama yürütme hataları isError: true ayarlar; FastMCP'nin üst düzey call_tool() kullanan istemciler ToolError işlemeli veya sonuç bayrağını incelemek için call_tool_mcp() kullanmalıdır. MCP araç sonuçlarına bakın.

search, eksik parametreleri belirlemek için motor kataloğunu ve motora özgü kuralları kullanır. MCP 2026-07-28'i destekleyen istemciler, herhangi bir arama çalıştırılmadan önce bir form alır. Kabul edilen yanıtlar doğrulanır; reddetme veya iptal arama çalıştırmaz. Eski istemciler ve form çıkarma özelliği olmayan istemciler, aracının konuşmada sorabilmesi için eksik parametreleri listeleyen bir hata alır. MCP giriş isteklerine bakın.

• Google Flights: kalkış ve varış tanımlayıcıları, kalkış tarihi ve gidiş-dönüş için dönüş tarihi. Tarihler ve havaalanı tanımlayıcıları kontrol edilir. Token tabanlı aramalar, çok şehirli güzergahlar ve selected_flights_json mevcut davranışlarını korur.
• Google Hotels: hedef veya otel sorgusu, giriş tarihi ve çıkış tarihi. Çıkış, girişten sonra olmalıdır. Misafir sayıları ve diğer isteğe bağlı filtreler, çağıranın değerlerini veya API varsayılanlarını korur.
• Google Maps Directions: eksik başlangıç ve varış adresleri. Önceden sağlanan koordinatlar veya yer veri kimlikleri ilgili uç noktayı karşılar.
• Diğer katalog motorları, YouTube'un search_query, Yelp'in find_loc ve Amazon'un k gibi gerekli alanlarını kullanır. Motor kuralları, Amazon kategori düğümleri, eBay kategorileri ve Google Scholar alıntı aramaları dahil bilinen varsayılanları ve alternatifleri hesaba katar.

Form, her istekteki orijinal argümanlardan türetilir. requestState veya işlem yerel devam depolaması kullanmaz; böylece paylaşılan durum koruma anahtarı olmadan bir yeniden deneme başka bir kopyada çalışabilir. Kimlik doğrulama her HTTP isteğinde uygulanır ve yalnızca istenen alanlar için yanıtlar kullanılır. Bir yanıt başka bir gereksinim getirirse, araç aracının yeni bir çağrıda sağlaması için kalan alanları listeler.

Rehberli aramayı genişletmek için motorun engines/<engine>.json dosyasına gerekli alanları, açıklamaları, türleri ve seçenekleri ekleyin. Gereksinimler diğer parametrelere, varsayılanlara veya alternatiflere bağlı olduğunda src/engine_input_rules.py dosyasına bir EngineInputRules girişi ekleyin. src/search_input.py içindeki paylaşılan MCP işleyicisi motora özgü dallar gerektirmez. Formlar dizeleri, sayıları, boole'ları ve tek seçimli alanları destekler; desteklenmeyen karmaşık alanlar eksik parametre hatası alır. Bilinmeyen motorlar SerpApi'ye iletilir.

Etkileşimli Arayüz (MCP Uygulamaları)

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

• search_table: sıralanabilir, aranabilir bir tablo olarak organik sonuçlar.
• search_dashboard: özet metrikler, kaynak dağılımı grafiği ve tıklayarak genişletilebilir ayrıntı paneli olan bir sonuç tablosu.

Her ikisi de search ile aynı params kabul eder. MCP Uygulamalarını desteklemeyen ana bilgisayarlar bu araçları yok sayar.

Bunları bir MCP ana bilgisayarı olmadan yerel olarak önizleyin:

uv run fastmcp dev apps src/server.py

Geliştirme

# Local development
uv sync && uv run src/server.py

# Docker
docker build -t serpapi-mcp . && docker run -p 8000:8000 serpapi-mcp

# Build the Claude Desktop extension (MCP Bundle); rebuilds engines, needs Node.js for the MCPB CLI
uv run mcpb/build.py

# Release: update pyproject.toml, server.json, mcpb/manifest.json and uv.lock together.
uv run --no-sync scripts/bump_version.py 2.0.0
# Review and commit the changes before tagging the release.
# Nothing ships on a plain push to main. The tag runs the release workflow, which runs the test
# suite and then deploys the hosted server, publishes server.json to the MCP Registry, and builds
# the MCP Bundle and attaches it to the GitHub release.
git tag v2.0.0 && git push origin v2.0.0

# Regenerate engine resources (Playground scrape)
python build-engines.py

# Testing with MCP Inspector
npx @modelcontextprotocol/inspector
# Configure: URL mcp.serpapi.com/YOUR_KEY/mcp, Transport "Streamable HTTP transport"

Sorun Giderme

• "Eksik API anahtarı": Anahtarı URL yoluna /{YOUR_KEY}/mcp veya başlığa Bearer YOUR_KEY ekleyin
• "Geçersiz anahtar": serpapi.com/dashboard adresinde doğrulayın
• "Hız sınırı aşıldı": Bekleyin veya SerpApi planınızı yükseltin
• "Sonuç yok": Farklı bir sorgu veya motor deneyin

Gizlilik Politikası

• Gönderilen: yalnızca MCP ana bilgisayarının bir araç çağrısına ilettiği parametreler. Sunucu, konuşmanın geri kalanını veya ana bilgisayardaki dosyaları, belleği veya geçmişi asla görmez.
• İletilen: her arama, API anahtarınızla serpapi.com adresine gider; sonuçlar değişmeden geri gelir. SerpApi'nin aramaları ve hesapları nasıl işlediği hakkında SerpApi Gizlilik Politikasına bakın.
• Saklanan: mcp.serpapi.com istek metriklerini (yöntem, durum kodu, süre) kaydeder ve hiçbir sorgu veya sonuç saklamaz. URL yolundaki bir anahtar istek günlüklerinde görünebilir, bu nedenle başlığı tercih edin.
• Yerel paket: Claude Desktop uzantısı makinenizde çalışır, anahtarı Claude Desktop'un ayarlarında tutar ve serpapi.com doğrudan çağırır. Hiçbir şey mcp.serpapi.com üzerinden geçmez.
• İletişim: privacy@serpapi.com veya bir sorun açın.

Katkıda Bulunma

1. Depoyu çatallayın
2. Özellik dalınızı oluşturun: git checkout -b feature/amazing-feature
3. Bağımlılıkları yükleyin: uv install
4. Değişikliklerinizi yapın
5. Değişiklikleri kaydedin: git commit -m 'Add amazing feature'
6. Dala gönderin: git push origin feature/amazing-feature
7. Bir Çekme İsteği açın

Lisans

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