DuckDuckGo MCP

Servidor MCP que proporciona búsqueda web de DuckDuckGo y extracción del contenido de páginas web. Utiliza el endpoint HTML de DuckDuckGo sin necesidad de clave API, y devuelve los resultados de búsqueda y el contenido de página depurado en un formato que el LLM puede consumir directamente.

Este repositorio es una versión bifurcada y modificada de nickclyde/duckduckgo-mcp-server para su distribución en Goover MCP Hub. El original solo aceptaba la configuración de transporte mediante argumentos CLI, y en el despliegue en contenedores había problemas con la validación del encabezado Host (421) y con las respuestas de streaming SSE. En este repositorio se ha añadido la configuración basada en variables de entorno y se han corregido cuatro problemas que bloqueaban el despliegue.

Información básica

Related MCP server: DuckDuckGo MCP Server

Introducción

English

DuckDuckGo MCP provides web search and webpage content extraction without requiring any API key. It scrapes DuckDuckGo's HTML endpoint and returns results formatted for LLM consumption, along with a fetch tool that strips navigation, headers, footers, scripts, and styles to return clean readable text with pagination support. Built-in sliding-window rate limiting protects both tools. SafeSearch level and default region are fixed at server startup by the operator and cannot be changed by an AI assistant. An optional browser backend uses curl_cffi's Chrome TLS impersonation to pass fingerprint-based bot filters. Outbound fetches are guarded against SSRF by default.

한글

DuckDuckGo MCP es un MCP que proporciona búsqueda web y extracción del contenido de páginas web sin necesidad de clave API. Hace scraping del endpoint HTML de DuckDuckGo y devuelve los resultados en un formato que el LLM puede usar directamente; la herramienta de extracción de contenido elimina navegación, encabezados, pies de página, scripts y estilos, y devuelve texto depurado con paginación. Ambas herramientas tienen un límite de tasa de ventana deslizante. El nivel de SafeSearch y la región predeterminada los fija el operador al iniciar el servidor y el asistente de IA no puede cambiarlos. El backend de navegador opcional utiliza la suplantación de huella TLS de Chrome de curl_cffi para superar los filtros de bots. El acceso a URL externas tiene protección SSRF aplicada por defecto.

Herramientas proporcionadas (2)

Es un MCP puramente basado en herramientas, sin prompts ni recursos.

region se puede especificar por llamada como us-en, cn-zh, jp-ja, de-de, fr-fr, wt-wt, etc. Si se deja vacío, se usa el valor predeterminado del servidor.

Protección SSRF: fetch_content rechaza por defecto las URL que se resuelven a direcciones loopback, privadas (RFC1918), link-local (incluida la metadatos de nube 169.254.169.254), reservadas, multicast o no especificadas, y revalida en cada salto de redirección. Solo permite http/https. En despliegues de confianza que necesiten acceso a hosts internos, se puede desactivar con DDG_ALLOW_PRIVATE_URLS=1. Consulte SECURITY.md para más detalles.

Cambios respecto al original

1. La configuración de transporte no se podía recibir mediante variables de entorno

El original solo aceptaba --transport / --host / --port como argumentos CLI (lo que se leía con os.getenv() era solo la serie DDG_*). No se podía iniciar en entornos como Rancher donde es difícil introducir Arguments de contenedor.

Se han añadido las variables de entorno TRANSPORT / HOST / PORT como respaldo. La razón de que no tengan el prefijo DDG_ es la compatibilidad con la implementación anterior en Node.js que ocupaba este lugar.

Las env se interpretan después de parse_args(), no como default= de argparse. Esto es para conservar la protección del original de "si se dan host/port pero el transporte es stdio, salir". Si se pusiera default=os.getenv("HOST"), la ejecución de stdio moriría inmediatamente con solo tener HOST presente en el entorno.

Además, argparse no valida los valores default con choices, y la rama de transporte del original no tenía else. Por eso, si llegaba un error tipográfico como TRANSPORT=http, terminaba con exit 0 sin ningún log, dificultando el diagnóstico. Se han añadido validación explícita y una línea de defensa else.

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

TRANSPORT también acepta valores múltiples separados por comas (sse,streamable-http).

2. Al activar la lista de permitidos de Host, localhost quedaba bloqueado

El problema de que en el despliegue en contenedores las peticiones de dominios externos fueran rechazadas con 421 Misdirected Request: Invalid Host header se resuelve con DDG_ALLOWED_HOSTS, que ya existía en el original.

El problema era lo siguiente. Al pasar un TransportSecuritySettings explícito a FastMCP, se sobrescriben por completo los valores predeterminados de localhost del SDK (127.0.0.1:*, localhost:*, [::1]:*). Así, en el momento de añadir el host del proxy a la lista de permitidos, todo el acceso local quedaba bloqueado y el healthcheck de Docker o las sondas locales morían silenciosamente.

Se ha modificado para fusionar los patrones de localhost. De paso, también se ha resuelto el problema de que al configurar solo DDG_ALLOWED_ORIGINS, allowed_hosts quedaba como lista vacía y todos los Host recibían 421.

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   (차단 유지)

La coincidencia de Host del SDK solo maneja coincidencia exacta o comodín de puerto con :* al final. Poner * en la barra no significa "permitir todos los hosts"; solo coincide cuando el encabezado Host es literalmente *. Si necesita permitir todo, use DDG_DISABLE_DNS_REBINDING_PROTECTION=1.

3. El cliente HTTP bloqueante no podía leer respuestas SSE

El Hub llama con HttpURLConnection bloqueante, y como la respuesta POST de streamable-http es un flujo SSE, se producían dos síntomas.

