HasData DuckDuckGo MCP Server

Servidor MCP de DuckDuckGo

Un servidor de Protocolo de Contexto de Modelo (MCP) alojado que brinda a Claude, Cursor, Windsurf y cualquier otro cliente MCP resultados de búsqueda de DuckDuckGo como JSON estructurado. Resultados orgánicos clasificados con posiciones, anuncios en su propio arreglo, la propia respuesta de IA de DuckDuckGo y 37 regiones para segmentar. Diseñado para volumen y para análisis, sin navegador local ni cadena de respaldo que configurar.

1,000 créditos gratis cada mes, sin necesidad de tarjeta, lo que equivale a 100 búsquedas.

https://mcp.hasdata.com/mcp?apis=duckduckgo

• Prompts y recursos

Contenido

• Lo que necesitas
• Inicio rápido
• Ejemplos de prompts
• Herramientas
• Errores y rutas de fallo
• Precios, nivel gratuito y límites
• Selección de herramientas
• Cómo se compara
• Preguntas frecuentes
• Enlaces de HasData
• Desarrollo
• Contribuciones
• Licencia

Lo que necesitas

Un cliente MCP que hable HTTP transmisible con encabezados personalizados. Una clave de API de HasData desde el panel de control, gratuita de crear. Nada más. Este es un servidor remoto, por lo que la ruta más simple es una URL y un encabezado, sin paquete de navegador que agregar ni proceso local que mantener. Un cliente solo stdio puede usar el lanzador @hasdata/duckduckgo-mcp (npm) o hasdata-duckduckgo-mcp (PyPI) en su lugar.

Inicio rápido

La URL del servidor es la misma para cada cliente. Lo ejecutamos de forma práctica en Claude Code y Claude Desktop. Los otros bloques siguen el formato documentado de cada cliente para un servidor remoto.

Los clientes con soporte OAuth pueden agregar la misma URL como conector e iniciar sesión sin poner una clave en un archivo de configuración.

claude mcp add --transport http duckduckgo "https://mcp.hasdata.com/mcp?apis=duckduckgo" \
  --header "x-api-key: HASDATA_API_KEY"

