DuckDuckGo MCP

Dies ist ein MCP-Server, der DuckDuckGo-Websuche und Extraktion von Webseiteninhalten bereitstellt. Er verwendet den DuckDuckGo-HTML-Endpunkt ohne API-Schlüssel und gibt Suchergebnisse sowie bereinigte Seiteninhalte in einer Form zurück, die LLMs direkt konsumieren können.

Dieses Repository ist eine für den Goover MCP Hub-Einsatz geforkte und modifizierte Version von nickclyde/duckduckgo-mcp-server. Das Original akzeptierte Transporteinstellungen nur über CLI-Argumente und hatte bei Container-Bereitstellungen jeweils Probleme mit der Host-Header-Validierung (421) und SSE-Streaming-Antworten. In diesem Repository wurden umgebungsvariablenbasierte Einstellungen hinzugefügt und vier Bereitstellungsblockaden behoben.

Grundinformationen

Related MCP server: DuckDuckGo MCP Server

Einführung

Englisch

DuckDuckGo MCP bietet Websuche und Extraktion von Webseiteninhalten ohne API-Schlüssel. Es scraped den HTML-Endpunkt von DuckDuckGo und gibt Ergebnisse in einem für LLMs aufbereiteten Format zurück, zusammen mit einem Fetch-Tool, das Navigation, Header, Footer, Skripte und Styles entfernt, um sauberen, lesbaren Text mit Paginierungsunterstützung zurückzugeben. Ein integrierter Rate-Limiter mit gleitendem Fenster schützt beide Tools. SafeSearch-Stufe und Standardregion werden beim Serverstart vom Betreiber festgelegt und können von einem KI-Assistenten nicht geändert werden. Ein optionales Browser-Backend verwendet curl_cffis Chrome-TLS-Imitation, um fingerabdruckbasierte Bot-Filter zu umgehen. Ausgehende Abrufe sind standardmäßig gegen SSRF geschützt.

Koreanisch

DuckDuckGo MCP ist ein MCP, das Websuche und Extraktion von Webseiteninhalten ohne API-Schlüssel bereitstellt. Es scraped den DuckDuckGo-HTML-Endpunkt und gibt Ergebnisse in einer Form zurück, die LLMs direkt verwenden können. Das Inhalts-Extraktionstool entfernt Navigation, Header, Footer, Skripte und Styles und liefert bereinigten Text mit Paginierung. Beide Tools unterliegen einem Rate-Limit mit gleitendem Fenster. SafeSearch-Stufe und Standardregion werden vom Betreiber beim Serverstart festgelegt und können von einem KI-Assistenten nicht geändert werden. Das optionale Browser-Backend umgeht Bot-Filter durch Chrome-TLS-Fingerabdruck-Imitation von curl_cffi. Externe URL-Zugriffe sind standardmäßig durch einen SSRF-Schutz abgesichert.

Bereitgestellte Tools (2)

Es handelt sich um ein reines Tool-basiertes MCP ohne Prompts/Ressourcen.

region kann pro Aufruf als us-en, cn-zh, jp-ja, de-de, fr-fr, wt-wt usw. angegeben werden; wenn leer, wird der Serverstandardwert verwendet.

SSRF-Schutz: fetch_content lehnt standardmäßig URLs ab, die zu Loopback-, privaten (RFC1918), Link-Local-Adressen (einschließlich 169.254.169.254-Cloud-Metadaten), Reserved-, Multicast- oder nicht spezifizierten Adressen aufgelöst werden, und validiert bei jedem Redirect-Hop erneut. Nur http/https sind erlaubt. In vertrauenswürdigen Bereitstellungen, die internen Host-Zugriff benötigen, kann dies mit DDG_ALLOW_PRIVATE_URLS=1 deaktiviert werden. Weitere Details finden Sie in SECURITY.md.

Änderungen gegenüber dem Original

1. Transporteinstellungen konnten nicht über Umgebungsvariablen gesetzt werden

