DuckDuckGo Search MCP Server

DuckDuckGo üzerinden web arama özellikleri sağlayan bir Model Context Protocol (MCP) sunucusu. İçerik getirme ve analiz için ek özellikler içerir.

Hızlı Başlangıç

uvx duckduckgo-mcp-server

Özellikler

• Web Arama: DuckDuckGo'da gelişmiş rate limiting ve sonuç formatlaması ile arama yapın
• İçerik Getirme: Web sayfası içeriğini almak ve akıllı metin çıkarımı ile analiz edin
• Rate Limiting: Arama ve içerik getirme için yerleşik rate limit koruması
• Hata Yönetimi: Kapsamlı hata yönetimi ve loglama
• LLM Dostu Çıktı: Büyük dil modelleri için özel olarak formatlanmış sonuçlar

Kurulum

PyPI'dan uv kullanarak kurulum yapın:

uv pip install duckduckgo-mcp-server

Kullanım

Claude Desktop ile Çalıştırma

1. Claude Desktop dosyasını indirin
2. Claude Desktop yapılandırmanızı oluşturun veya düzenleyin:
   • macOS üzerinde: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows üzerinde: %APPDATA%\Claude\claude_desktop_config.json

Aşağıdaki yapılandırmayı ekleyin:

Temel Yapılandırma (SafeSearch Olmadan, Varsayılan Bölge Olmadan):

{
    "mcpServers": {
        "ddg-search": {
            "command": "uvx",
            "args": ["duckduckgo-mcp-server"]
        }
    }
}

SafeSearch ve Bölge Yapılandırması İle:

{
    "mcpServers": {
        "ddg-search": {
            "command": "uvx",
            "args": ["duckduckgo-mcp-server"],
            "env": {
                "DDG_SAFE_SEARCH": "STRICT",
                "DDG_REGION": "cn-zh"
            }
        }
    }
}

Yapılandırma Seçenekleri:

• DDG_SAFE_SEARCH: SafeSearch filtreleme seviyesi (isteğe bağlı)
  • STRICT: Maksimum içerik filtrelemesi (kp=1)
  • MODERATE: Dengeli filtreleme (kp=-1, belirtilmezse varsayılan)
  • OFF: İçerik filtrelemesi yok (kp=-2)
• DDG_REGION: Varsayılan bölge/dil kodu (isteğe bağlı, aşağıda örnekler)
  • us-en: Amerika Birleşik Devletleri (İngilizce)
  • cn-zh: Çin (Çince)
  • jp-ja: Japonya (Japonca)
  • wt-wt: Belirli bir bölge yok
  • DuckDuckGo'nun varsayılan davranışı için boş bırakın

3. Claude Desktop'ı yeniden başlatın

Claude Code ile Çalıştırma

1. Claude Code dosyasını indirin
2. uvenv kurulu olduğundan ve uvx komutunun kullanılabilir olduğundan emin olun
3. MCP sunucusunu ekleyin: claude mcp add ddg-search uvx duckduckgo-mcp-server

SSE veya Streamable HTTP ile Çalıştırma

Sunucu diğer MCP istemcileriyle kullanmak için alternatif taşımalar destekler:

# SSE taşıması
uvx duckduckgo-mcp-server --transport sse

# Streamable HTTP taşıması
uvx duckduckgo-mcp-server --transport streamable-http

Varsayılan taşıma stdio olup, Claude Desktop ve Claude Code tarafından kullanılır.

sse veya streamable-http ile çalıştırırken, --host ve --port bayraklarıyla varsayılan bağlama adresini (127.0.0.1:8000) geçersiz kılın:

uvx duckduckgo-mcp-server --transport streamable-http --host 0.0.0.0 --port 7070

Fetch Backend (bot algılamayı atlama)

Bazı siteler, User-Agent ne olursa olsun varsayılan httpx istemcisini engeller — Cloudflare Bot Management ve benzer filtreler JA3/TLS handshake'ini başlıkları değil anahtarlar. İsteğe bağlı bir backend olan curl (curl_cffi aracılığıyla), gerçek bir Chrome tarayıcısının TLS handshake'ini taklit eder ve bu kontrolleri geçer.

Kurulum:

# Varsayılan kurulum (yalnızca httpx)
uv pip install duckduckgo-mcp-server

# İsteğe bağlı tarayıcı backend'i ile
uv pip install "duckduckgo-mcp-server[browser]"

Backend seçenekleri:

Değer	Davranış	[browser] Gerekli
httpx	Hafif async HTTP. Varsayılan. Çoğu sitede çalışır.	hayır
curl	curl_cffi ile Chrome 131 TLS taklit eder. TLS-fingerprint tabanlı filtreleri geçer.	evet
auto	Önce httpx deneyen; 403 veya Cloudflare challenge yanıtında curl ile yeniden deneyen.	evet

Backend'i yapılandırmanın iki yolu:

1. Sunucu genelinde varsayılan --fetch-backend CLI bayrağı aracılığıyla (her fetch_content çağrısına uygulanır):

   # Varsayılan davranış — httpx kullanır
   uvx duckduckgo-mcp-server
   
   # Her fetch için curl'ü zorla ([browser] extra gerekli)
   uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend curl
   
   # Önce httpx dene, 403 / Cloudflare challenge üzerinde curl'e geri düş
   uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend auto
   

