DuckDuckGo Search

Realiza búsquedas web utilizando la API de DuckDuckGo, con funciones para obtener y analizar contenido.

GitHub
1.4k
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Búsqueda DuckDuckGo

PyPI version PyPI downloads Python versions

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona capacidades de búsqueda web a través de DuckDuckGo, con funciones adicionales para la obtención y análisis de contenido.

Inicio Rápido

uvx duckduckgo-mcp-server

Características

  • Búsqueda Web: Busca en DuckDuckGo con limitación de velocidad avanzada y formato de resultados
  • Obtención de Contenido: Recupera y analiza contenido de páginas web con extracción inteligente de texto
  • Limitación de Velocidad: Protección integrada contra límites de velocidad tanto para búsquedas como para obtención de contenido
  • Manejo de Errores: Manejo y registro de errores exhaustivo
  • Salida Amigable para LLM: Resultados formateados específicamente para el consumo de modelos de lenguaje grandes

Instalación

Instala desde PyPI usando uv:

uv pip install duckduckgo-mcp-server

Uso

Ejecución con Claude Desktop

  1. Descarga Claude Desktop
  2. Crea o edita tu configuración de Claude Desktop:
    • En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • En Windows: %APPDATA%\Claude\claude_desktop_config.json

Añade la siguiente configuración:

Configuración Básica (Sin SafeSearch, Sin Región Predeterminada):

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

Con Configuración de SafeSearch y Región:

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

Opciones de Configuración:

  • DDG_SAFE_SEARCH: Nivel de filtrado de SafeSearch (opcional)
    • STRICT: Filtrado máximo de contenido (kp=1)
    • MODERATE: Filtrado equilibrado (kp=-1, predeterminado si no se especifica)
    • OFF: Sin filtrado de contenido (kp=-2)
  • DDG_REGION: Código de región/idioma predeterminado (opcional, ejemplos abajo)
    • us-en: Estados Unidos (Inglés)
    • cn-zh: China (Chino)
    • jp-ja: Japón (Japonés)
    • wt-wt: Sin región específica
    • Déjalo vacío para el comportamiento predeterminado de DuckDuckGo
  • DDG_CA_CERTS: Ruta a un paquete de CA PEM utilizado para verificar certificados TLS en solicitudes salientes (opcional). Necesario detrás de proxies que interceptan TLS — consulta Ejecución detrás de un proxy que intercepta TLS.
  1. Reinicia Claude Desktop

Ejecución con Claude Code

  1. Descarga Claude Code
  2. Asegúrate de que uvenv esté instalado y el comando uvx esté disponible
  3. Añade el servidor MCP: claude mcp add ddg-search uvx duckduckgo-mcp-server

Ejecución con SSE o Streamable HTTP

El servidor admite transportes alternativos para su uso con otros clientes MCP:

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

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

El transporte predeterminado es stdio, que es utilizado por Claude Desktop y Claude Code.

Cuando se ejecuta con sse o streamable-http, anula la dirección de enlace predeterminada (127.0.0.1:8000) con las banderas --host y --port:

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

Ejecución detrás de un proxy inverso o en Docker

FastMCP habilita la protección contra el reenlace de DNS para los transportes HTTP y, de forma predeterminada, solo acepta encabezados Host/Origin para localhost. Detrás de un proxy inverso o en un contenedor, el encabezado Host del cliente no coincidirá, por lo que las solicitudes fallarán con 421 Misdirected Request.

Soluciona esto permitiendo explícitamente los hosts y orígenes que los clientes realmente usan (preferible a deshabilitar la protección). Los valores admiten host, host:port y puerto comodín host:*:

uvx duckduckgo-mcp-server --transport streamable-http --host 0.0.0.0 --port 7070 \
  --allowed-hosts ddg-mcp.example.com "ddg-mcp.example.com:*" \
  --allowed-origins "https://ddg-mcp.example.com"