Das Original akzeptierte --transport / --host / --port nur als CLI-Argumente (per os.getenv() wurden nur DDG_*-Variablen gelesen). In Umgebungen wie Rancher, in denen Container-Arguments schwer zu setzen sind, war ein Start nicht möglich.

Die Umgebungsvariablen TRANSPORT / HOST / PORT wurden als Fallback hinzugefügt. Der Grund für das Fehlen des DDG_-Präfixes ist die Kompatibilität mit der früheren Node.js-Implementierung an dieser Stelle.

Die env-Variablen werden nicht als default= von argparse, sondern nach parse_args() ausgewertet. Dies dient dazu, die Original-Schutzlogik "wenn host/port angegeben, aber transport stdio ist, beenden" beizubehalten. Würde man default=os.getenv("HOST") verwenden, würde die stdio-Ausführung sofort abbrechen, sobald HOST in der Umgebung vorhanden ist.

Außerdem validiert argparse default-Werte nicht gegen choices, und der Transport-Zweig des Originals hatte kein else. Dadurch endete ein Tippfehler wie TRANSPORT=http ohne jegliche Logausgabe mit Exit 0, was die Ursachenfindung erschwerte. Es wurden explizite Validierung und eine else-Absicherung hinzugefügt.

$ TRANSPORT=http python -m duckduckgo_mcp_server.server
error: Invalid TRANSPORT value(s) ['http']; choose from stdio, sse, streamable-http

TRANSPORT akzeptiert auch kommagetrennte Mehrfachwerte (sse,streamable-http).

2. Bei aktivierter Host-Allowlist wurde localhost blockiert

Das Problem, dass bei Container-Bereitstellungen Anfragen von externen Domains mit 421 Misdirected Request: Invalid Host header abgelehnt wurden, wird durch die bereits im Original vorhandene DDG_ALLOWED_HOSTS gelöst.

Das Problem war der nächste Schritt: Wenn man FastMCP explizite TransportSecuritySettings übergibt, werden die localhost-Standardwerte des SDK (127.0.0.1:*, localhost:*, [::1]:*) vollständig überschrieben. Sobald man also einen Proxy-Host in die Allowlist aufnimmt, werden alle lokalen Zugriffe blockiert, und Docker-Healthchecks oder lokale Probes sterben still.

Es wurde korrigiert, sodass localhost-Muster zusammengeführt werden. Nebenbei wurde auch das Problem behoben, dass bei alleiniger Angabe von DDG_ALLOWED_ORIGINS die allowed_hosts eine leere Liste wurde und alle Hosts mit 421 abgelehnt wurden.

DDG_ALLOWED_HOSTS=example.goover.ai:33284 로 기동 시

Host: example.goover.ai:33284 -> 200
Host: localhost:8000          -> 200   (수정 전 421)
Host: 127.0.0.1:8000          -> 200   (수정 전 421)
Host: attacker.example.com    -> 421   (차단 유지)

Die Host-Zuordnung des SDK unterstützt nur exakte Übereinstimmung oder Port-Wildcards mit angehängtem :*. Selbst wenn man * in die Liste setzt, bedeutet das nicht "alle Hosts erlauben" — es wird nur dann gematcht, wenn der Host-Header wörtlich * ist. Für vollständige Freigabe verwenden Sie DDG_DISABLE_DNS_REBINDING_PROTECTION=1.

3. Blockierender HTTP-Client konnte SSE-Antworten nicht lesen

Der Hub ruft mit blockierendem HttpURLConnection auf, aber da die POST-Antwort von streamable-http ein SSE-Stream ist, traten zwei Symptome auf:

1. {"content":[{"type":"text","text":""}],"isError":false} — nur das erste SSE-Chunk (Zwischen-Notification) wurde gelesen und fälschlich als Stream-Ende interpretiert

2. java.net.SocketException: Unexpected end of file from server — Fehler beim Parsen von chunked/SSE

Es wurden zwei unabhängige Schalter hinzugefügt, beide standardmäßig aus:

