DuckDuckGo Search MCP-Server

👁 PyPI version
👁 PyPI downloads
👁 Python versions

Ein Model Context Protocol (MCP)-Server, der Websuchfunktionen über DuckDuckGo bereitstellt, mit zusätzlichen Funktionen zum Abrufen und Parsen von Inhalten.

Schnellstart

uvx duckduckgo-mcp-server

Related MCP server: Duck Duck MCP

Funktionen

• Websuche: Durchsuche DuckDuckGo mit erweitertem Rate-Limiting und Ergebnisformatierung

• Inhaltsabruf: Abrufen und Parsen von Webseiteninhalten mit intelligenter Textextraktion

• Rate-Limiting: Integrierter Schutz gegen Ratenbegrenzungen sowohl für die Suche als auch für den Inhaltsabruf

• Fehlerbehandlung: Umfassende Fehlerbehandlung und Protokollierung

• LLM-freundliche Ausgabe: Ergebnisse, die speziell für die Verarbeitung durch große Sprachmodelle formatiert sind

Installation

Installation von PyPI mittels uv:

uv pip install duckduckgo-mcp-server

Verwendung

Ausführung mit Claude Desktop

1. Lade Claude Desktop herunter

2. Erstelle oder bearbeite deine Claude Desktop-Konfiguration:

   • Unter macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Unter Windows: %APPDATA%\Claude\claude_desktop_config.json

Füge die folgende Konfiguration hinzu:

Grundkonfiguration (Kein SafeSearch, keine Standardregion):

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

Mit SafeSearch- und Regionskonfiguration:

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

Konfigurationsoptionen:

• DDG_SAFE_SEARCH: SafeSearch-Filterstufe (optional)

  • STRICT: Maximale Inhaltsfilterung (kp=1)

  • MODERATE: Ausgewogene Filterung (kp=-1, Standard, falls nicht angegeben)

  • OFF: Keine Inhaltsfilterung (kp=-2)

• DDG_REGION: Standard-Regions-/Sprachcode (optional, Beispiele unten)

  • us-en: Vereinigte Staaten (Englisch)

  • cn-zh: China (Chinesisch)

  • jp-ja: Japan (Japanisch)

  • wt-wt: Keine spezifische Region

  • Leer lassen für das Standardverhalten von DuckDuckGo

3. Starte Claude Desktop neu

Ausführung mit Claude Code

1. Lade Claude Code herunter

2. Stelle sicher, dass uvenv installiert ist und der uvx-Befehl verfügbar ist

3. Füge den MCP-Server hinzu: claude mcp add ddg-search uvx duckduckgo-mcp-server

Ausführung mit SSE oder Streamable HTTP

Der Server unterstützt alternative Transporte zur Verwendung mit anderen MCP-Clients:

# SSE transport
uvx duckduckgo-mcp-server --transport sse

# Streamable HTTP transport
uvx duckduckgo-mcp-server --transport streamable-http

Der Standardtransport ist stdio, der von Claude Desktop und Claude Code verwendet wird.

Bei der Ausführung mit sse oder streamable-http überschreibe die Standard-Bind-Adresse (127.0.0.1:8000) mit den Flags --host und --port:

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

Fetch-Backend (Umgehung der Bot-Erkennung)

Einige Websites blockieren den Standard-httpx-Client aufgrund seines charakteristischen TLS-Fingerabdrucks, unabhängig vom User-Agent – Cloudflare Bot Management und ähnliche Filter basieren auf dem JA3/TLS-Handshake, nicht auf Headern. Ein optionales Backend, curl (implementiert über curl_cffi), imitiert den TLS-Handshake eines echten Chrome-Browsers und passiert diese Prüfungen.

Installation:

# Default install (httpx only)
uv pip install duckduckgo-mcp-server

# With the optional browser backend
uv pip install "duckduckgo-mcp-server[browser]"

Backend-Optionen:

Zwei Möglichkeiten zur Konfiguration des Backends:

1. Serverweiter Standard über das CLI-Flag --fetch-backend (gilt für jeden fetch_content-Aufruf):

   # Default behavior — uses httpx
   uvx duckduckgo-mcp-server
   
   # Force curl for every fetch (requires the [browser] extra)
   uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend curl
   
   # Try httpx first, fall back to curl on 403 / Cloudflare challenge
   uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend auto