2. Çağrı başına geçersiz kılma fetch_content aracındaki backend argümanı aracılığıyla (CLI varsayılanını o tek çağrı için geçersiz kılar). Araç input şemasında backend sunmaktadır, bu nedenle bir MCP istemcisi fetch başına "httpx", "curl" veya "auto" seçebilir.

search aracı her zaman httpx kullanır — DuckDuckGo'nun search endpoint'i taklit gerektirmez.

Varsayılan httpx kalır, böylece taklit gerektirmeyenler ekstra dependency'nin ücretini ödemezler.

Geliştirme

Yerel geliştirme için:

# Bağımlılıkları yükle
uv sync

# MCP Inspector ile çalıştır
mcp dev src/duckduckgo_mcp_server/server.py

# Claude Desktop ile test etmek için yerel olarak yükle
mcp install src/duckduckgo_mcp_server/server.py

# Tüm testleri çalıştır
uv run python -m pytest src/duckduckgo_mcp_server/ -v

# Yalnızca unit test'leri çalıştır
uv run python -m pytest src/duckduckgo_mcp_server/test_server.py -v

# Yalnızca e2e test'lerini çalıştır
uv run python -m pytest src/duckduckgo_mcp_server/test_e2e.py -v

Kullanılabilir Araçlar

1. Arama Aracı

async def search(query: str, max_results: int = 10, region: str = "") -> str

DuckDuckGo'da web araması yapar ve formatlanmış sonuçları döndürür.

Parametreler:

• query: Arama sorgusu dizesi
• max_results: Döndürülecek maksimum sonuç sayısı (varsayılan: 10)
• region: (İsteğe bağlı) Varsayılan bölgeyi geçersiz kılmak için bölge/dil kodu. Yapılandırılmış varsayılan bölgeyi kullanmak için boş bırakın.

Bölge Kodu Örnekleri:

• us-en: Amerika Birleşik Devletleri (İngilizce)
• cn-zh: Çin (Çince)
• jp-ja: Japonya (Japonca)
• de-de: Almanya (Almanca)
• fr-fr: Fransa (Fransızca)
• wt-wt: Belirli bir bölge yok

Döndürür: Başlıklar, URL'ler ve özet içeren arama sonuçlarını içeren formatlanmış dize.

Örnek Kullanım:

• Varsayılan ayarlarla arama yapın: search("python tutorial")
• Belirli bölge ile arama yapın: search("latest news", region="jp-ja") Japonca haberler için

2. İçerik Getirme Aracı

async def fetch_content(
    url: str,
    start_index: int = 0,
    max_length: int = 8000,
    backend: Optional[str] = None,
) -> str

Bir web sayfasından içerik getirir ve analiz eder.

Parametreler:

• url: İçerik getirmek için web sayfası URL'si
• start_index: Okumaya başlamak için karakter ofseti (sayfalandırma için)
• max_length: Döndürülecek maksimum karakter sayısı
• backend: Varsayılan fetch backend'ini geçersiz kılmak için isteğe bağlı çağrı başına ("httpx", "curl" veya "auto"). Atlanırsa, sunucu başlangıcında --fetch-backend ile ayarlanan değeri kullanır.

Döndürür: Web sayfasından temizlenmiş ve formatlanmış metin içeriği.

Özelliklerin Ayrıntıları

Rate Limiting

• Arama: Dakikada 30 istek ile sınırlı
• İçerik Getirme: Dakikada 20 istek ile sınırlı
• Otomatik kuyruk yönetimi ve bekleme süreleri

Sonuç İşleme

• Reklamları ve ilgisiz içeriği kaldırır
• DuckDuckGo yönlendirme URL'lerini temizler
• Sonuçları optimal LLM tüketimi için formatlar
• Uzun içeriği uygun şekilde keser

İçerik Güvenliği

• SafeSearch Filtrelemesi: Sunucu başlangıcında DDG_SAFE_SEARCH ortam değişkeni aracılığıyla yapılandırılır

  • Yöneticiler tarafından kontrol edilir, AI asistanlar tarafından değiştirilemez
  • Seçilen seviye temelinde uygunsuz içeriği filtreler
  • DuckDuckGo'nun resmi kp parametresini kullanır

• Bölge Yerelleştirmesi:

  • Varsayılan bölge DDG_REGION ortam değişkeni aracılığıyla ayarlanır
  • AI asistanlar tarafından arama başına geçersiz kılınabilir
  • Belirli coğrafik bölgeler için sonuç ilgisini iyileştirir

Hata Yönetimi

• Kapsamlı hata yakalaması ve raporlaması
• MCP bağlamı aracılığıyla ayrıntılı loglama
• Rate limitler veya zaman aşımlarında sorunsuz bozunma

Katkıda Bulunma

İssues ve pull request'ler memnuniyetle karşılanır! Potansiyel iyileştirmeler için bazı alanlar:

• Geliştirilmiş içerik analiz seçenekleri
• Sık erişilen içerik için önbelleğe alma katmanı
• Ek rate limiting stratejileri

Lisans

Bu proje MIT Lisansı altında lisanslanmıştır.

Star Geçmişi