• DDG_JSON_RESPONSE=1 — gibt die POST-Antwort als einzelnen application/json-Body ohne SSE-Frames zurück

• DDG_DISABLE_PROGRESS_NOTIFICATIONS=1 — sendet ctx.info/ctx.error anstelle der MCP-Kommunikation an die Server-Logs

Messungen zeigen, dass die alleinige Unterdrückung von Notifications Symptom 2 nicht löst. Die Anzahl der Events wird nur reduziert, die SSE-Frames selbst bleiben erhalten.

json_response muss vor dem Aufruf von mcp.streamable_http_app() gesetzt werden — da FastMCP beim ersten Aufruf einen Session-Manager erstellt und cached.

Auch bei Unterdrückung bleiben die Nachrichten in den Server-Logs erhalten, und Fehlerinhalte sind auch in den Rückgabewerten jedes Tools enthalten, sodass der Client Fehler nicht übersieht.

4. curl_cffi fehlte im Docker-Image

Das Original-Dockerfile führte nur pip install . aus und ließ das [browser]-Extra aus. Da der Standardwert des Such-Backends jedoch auto ist, konnte der Fallback bei TLS-Fingerabdruck-Blockierung durch DuckDuckGo (HTTP 202/403) ohne curl_cffi nicht greifen — es wurde nur eine Hinweismeldung zurückgegeben. Dies war insbesondere die Ursache des bei koreanischen Suchanfragen reproduzierbaren Symptoms "keine Ergebnisse".

RUN pip install --no-cache-dir --upgrade pip \
    && pip install --no-cache-dir ".[browser]"

Hinweis — zusätzlich bereinigter Punkt

Die __version__ in src/duckduckgo_mcp_server/__init__.py war hartkodiert auf 0.1.1 und wich damit von 0.6.1 in pyproject.toml ab. Es wurde geändert, sodass sie aus den Metadaten der installierten Distribution gelesen wird, wodurch die doppelte Quelle entfiel.

Umgebungsvariablen

Wird beim Start einmal gelesen, nicht pro Anfrage berücksichtigt.

Transport (neu)

CLI-Flags haben Vorrang vor Umgebungsvariablen.

Suchverhalten

Netzwerk / Sicherheit

Client-Kompatibilität (neu)

Ausführungsmethoden

stdio (Originalmethode, unverändert beibehalten)

uvx duckduckgo-mcp-server