También están disponibles variables de entorno equivalentes (separadas por comas): DDG_ALLOWED_HOSTS, DDG_ALLOWED_ORIGINS.

Como último recurso, puedes desactivar la verificación por completo con --disable-dns-rebinding-protection (o DDG_DISABLE_DNS_REBINDING_PROTECTION=1). Prefiere una lista de permitidos: deshabilitar la protección elimina una defensa contra ataques de reenlace de DNS. Cuando no se configura nada, se conserva el valor predeterminado seguro de solo localhost.

Ejecución detrás de un proxy que intercepta TLS

Los proxies corporativos que vuelven a firmar el tráfico HTTPS con su propia CA (a través de HTTPS_PROXY) hacen que las solicitudes salientes fallen con errores de verificación de certificados, porque los clientes HTTP no confían en la CA autofirmada del proxy (y httpx ya no lee la variable de entorno SSL_CERT_FILE). Apunta el servidor al paquete de CA de tu proxy:

uvx duckduckgo-mcp-server --ca-certs /path/to/proxy-ca.pem

O establece DDG_CA_CERTS=/path/to/proxy-ca.pem. El paquete es utilizado tanto por la herramienta search como por la fetch_content, en los backends httpx y curl por igual.

Como último recurso, --no-ssl-verify (o DDG_SSL_VERIFY=0) deshabilita la verificación de certificados por completo. Esto expone el tráfico a la interceptación por parte de cualquier persona en la ruta de red — prefiere --ca-certs.

Backends (evadiendo la detección de bots)

Algunos sitios — y, recientemente, el propio endpoint de búsqueda de DuckDuckGo (html.duckduckgo.com) — bloquean el cliente httpx predeterminado debido a su distintiva huella TLS, independientemente del User-Agent. Cloudflare Bot Management y filtros similares se basan en el protocolo de enlace JA3/TLS, no en los encabezados, por lo que html.duckduckgo.com puede responder a httpx con una página HTTP 202 vacía (devolviendo silenciosamente "sin resultados"). Un backend opcional, curl (implementado a través de curl_cffi), suplanta el protocolo de enlace TLS de un navegador Chrome real y supera esas verificaciones.

Tanto la herramienta search como la herramienta fetch_content admiten estos backends.

Instalación:

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

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

Opciones de backend:

ValorComportamientoNecesita [browser]
httpxHTTP asíncrono ligero. Predeterminado. Funciona en la mayoría de los sitios.no
curlUsa curl_cffi con suplantación de TLS de Chrome 131. Supera los filtros basados en huellas TLS.sí
autoIntenta httpx primero; ante un 403 o una respuesta de desafío de Cloudflare, reintenta con curl.sí

Dos formas de configurar el backend:

  1. Valor predeterminado a nivel de servidor mediante la bandera CLI --fetch-backend (se aplica a cada llamada de fetch_content):

    # 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. Anulación por llamada mediante el argumento backend en la herramienta fetch_content (anula el valor predeterminado de CLI para esa única llamada). La herramienta expone backend en su esquema de entrada, por lo que un cliente MCP puede elegir "httpx", "curl" o "auto" en cada obtención individual.

Para fetch_content, el valor predeterminado sigue siendo httpx para que los usuarios que no necesitan la suplantación no paguen por la dependencia adicional.

Backend de búsqueda

Debido a que el endpoint de búsqueda de DuckDuckGo ahora bloquea por huella a httpx simple, la herramienta search usa por defecto auto: intenta httpx primero y recurre a curl cuando detecta un bloqueo (HTTP 202/403). La alternativa solo funciona si el extra [browser] está instalado; de lo contrario, la búsqueda devuelve un mensaje indicando que lo instales.

Configura el backend de búsqueda con la bandera CLI --search-backend o la variable de entorno DDG_SEARCH_BACKEND (auto (predeterminado) / httpx / curl):

# Recommended: install the browser extra so the auto fallback can impersonate Chrome
uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server

# Force curl for every search
uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --search-backend curl