1. {"content":[{"type":"text","text":""}],"isError":false} — solo leía el primer chunk SSE (notificación intermedia) y lo malinterpretaba como fin del flujo

2. java.net.SocketException: Unexpected end of file from server — fallo al analizar chunked/SSE

Se han añadido dos interruptores independientes, y ambos están desactivados por defecto.

• DDG_JSON_RESPONSE=1 — devuelve la respuesta POST como un único cuerpo application/json sin tramas SSE

• DDG_DISABLE_PROGRESS_NOTIFICATIONS=1 — envía ctx.info/ctx.error a los logs del servidor en lugar de a la comunicación MCP

Las mediciones reales muestran que solo suprimir las notificaciones no resuelve el síntoma 2. Porque solo se reduce el número de eventos, pero las tramas SSE en sí permanecen.

json_response debe configurarse antes de la llamada a mcp.streamable_http_app() — porque FastMCP crea y cachea el gestor de sesiones en la primera llamada.

Aunque se supriman, los mensajes quedan en los logs del servidor, y el contenido del error también está en el valor de retorno de cada herramienta, por lo que el cliente no pierde el fallo.

4. Faltaba curl_cffi en la imagen Docker

El Dockerfile original solo ejecutaba pip install ., omitiendo el extra [browser]. Pero como el valor predeterminado del backend de búsqueda es auto, si no había curl_cffi, el fallback no funcionaba ante el bloqueo por huella TLS de DuckDuckGo (HTTP 202/403) y solo devolvía un mensaje informativo. Era la causa del síntoma de "sin resultados" que se reproducía especialmente con consultas en coreano.

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

Nota — elementos organizados de paso

__version__ en src/duckduckgo_mcp_server/__init__.py estaba codificado como 0.1.1, en desacuerdo con el 0.6.1 de pyproject.toml. Se ha cambiado para que se lea de los metadatos de la distribución instalada, eliminando la doble fuente.

Variables de entorno

Se leen una vez al iniciar; no se aplican por petición.

Transport (nuevo)

Los flags CLI tienen prioridad sobre las variables de entorno.

Comportamiento de búsqueda

Red / seguridad

Compatibilidad de cliente (nuevo)

Métodos de ejecución

stdio (método original, se mantiene igual)

uvx duckduckgo-mcp-server

Configuración de Claude Desktop (~/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 (nuevo, para distribución en Goover MCP Hub)

# 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

Backend de búsqueda (evasión de bloqueo de bots)

El endpoint de búsqueda de DuckDuckGo puede bloquear la huella TLS de httpx y devolver un HTTP 202 vacío (mira el handshake JA3/TLS independientemente del User-Agent). El backend curl lo supera suplantando el handshake de Chrome con curl_cffi.

La búsqueda tiene auto como valor predeterminado, fetch_content tiene httpx como valor predeterminado, y se puede sobrescribir con el argumento backend por llamada.

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

Ya está incluido en la imagen Docker.

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 []

Compilación local y prueba de humo

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"}}}'

La razón de poner las tres formas en DDG_ALLOWED_HOSTS es que no está claro si el cliente añade el puerto al encabezado Host. example.goover.ai y example.goover.ai:33284 son valores diferentes y no coinciden.

Elementos verificados:

• initialize — arranque solo con variables de entorno, respuesta correcta

• tools/list — devuelve correctamente las 2 herramientas search, fetch_content

• tools/call(search) — éxito tanto con consultas en inglés como en coreano, sin 202 incluso en 5 llamadas rápidas consecutivas

• tools/call(fetch_content) — extracción correcta del contenido de una página real

• Sondas con 4 tipos de encabezado Host — host permitido, localhost y 127.0.0.1 devuelven 200; host no registrado devuelve 421

• 4 combinaciones de formato de respuesta — conmutación correcta entre application/json / text/event-stream según la presencia de DDG_JSON_RESPONSE

Desarrollo

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 잡과 동일)

El CI ejecuta pytest en Python 3.10–3.14 con GitHub Actions, y ejecuta ruff check (bloqueante) y pip-audit (no bloqueante).

Características distintivas de este fork

• El original estaba documentado para uso exclusivo con stdio, y la configuración del transporte HTTP solo estaba expuesta en los argumentos CLI, por lo que el arranque en despliegues en contenedores era difícil.

• Se ha eliminado el modo de fallo en el que un valor incorrecto de TRANSPORT terminaba con exit 0 sin ningún log. La causa era que argparse no valida los valores default con choices.

• Se ha corregido el bug en el que la configuración de la lista de permitidos de Host sobrescribía los valores predeterminados de localhost del SDK, bloqueando silenciosamente las sondas locales. Este problema no se manifiesta hasta que se activa la lista de permitidos.

• Se ha confirmado con mediciones reales que la compatibilidad con clientes HTTP bloqueantes no se resuelve suprimiendo notificaciones, sino cambiando el propio formato de respuesta (json_response), y se ofrecen ambos interruptores.

• Al no tener ningún estado local, no se necesita PVC, y al no necesitar autenticación ni claves API, no hay problemas de gestión de credenciales.

• Nota sobre la causa raíz: hasta que el cliente HTTP del Hub se sustituya por una pila que soporte oficialmente el streaming SSE (Spring WebClient, etc.), el mismo problema puede reaparecer cada vez que se conecte otro MCP que envíe notificaciones de progreso. El punto 3 es una solución alternativa del lado del servidor.

Licencia

Sigue la licencia MIT del repositorio original (nickclyde/duckduckgo-mcp-server) (Copyright (c) 2025 Nick Clyde). Antes de redistribuir o usar comercialmente, consulte el archivo LICENSE.