Servidor MCP de búsqueda de DuckDuckGo

Un servidor del 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 el análisis de contenido.

Inicio rápido

uvx duckduckgo-mcp-server

Related MCP server: duck-poacher-mcp

Características

• Búsqueda web: Busca en DuckDuckGo con limitación de tasa avanzada y formato de resultados

• Obtención de contenido: Recupera y analiza el contenido de páginas web con extracción de texto inteligente

• Limitación de tasa: Protección integrada contra límites de tasa tanto para búsquedas como para la obtención de contenido

• Gestión de errores: Gestión integral de errores y registro de eventos

• Salida compatible con LLM: Resultados formateados específicamente para el consumo por parte 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 de contenido máximo (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 a continuación)

  • 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

3. Reinicia Claude Desktop

Ejecución con Claude Code

1. Descarga Claude Code

2. Asegúrate de que uvenv esté instalado y que 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 HTTP transmitible

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.

Al ejecutar con sse o streamable-http, sobrescribe 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

Backend de obtención (evitando la detección de bots)

Algunos sitios bloquean el cliente httpx predeterminado debido a su huella digital TLS distintiva, independientemente del User-Agent; la gestión de bots de Cloudflare y filtros similares se basan en el handshake JA3/TLS, no en los encabezados. Un backend opcional, curl (implementado a través de curl_cffi), suplanta el handshake TLS de un navegador Chrome real y supera esas comprobaciones.

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:

Dos formas de configurar el backend:

1. Predeterminado para todo el 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. Sobrescritura por llamada mediante el argumento backend en la herramienta fetch_content (sobrescribe el valor predeterminado de la 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.

La herramienta search siempre usa httpx: el endpoint de búsqueda de DuckDuckGo no requiere suplantación.

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

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 sobrescribir 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, URLs y fragmentos.

Ejemplo de uso:

• Búsqueda con configuración predeterminada: search("python tutorial")

• Búsqueda 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 empezar a leer (para paginación)

• max_length: Número máximo de caracteres a devolver

• backend: Sobrescritura opcional por llamada del backend de obtención predeterminado ("httpx", "curl" o "auto"). Cuando se omite, usa lo que se haya configurado mediante --fetch-backend al iniciar el servidor.

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

Detalles de las características

Limitación de tasa

• 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 URLs de redirección de DuckDuckGo

• Formatea los resultados para un consumo óptimo por parte de LLM

• Trunca el contenido largo de forma adecuada

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

  • Utiliza 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 sobrescrita por solicitud de búsqueda por los asistentes de IA

  • Mejora la relevancia de los resultados para regiones geográficas específicas

Gestión de errores

• Captura y notificación integral de errores

• Registro detallado a través del contexto MCP

• Degradación elegante ante límites de tasa o tiempos de espera

Contribución

¡Las propuestas y solicitudes de extracción (pull requests) son bienvenidas! Algunas áreas para posibles mejoras:

• Opciones mejoradas de análisis de contenido

• Capa de caché para contenido accedido frecuentemente

• Estrategias adicionales de limitación de tasa

Licencia

Este proyecto está bajo la Licencia MIT.