2. Aufruf-spezifische Überschreibung über das Argument backend im fetch_content-Tool (überschreibt den CLI-Standard für diesen einen Aufruf). Das Tool macht backend in seinem Eingabeschema verfügbar, sodass ein MCP-Client für jeden Abruf einzeln zwischen "httpx", "curl" oder "auto" wählen kann.

Das search-Tool verwendet immer httpx – der Such-Endpunkt von DuckDuckGo erfordert keine Impersonierung.

Der Standard bleibt httpx, damit Benutzer, die die Impersonierung nicht benötigen, nicht für die zusätzliche Abhängigkeit bezahlen müssen.

Entwicklung

Für die lokale Entwicklung:

# Install dependencies
uv sync

# Run with the MCP Inspector
mcp dev src/duckduckgo_mcp_server/server.py

# Install locally for testing with Claude Desktop
mcp install src/duckduckgo_mcp_server/server.py

# Run all tests
uv run python -m pytest src/duckduckgo_mcp_server/ -v

# Run only unit tests
uv run python -m pytest src/duckduckgo_mcp_server/test_server.py -v

# Run only e2e tests
uv run python -m pytest src/duckduckgo_mcp_server/test_e2e.py -v

Verfügbare Tools

1. Such-Tool

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

Führt eine Websuche auf DuckDuckGo durch und gibt formatierte Ergebnisse zurück.

Parameter:

• query: Suchbegriff

• max_results: Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 10)

• region: (Optional) Regions-/Sprachcode zum Überschreiben des Standards. Leer lassen, um die konfigurierte Standardregion zu verwenden.

Regionscode-Beispiele:

• us-en: Vereinigte Staaten (Englisch)

• cn-zh: China (Chinesisch)

• jp-ja: Japan (Japanisch)

• de-de: Deutschland (Deutsch)

• fr-fr: Frankreich (Französisch)

• wt-wt: Keine spezifische Region

Rückgabe: Formatierter String mit Suchergebnissen inklusive Titeln, URLs und Snippets.

Beispielverwendung:

• Suche mit Standardeinstellungen: search("python tutorial")

• Suche mit spezifischer Region: search("aktuelle nachrichten", region="de-de") für deutsche Nachrichten

2. Inhaltsabruf-Tool

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

Ruft Inhalte von einer Webseite ab und parst diese.

Parameter:

• url: Die URL der Webseite, von der Inhalte abgerufen werden sollen

• start_index: Zeichen-Offset für den Beginn des Lesens (für Paginierung)

• max_length: Maximale Anzahl der zurückzugebenden Zeichen

• backend: Optionale aufruf-spezifische Überschreibung des Standard-Fetch-Backends ("httpx", "curl" oder "auto"). Wenn weggelassen, wird das verwendet, was beim Serverstart über --fetch-backend festgelegt wurde.

Rückgabe: Bereinigter und formatierter Textinhalt der Webseite.

Funktionen im Detail

Rate-Limiting

• Suche: Begrenzt auf 30 Anfragen pro Minute

• Inhaltsabruf: Begrenzt auf 20 Anfragen pro Minute

• Automatische Warteschlangenverwaltung und Wartezeiten

Ergebnisverarbeitung

• Entfernt Werbung und irrelevante Inhalte

• Bereinigt DuckDuckGo-Weiterleitungs-URLs

• Formatiert Ergebnisse für optimale LLM-Verarbeitung

• Kürzt lange Inhalte angemessen

Inhaltssicherheit

• SafeSearch-Filterung: Konfiguriert beim Serverstart über die Umgebungsvariable DDG_SAFE_SEARCH

  • Wird von Administratoren gesteuert, nicht durch KI-Assistenten änderbar

  • Filtert unangemessene Inhalte basierend auf der gewählten Stufe

  • Verwendet den offiziellen kp-Parameter von DuckDuckGo

• Regionslokalisierung:

  • Standardregion über die Umgebungsvariable DDG_REGION festgelegt

  • Kann pro Suchanfrage von KI-Assistenten überschrieben werden

  • Verbessert die Relevanz der Ergebnisse für bestimmte geografische Regionen

Fehlerbehandlung

• Umfassende Fehlererkennung und -meldung

• Detaillierte Protokollierung über den MCP-Kontext

• Graceful Degradation bei Ratenbegrenzungen oder Timeouts

Mitwirken

Issues und Pull Requests sind willkommen! Einige Bereiche für potenzielle Verbesserungen:

• Erweiterte Optionen für das Parsen von Inhalten

• Caching-Schicht für häufig abgerufene Inhalte

• Zusätzliche Strategien für das Rate-Limiting

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• fetch_contentA
• searchA