{
  "mcpServers": {
    "duckduckgo": {
      "command": "npx",
      "args": ["-y", "@hasdata/duckduckgo-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "duckduckgo": {
      "command": "uvx",
      "args": ["hasdata-duckduckgo-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "duckduckgo": {
      "url": "https://mcp.hasdata.com/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "duckduckgo": {
      "serverUrl": "https://mcp.hasdata.com/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "duckduckgo": {
      "url": "https://mcp.hasdata.com/mcp?apis=duckduckgo",
      "type": "streamableHttp",
      "headers": { "x-api-key": "HASDATA_API_KEY" },
      "disabled": false
    }
  }
}

{
  "servers": {
    "duckduckgo": {
      "type": "http",
      "url": "https://mcp.hasdata.com/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

[mcp_servers.duckduckgo]
url = "https://mcp.hasdata.com/mcp?apis=duckduckgo"

[mcp_servers.duckduckgo.headers]
"x-api-key" = "HASDATA_API_KEY"

{
  "mcpServers": {
    "duckduckgo": {
      "httpUrl": "https://mcp.hasdata.com/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

Ejemplos de prompts

Prompts, no código. Pega uno y el agente llama a la herramienta por sí mismo. Cada uno está anotado con las llamadas que realiza, porque en MCP el modelo decide cuántas llamadas hacer y cada llamada exitosa cuesta 10 créditos.

Busca en DuckDuckGo "model context protocol" y dame los diez mejores resultados con sus posiciones y dominios.

Una llamada, 10 créditos.

Ejecuta la consulta "vpn review" en la región alemana y nuevamente en la región de EE. UU., luego dime qué dominios aparecen en una y no en la otra.

Dos llamadas, 20 créditos. La región es un parámetro. La misma consulta en dos mercados son dos llamadas.

Busca "best crm software" y lista solo las colocaciones pagadas, con el dominio del anunciante para cada una.

Una llamada, 10 créditos. Los anuncios llegan en su propio arreglo y no necesitan heurísticas de filtrado.

Toma la consulta "model context protocol" y recorre las primeras tres páginas, luego dime qué dominios tienen más de una posición.

Tres llamadas, 30 créditos. Cada página después de la primera es una llamada nueva con el cursor, y elimina q de los argumentos una vez que tengas uno.

Busca "who invented the transistor" y muéstrame la propia respuesta de IA de DuckDuckGo junto a los resultados orgánicos en los que se basó.

Una llamada, 10 créditos.

Dos de esos son la razón por la que este servidor existe. La segmentación por región es un parámetro de primera clase en 37 mercados. Comparar una consulta entre países es un bucle y no una configuración de proxy. Y las colocaciones pagadas vuelven por separado de las orgánicas, lo que evita que el seguimiento de clasificación dependa de adivinar qué resultado fue un anuncio.

La paginación cuesta una llamada cada vez. Un prompt que recorre diez páginas son diez llamadas y 100 créditos.

Herramientas

Una herramienta. Las muestras a continuación están recortadas de llamadas reales, y los resultados en ellas cambian a medida que cambia la web. Léelas como formas.

Las muestras son la carga útil, no la respuesta completa. Un resultado tools/call lleva un bloque de texto, y ese texto es en sí mismo JSON que contiene url, status, text y json, con los datos extraídos bajo json. Desde una respuesta JSON-RPC cruda, la ruta es result.content[0].text, analizada, luego .json. Un cliente de chat lo desenvuelve por ti y el código que habla directamente con el endpoint no lo hace.

Obtener resultados de búsqueda de DuckDuckGo

hasdata_duckduckgo_serp_getSearchResults

Obtiene una página de resultados de DuckDuckGo y la devuelve analizada.

Envía ya sea q o nextPageToken. Enviar ninguno devuelve 422 nombrando ambos campos, porque el requisito es condicional y el esquema no puede expresarlo como una lista requerida simple. Enviar ambos tampoco es un error: el cursor gana y la consulta no va a ninguna parte, por lo que un agente que mantiene q en los argumentos mientras pagina lee silenciosamente el conjunto de resultados incorrecto.

position cuenta dentro de la página de la que proviene, no en todo el conjunto de resultados. La página dos vuelve con posiciones comenzando en 1 nuevamente, y el tamaño de página tampoco es fijo, por lo que páginas de 10, 15 y 14 resultados aparecen todas. El rango absoluto es, por lo tanto, el número de resultados orgánicos que ya has recopilado más position, no algo que puedas derivar del número de página. Construye un conjunto de datos de clasificación sin eso y cada página contribuye con su propio número uno.

Devuelve organicResults, ads, searchAssist y pagination. Las entradas orgánicas llevan position, title, link, displayedLink, source y snippet, más una fecha, enlaces de sitio y metadatos de video donde DuckDuckGo los muestra. searchAssist contiene la propia respuesta de IA de DuckDuckGo para la consulta.

ads y searchAssist están ausentes cuando la página no tiene ninguno, así que prueba la clave antes de leerla. organicResults también puede estar ausente, así que léelo con un valor predeterminado en lugar de tratar su presencia como dada. Una consulta sin coincidencias reales aún vuelve como una página completa de entradas vagamente relacionadas, lo cual no es cómo se ve normalmente "nada encontrado".

{
  "organicResults": [
    {
      "position": 1,
      "title": "What is the Model Context Protocol (MCP)?",
      "link": "https://modelcontextprotocol.io/docs/getting-started/intro",
      "displayedLink": "modelcontextprotocol.io › docs › getting-started › intro",
      "source": "modelcontextprotocol.io",
      "snippet": "MCP is an open-source standard for connecting AI applications to external systems."
    }
  ],
  "ads": [
    { "position": 1, "title": "Make Agents Accountable", "link": "https://www.gravitee.io/platform/ai-agent-management" }
  ],
  "searchAssist": {
    "answer": "Model Context Protocol (MCP) is an open standard from Anthropic that lets LLMs connect to external tools, systems, and data sources using a shared interface."
  },
  "pagination": { "nextPageToken": "eyJ1cmwiOiJodHRwczovL2xpbmtzLmR1Y2tkdWNrZ28uY29t…" }
}

Prompts y recursos

El servidor expone 5 recursos, uno por parámetro cuyos valores aceptados son una lista fija. Leer uno es más barato que aprender el vocabulario de una llamada rechazada, y no cuesta créditos. Cada URI es hasdata://duckduckgo/<parameter>.

La lista se sirve sin clave de API, por lo que un cliente puede leerla antes de que un usuario se haya registrado.

Errores y rutas de fallo

Tu cliente casi nunca ve un código de error HTTP de una llamada de herramienta. La capa MCP responde 200 y coloca el fallo dentro del resultado, con isError establecido en true y la razón como texto. El agente lee un mensaje donde podrías esperar una línea de estado.

Una clave incorrecta aparece como salida de herramienta, no como conexión fallida. Listar herramientas acepta cualquier clave no vacía, por lo que el cliente completa su protocolo de enlace y muestra verde. La primera llamada de herramienta luego vuelve con isError: true y el texto HasData API error: 401 Unauthorized. Vigila esa cadena, porque nada antes en el flujo informa el problema.

Una clave faltante es el único error HTTP real. La autorización se ejecuta antes de cualquier herramienta, y la conexión misma falla con 401.

Un argumento que rompe el esquema se rechaza antes de convertirse en búsqueda. El servidor responde con isError: true y el texto MCP error -32602: Input validation error, nombrando el campo. Nada se obtiene y nada se cobra.

Ni q ni nextPageToken devuelve 422 con un arreglo errors nombrando ambos campos y la regla requiredIfNotExists que los une.

Una consulta sin nada detrás aún devuelve resultados. DuckDuckGo decide la relevancia, por lo que una cadena sin sentido vuelve como una página normal de diez entradas vagamente relacionadas con ads y searchAssist ausentes. Nada la marca como un fallo, lo cual importa si estás construyendo una alerta sobre "sin cobertura para esta marca".

Los resultados que llevan datos también llevan un requestMetadata.id que vale la pena citar en soporte.

Precios, nivel gratuito y límites

Cada llamada cuesta 10 créditos. El número de resultados no cambia el precio. Una página completa cuesta lo mismo que una página con una sola entrada.

El plan gratuito es de 1,000 créditos cada mes sin tarjeta, lo que equivale a 100 búsquedas. Se renueva con el ciclo de facturación, por lo que un agente de bajo volumen funciona con el plan gratuito indefinidamente.

Los planes de pago comienzan en $59 al mes por 200,000 créditos, lo que equivale a 20,000 búsquedas. El precio unitario baja con el volumen, desde $2.95 por cada 1,000 búsquedas en el plan inicial hasta $1.19 en Basic y $0.83 en los niveles Growth. Las cifras actuales están en la página de precios.

Tu plan también define la concurrencia. El plan gratuito permite 1 solicitud a la vez, Startup 5, Basic 15, y los niveles Growth van de 50 a 500. Maneja el caso de desbordamiento de forma defensiva en cualquier proceso desatendido, porque un agente que se expande llegará al límite antes que tú.

Una solicitud que devuelve un código distinto de 200 no se factura. Una llamada exitosa que no encuentra nada sigue siendo una llamada.

Selección de herramientas

El parámetro de consulta apis decide qué herramientas ve tu agente. Menos herramientas significa menos contexto gastado en definiciones de herramientas y menos posibilidades de que el modelo use la incorrecta.

?apis=duckduckgo                        the one tool in this repo
?apis=duckduckgo,google_serp            add Google search
?apis=duckduckgo,bing_serp,google_serp  three engines side by side

El parámetro acepta nombres de proveedores como duckduckgo y nombres de API individuales como google_maps_search. Los nombres mal escritos se ignoran. Si todos los nombres son incorrectos, la solicitud falla con 400 y el cuerpo enumera tanto lo que no reconoció como todos los valores válidos. Si omites el parámetro, el mismo endpoint expone las 57 herramientas de HasData.

Tres motores en un solo agente es la razón común para ampliar la lista aquí, porque comparar la misma consulta en DuckDuckGo, Google y Bing es una sola instrucción una vez que los tres están expuestos.

Cómo se compara

La alternativa realista es un servidor autoalojado. Los populares son paquetes de Python que ejecutas localmente, llegan a DuckDuckGo desde tu propia máquina y le entregan al modelo un bloque de texto formateado. Eso funciona bien para un asistente de investigación que responde una pregunta a la vez. Deja de funcionar cuando quieres volumen y una forma estable.

Dos filas llevan la mayor parte de la decisión. Un bloque de texto es el resultado correcto para una respuesta de chat y el incorrecto para un conjunto de datos clasificados, porque reconstruir position a partir de prosa es trabajo que no deberías hacer. Y que la obtención sea nuestra significa que la pregunta del backend desaparece, junto con elegir entre httpx y un cliente que imita al navegador, instalar el extra del que depende el respaldo y leer un seguimiento de pila cuando un cliente HTTP simple deja de recibir una página.

Todo lo demás en esa lista es una compensación real. Un servidor autoalojado es gratuito, no requiere cuenta, mantiene tus consultas en tu propia máquina y obtiene contenido de página, algo que este servidor no hace. Si ejecutas un puñado de búsquedas al día dentro de un solo asistente, es la mejor opción. Este es para el caso en el que el número de búsquedas, el número de regiones o la forma de la salida empiezan a importar.

Frente a la propia API de DuckDuckGo. api.duckduckgo.com es la API de Instant Answer, y devuelve un resumen enciclopédico cuando existe en lugar de una página de resultados. No hay un endpoint oficial que entregue resultados web clasificados, por eso cada opción aquí analiza la página.

Lo que este servidor no hace. Sin obtención de páginas ni extracción de contenido, sin verticales de imágenes o noticias, sin autocompletado. Devuelve la página de resultados, analizada.

FAQ

¿Existe un servidor MCP oficial de DuckDuckGo?

No. DuckDuckGo no publica ningún servidor MCP. Cada opción está construida por otra persona. La mayoría son proyectos de código abierto que se ejecutan localmente, y este es un servidor alojado mantenido por HasData.

¿Qué es un servidor MCP de DuckDuckGo?

Un servidor que expone la búsqueda de DuckDuckGo como una herramienta que un cliente de IA puede invocar. El cliente envía una llamada de herramienta a través del Model Context Protocol, el servidor ejecuta la búsqueda y devuelve JSON estructurado, y el modelo trabaja con el resultado y nunca ve una página de HTML.

¿Necesito una cuenta de DuckDuckGo o una clave de API?

No. La única credencial es tu clave de HasData. DuckDuckGo no tiene un programa para desarrolladores al que registrarse, y la API de Instant Answer que publica no devuelve resultados de búsqueda.

¿Necesito alojar o ejecutar algo?

No. Este es un servidor MCP remoto en HTTP transmisible. Nada que instalar, sin entorno de Python, sin paquete de navegador, sin proceso que reiniciar.

¿Los datos son en vivo o en caché?

En vivo. Cada llamada obtiene la página de resultados en el momento de la solicitud y lleva su propio requestMetadata.id. Dos llamadas idénticas son dos obtenciones separadas y no una reproducción de una copia almacenada.

¿Puedo comparar la misma consulta entre regiones?

Sí, y esa es la razón principal para usar un parámetro en lugar de un proxy. kl acepta 37 códigos de región, y cc con setLang separa país e idioma cuando los necesitas por separado. Cada región es su propia llamada.

¿Qué sucede cuando DuckDuckGo cambia su diseño?

Nada de tu lado. Nosotros seguimos los cambios y mantenemos estable el esquema de respuesta, por lo que los nombres y tipos de campos permanecen igual. Un bloque sin nada que informar está ausente de la respuesta, así que lee ads y searchAssist con un valor predeterminado.

¿Puedo usar esto junto con otras APIs de HasData?

Sí. El parámetro apis acepta una lista, y ?apis=duckduckgo,google_serp,bing_serp le da a tu agente tres motores de búsqueda a la vez.

¿Puedo iniciar sesión con OAuth en lugar de pegar una clave?

Sí, en clientes que lo admitan. Claude Desktop y Cursor pueden agregar el endpoint como conector e iniciar sesión. Los agentes y scripts desatendidos usan el encabezado x-api-key.

Cumplimiento y datos personales

HasData accede únicamente a datos disponibles públicamente. Los términos de una plataforma pueden restringir el acceso automatizado, y tú eres responsable de tu propio cumplimiento. Cuando los datos que recopilas incluyan información personal, asegúrate de tener una base legal para ello según GDPR, CCPA o las reglas equivalentes en tu jurisdicción.

Enlaces de HasData

Desarrollo

Este repositorio es configuración y documentación para un servidor remoto. No hay paso de compilación ni nada que contenerizar.

Las pruebas en test/ verifican el contrato de la herramienta, la parte que puede romperse sin un commit aquí. Comprueban que ?apis=duckduckgo devuelve exactamente una herramienta, que su nombre no ha cambiado, que los parámetros que documenta este README siguen existiendo con los enums que cita, y que la clave en uso es realmente aceptada. Esa última verificación ejecuta una búsqueda real y cuesta 10 créditos, que es el precio de un canario que puede fallar por la razón correcta.

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

La misma suite se ejecuta en CI en cada push y una vez a la semana de forma programada, porque la lista de herramientas ascendente puede cambiar sin que nadie toque este repositorio. Un fallo significa que la lista de herramientas se movió, la clave dejó de funcionar o el endpoint era inalcanzable, y el mensaje de la aserción dice cuál.

Contribuciones

Las correcciones a la tabla de parámetros y a la muestra de respuesta son la contribución más útil, porque son las partes que se desvían. Incluye la llamada que hiciste y la respuesta que obtuviste. Las solicitudes de extracción de bifurcaciones ejecutan la suite sin clave, y las verificaciones en vivo se omiten en lugar de ponerse en rojo.

Licencia

MIT. Consulta LICENSE.