Claude-Desktop-Konfiguration (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Claude Code:

claude mcp add ddg-search uvx duckduckgo-mcp-server

streamable HTTP (neu, für Goover-MCP-Hub-Bereitstellung)

# CLI 인자로
uvx duckduckgo-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

# 환경변수만으로 (Arguments를 넣기 어려운 환경)
TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 uvx duckduckgo-mcp-server

Such-Backend (Bot-Blockierungs-Umgehung)

Der Such-Endpunkt von DuckDuckGo kann den TLS-Fingerabdruck von httpx blockieren und eine leere HTTP-202-Antwort zurückgeben (er prüft JA3/TLS-Handshake unabhängig vom User-Agent). Das curl-Backend umgeht dies, indem es mit curl_cffi den Chrome-Handshake imitiert.

Die Suche hat standardmäßig auto, fetch_content standardmäßig httpx; beides kann pro Aufruf mit dem backend-Argument überschrieben werden.

uv pip install "duckduckgo-mcp-server[browser]"

Im Docker-Image ist es bereits enthalten.

Docker

Dockerfile

FROM python:3.13-slim

WORKDIR /app

COPY . /app

RUN pip install --no-cache-dir --upgrade pip \
    && pip install --no-cache-dir ".[browser]"

ENTRYPOINT ["python", "-m", "duckduckgo_mcp_server.server"]
CMD []

Lokaler Build und Smoke-Test

docker build --no-cache --platform linux/amd64 -t duckduckgo-mcp:latest .

docker run -d --name duckduckgo-mcp-test -p 8069:8000 \
  -e TRANSPORT=streamable-http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e DDG_REGION=wt-wt \
  -e DDG_SAFE_SEARCH=OFF \
  -e DDG_ALLOWED_HOSTS=example.goover.ai:33284,example.goover.ai:*,example.goover.ai \
  -e DDG_JSON_RESPONSE=1 \
  -e DDG_DISABLE_PROGRESS_NOTIFICATIONS=true \
  duckduckgo-mcp:latest

curl -s -X POST http://localhost:8069/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Der Grund, warum alle drei Formen in DDG_ALLOWED_HOSTS aufgenommen wurden, ist, dass nicht sicher ist, ob der Client einen Port an den Host-Header anhängt. example.goover.ai und example.goover.ai:33284 sind unterschiedliche Werte und matchen nicht.

Verifizierte Punkte:

• initialize — Start nur mit Umgebungsvariablen, normale Antwort

• tools/list — search, fetch_content werden korrekt zurückgegeben (2 Tools)

• tools/call(search) — Erfolg bei englischen und koreanischen Suchanfragen, kein 202 auch bei 5 schnellen Aufrufen in Folge

• tools/call(fetch_content) — Erfolgreiche Extraktion tatsächlicher Seiteninhalte

• Host-Header-Probes (4 Typen) — erlaubte Hosts, localhost, 127.0.0.1 liefern 200, nicht registrierte Hosts liefern 421

• Antwortformat-Kombinationen (4) — korrekter Wechsel zwischen application/json / text/event-stream je nach DDG_JSON_RESPONSE

Entwicklung

uv sync                                                    # 의존성 설치
uv run duckduckgo-mcp-server                               # 실행
mcp dev src/duckduckgo_mcp_server/server.py                # MCP Inspector

uv run python -m pytest src/duckduckgo_mcp_server/ -v      # 전체 테스트 (106개)
uv run ruff check .                                        # 린트 (CI quality 잡과 동일)

CI führt mit GitHub Actions pytest auf Python 3.10–3.14 aus und führt ruff check (blockierend) und pip-audit (nicht blockierend) aus.

Besonderheiten dieses Forks

• Das Original war für reine stdio-Nutzung dokumentiert; HTTP-Transporteinstellungen waren nur über CLI-Argumente verfügbar, was den Start bei Container-Bereitstellungen erschwerte.

• Der Fehlermodus, bei dem ein ungültiger TRANSPORT-Wert ohne jegliche Logausgabe mit Exit 0 endete, wurde entfernt. Ursache war, dass argparse default-Werte nicht gegen choices validiert.

• Der Bug, bei dem die Host-Allowlist die localhost-Standardwerte des SDK überschrieb und lokale Probes still blockierte, wurde behoben. Dieses Problem tritt erst auf, wenn die Allowlist aktiviert wird.

• Für die Kompatibilität mit blockierenden HTTP-Clients wurde messtechnisch bestätigt, dass nicht die Unterdrückung von Notifications, sondern die Änderung des Antwortformats selbst (json_response) die Lösung ist; beide Schalter werden bereitgestellt.

• Es gibt keinerlei lokalen Zustand, daher ist kein PVC erforderlich; auch keine Authentifizierung oder API-Schlüssel, daher keine Credential-Management-Probleme.

• Hinweis zur Grundursache: Bis der HTTP-Client des Hubs auf einen Stack mit offizieller SSE-Streaming-Unterstützung (z. B. Spring WebClient) umgestellt wird, kann dasselbe Problem bei jedem anderen MCP mit Progress-Notifications erneut auftreten. Punkt 3 ist eine serverseitige Umgehung.

Lizenz

Es gilt die MIT-Lizenz des Original-Repositorys (nickclyde/duckduckgo-mcp-server) (Copyright (c) 2025 Nick Clyde). Bitte prüfen Sie vor Weiterverbreitung oder kommerzieller Nutzung die Datei LICENSE.