# Opt out of the fallback (legacy behavior — may return no results while blocked)
uvx duckduckgo-mcp-server --search-backend httpx

Desarrollo

Para desarrollo local:

# 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

Herramientas Disponibles

1. Herramienta de Búsqueda

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

Realiza una búsqueda web en DuckDuckGo y devuelve resultados formateados.

Parámetros:

  • query: Cadena de consulta de búsqueda
  • max_results: Número máximo de resultados a devolver (predeterminado: 10)
  • region: (Opcional) Código de región/idioma para anular el predeterminado. Déjalo vacío para usar la región predeterminada configurada.

Ejemplos de Códigos de Región:

  • us-en: Estados Unidos (Inglés)
  • cn-zh: China (Chino)
  • jp-ja: Japón (Japonés)
  • de-de: Alemania (Alemán)
  • fr-fr: Francia (Francés)
  • wt-wt: Sin región específica

Devuelve: Cadena formateada que contiene los resultados de búsqueda con títulos, URL y fragmentos.

Ejemplo de Uso:

  • Buscar con configuración predeterminada: search("python tutorial")
  • Buscar con región específica: search("latest news", region="jp-ja") para noticias en japonés

2. Herramienta de Obtención de Contenido

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

Obtiene y analiza el contenido de una página web.

Parámetros:

  • url: La URL de la página web de la que obtener contenido
  • start_index: Desplazamiento de caracteres para comenzar a leer (para paginación)
  • max_length: Número máximo de caracteres a devolver
  • backend: Anulación opcional por llamada del backend de obtención predeterminado ("httpx", "curl" o "auto"). Cuando se omite, usa lo que se haya establecido mediante --fetch-backend al iniciar el servidor.

Devuelve: Contenido de texto limpio y formateado de la página web.

Protección SSRF: De forma predeterminada, fetch_content rechaza URL que se resuelven a direcciones de bucle local, privadas (RFC1918), de enlace local (incluido el endpoint de metadatos de la nube 169.254.169.254), reservadas, de multidifusión o no especificadas, y revalida cada salto de redirección. Solo se permiten URL http/https. Para implementaciones locales de confianza que necesiten obtener hosts internos, deshabilita la protección con DDG_ALLOW_PRIVATE_URLS=1 o --allow-private-urls. Consulta SECURITY.md para más detalles.

Características en Detalle

Limitación de Velocidad

  • Búsqueda: Limitada a 30 solicitudes por minuto
  • Obtención de Contenido: Limitada a 20 solicitudes por minuto
  • Gestión automática de colas y tiempos de espera

Procesamiento de Resultados

  • Elimina anuncios y contenido irrelevante
  • Limpia las URL de redirección de DuckDuckGo
  • Formatea los resultados para un consumo óptimo por parte de LLM
  • Trunca el contenido largo de manera apropiada

Seguridad del Contenido

  • Filtrado SafeSearch: Configurado al iniciar el servidor mediante la variable de entorno DDG_SAFE_SEARCH

    • Controlado por administradores, no modificable por asistentes de IA
    • Filtra contenido inapropiado según el nivel seleccionado
    • Usa el parámetro oficial kp de DuckDuckGo

  • Localización por Región:

    • Región predeterminada establecida mediante la variable de entorno DDG_REGION
    • Puede ser anulada por solicitud de búsqueda por los asistentes de IA
    • Mejora la relevancia de los resultados para regiones geográficas específicas

Manejo de Errores

  • Captura y reporte exhaustivo de errores
  • Registro detallado a través del contexto MCP
  • Degradación gradual ante límites de velocidad o tiempos de espera

Contribuciones

¡Las incidencias y solicitudes de extracción son bienvenidas! Algunas áreas de mejora potencial:

  • Opciones mejoradas de análisis de contenido
  • Capa de caché para contenido de acceso frecuente
  • Estrategias adicionales de limitación de velocidad

Licencia

Este proyecto está licenciado bajo la Licencia MIT.

Historial de Estrellas

Star History Chart