DuckDuckGo MCP Server

Un servidor de Model Context Protocol (MCP) alojado que ofrece a Claude, Cursor, Windsurf y cualquier otro cliente MCP los resultados de búsqueda de DuckDuckGo como JSON estructurado. Resultados orgánicos clasificados con posiciones, anuncios en su propio array, la respuesta de IA propia de DuckDuckGo y 37 regiones a las que dirigirse. Diseñado para volumen y para parseo, sin navegador local y sin cadena de respaldo que configurar.

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

Contenido

• Qué necesitas

• Inicio rápido

• Ejemplos de prompts

• Herramientas

• Errores y rutas de fallo

• Precios, plan gratuito y límites

• Selección de herramienta

• Cómo se compara

• FAQ

• Enlaces de HasData

• Desarrollo

• Contribuciones

• Licencia

Related MCP server: duckduckgo-mcp

Qué necesitas

Un cliente MCP que hable HTTP transmisible con cabeceras personalizadas. Una clave de API de HasData desde el panel de control, gratis de crear. Nada más. Este es un servidor remoto, así que la vía más sencilla es una URL y una cabecera, sin paquete de navegador que añadir y sin 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 todos los clientes. Lo probamos directamente en Claude Code y Claude Desktop. Los demás bloques siguen el formato documentado de cada cliente para un servidor remoto.

Los clientes con soporte de OAuth pueden añadir 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/api/mcp?apis=duckduckgo" \
  --header "x-api-key: HASDATA_API_KEY"

Ajustes, luego Conectores, luego Añadir conector personalizado, y luego pega https://mcp.hasdata.com/api/mcp?apis=duckduckgo e inicia sesión.

Para la vía del archivo de configuración, Claude Desktop solo carga servidores locales (stdio), así que llega a un servidor remoto a través de un lanzador stdio. El paquete @hasdata/duckduckgo-mcp es ese lanzador y lee la clave del entorno. Añade esto a claude_desktop_config.json:

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

¿Python en lugar de Node? Sustituye el lanzador por el paquete de PyPI, que uvx ejecuta sin instalación manual:

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

~/.cursor/mcp.json para todos los proyectos, o .cursor/mcp.json para uno solo:

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

~/.codeium/windsurf/mcp_config.json. Windsurf llama al campo serverUrl, no url:

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

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

.vscode/mcp.json en el espacio de trabajo:

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

~/.codex/config.toml:

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

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

~/.gemini/settings.json:

{
  "mcpServers": {
    "duckduckgo": {
      "httpUrl": "https://mcp.hasdata.com/api/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 su cuenta. Cada uno está anotado con las llamadas que requiere, porque en MCP el modelo decide cuántas llamadas hacer y cada llamada con éxito cuesta 10 créditos.

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

Una llamada, 10 créditos.

Ejecuta la consulta "reseña de VPN" en la región de Alemania y de nuevo en la región de EE. UU., y 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 "mejor software de CRM" y enumera solo los emplazamientos de pago, con el dominio del anunciante de cada uno.

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

Toma la consulta "model context protocol" y recorre las tres primeras páginas, y luego dime qué dominios ocupan 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 "quién inventó el transistor" y muéstrame la respuesta de IA propia de DuckDuckGo junto a los resultados orgánicos en los que se basó.

Una llamada, 10 créditos.

Dos de ellos son la razón de que exista este servidor. 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 los emplazamientos de pago vuelven por separado de los orgánicos, lo que evita que el seguimiento de posiciones dependa de adivinar qué resultado era un anuncio.

Cada paginación cuesta una llamada. Un prompt que recorra diez páginas son diez llamadas y 100 créditos.

Herramientas

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

Las muestras son la carga útil, no la respuesta completa. Un resultado de tools/call lleva un bloque de texto, y ese texto es a su vez 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, parseado, y después .json. Un cliente de chat te lo desenvuelve, y el código que habla directamente con el endpoint no.

Obtener resultados de búsqueda de DuckDuckGo

hasdata_duckduckgo_serp_getSearchResults

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

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

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 que empiezan en 1 otra vez, y el tamaño de página tampoco es fijo, así que aparecen páginas de 10, 15 y 14 resultados. Por tanto, la posición absoluta es el número de resultados orgánicos que ya has recopilado más position, no algo que puedas deducir del número de página. Construye un conjunto de datos de posiciones sin eso y cada página aportará su propio número uno.

Devuelve organicResults, ads, searchAssist y pagination. Las entradas orgánicas incluyen position, title, link, displayedLink, source y snippet, además de una fecha, sitelinks y metadatos de vídeo donde DuckDuckGo los muestra. searchAssist contiene la respuesta de IA propia de DuckDuckGo para la consulta.

ads y searchAssist están ausentes cuando la página no tiene ninguno, así que comprueba la clave antes de leerla. organicResults también puede estar ausente, así que léela con un valor por defecto en lugar de dar por hecha su presencia. Una consulta sin coincidencias reales sigue devolviendo una página completa de entradas vagamente relacionadas, que no es el aspecto habitual de "no se ha encontrado nada".

{
  "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…" }
}

Errores y rutas de fallo

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

Una clave incorrecta aparece como salida de la herramienta, no como una conexión fallida. Enumerar las herramientas acepta cualquier clave no vacía, así que el cliente completa su handshake y se muestra en verde. La primera llamada a herramienta vuelve entonces con isError: true y el texto HasData API error: 401 Unauthorized. Vigila esa cadena, porque nada antes en el flujo informa del problema.

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

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

Ni q ni nextPageToken devuelve 422 con un array errors que nombra ambos campos y la regla requiredIfNotExists que los vincula.

Una consulta sin nada detrás sigue devolviendo resultados. DuckDuckGo decide la relevancia, así 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 creando una alerta sobre "sin cobertura para esta marca".

Los resultados que contienen datos también llevan un requestMetadata.id que conviene citar en soporte.

Precios, plan 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.

La prueba gratuita es de 1.000 créditos durante 30 días sin tarjeta, lo que equivale a 100 búsquedas. Después, una cuenta activa sigue recibiendo una recarga de 100 créditos cada día siempre que su saldo baje de 100, así que un agente de bajo volumen funciona con el plan gratuito indefinidamente.

Los planes de pago empiezan en $49 al mes por 200.000 créditos, lo que equivale a 20.000 búsquedas. El precio unitario baja con el volumen, desde $2,45 por cada 1.000 búsquedas en el plan de entrada hasta $0,99 en Business, $0,83 en Growth y $0,75 en los planes de gran volumen más grandes. Las cifras actuales están en la página de precios.

Tu plan también fija la concurrencia. La prueba gratuita permite 1 solicitud a la vez, Startup 15, Business 30, Growth 50, y los planes de gran volumen van de 200 a 1.500. Gestiona el desbordamiento de forma defensiva en cualquier proceso desatendido, porque un agente que lance muchas solicitudes alcanzará el límite antes que tú.

Una solicitud que devuelve un código distinto de 200 no se factura. Una llamada correcta 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 dedicado a las definiciones de herramientas y menos oportunidades de que el modelo elija 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 un 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.

Tener tres motores en un mismo agente es el motivo habitual para ampliar la lista aquí, porque comparar la misma consulta en DuckDuckGo, Google y Bing es una sola indicación una vez que los tres están expuestos.

Cómo se compara

La alternativa realista es un servidor autoalojado. Los más populares son paquetes de Python que ejecutas localmente, acceden a DuckDuckGo desde tu propia máquina y le entregan al modelo un bloque de texto con formato. 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 son las que más pesan en la decisión. Un bloque de texto es la salida correcta para una respuesta de chat y la incorrecta para un conjunto de datos de posiciones, porque reconstruir position a partir de prosa es un trabajo que no deberías estar haciendo. Y que la descarga sea nuestra elimina la cuestión del backend, junto con elegir entre httpx y un cliente que imita al navegador, instalar el extra del que depende la opción de reserva y leer una traza de pila cuando un cliente HTTP normal deja de obtener la página.

Todo lo demás en esa lista supone una disyuntiva real. Un servidor autoalojado es gratis, no requiere cuenta, mantiene tus consultas en tu propia máquina y descarga el contenido de las páginas, cosa que este servidor no hace. Si ejecutas unas pocas búsquedas al día dentro de un asistente, es la opción que mejor se ajusta. Este es para el caso en que el número de búsquedas, el número de regiones o la forma de la salida empiezan a importar.

Frente a la API propia de DuckDuckGo. api.duckduckgo.com es la API de Instant Answer, que devuelve un resumen enciclopédico cuando lo hay, en lugar de una página de resultados. No hay ningún endpoint oficial que te proporcione resultados web clasificados, por lo que todas las opciones aquí analizan la página.

Lo que este servidor no hace. No descarga páginas ni extrae contenido, no tiene verticales de imágenes ni de noticias, ni autocompletado. Devuelve la página de resultados, parseada.

Preguntas frecuentes

¿Existe un servidor MCP oficial de DuckDuckGo?

No. DuckDuckGo no publica ningún servidor MCP. Todas las opciones las crea 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 llamar. El cliente envía una llamada a la herramienta mediante el Model Context Protocol, el servidor realiza la búsqueda y devuelve JSON estructurado, y el modelo trabaja con el resultado sin ver nunca una página HTML.

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

No. La única credencial es tu clave de HasData. DuckDuckGo no tiene ningún programa para desarrolladores en el 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 sobre streamable HTTP. Nada que instalar, sin entorno de Python, sin paquete de navegador, sin proceso que reiniciar.

¿Los datos son en directo o están en caché?

En directo. 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 descargas independientes, no una reproducción de una copia almacenada.

¿Puedo comparar la misma consulta en distintas 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 el país y el idioma cuando necesitas distinguirlos. Cada región es una llamada propia.

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

Nada por tu parte. Nosotros seguimos los cambios y mantenemos estable el esquema de respuesta, por lo que los nombres y tipos de los campos permanecen igual. Un bloque sin nada que notificar no aparece en la respuesta, así que lee ads y searchAssist con un valor por defecto.

¿Puedo usar esto junto con otras API 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 los clientes que lo admiten. Claude Desktop y Cursor pueden añadir el endpoint como conector e iniciar sesión. Los agentes y scripts desatendidos usan la cabecera x-api-key.

Cumplimiento normativo y datos personales

HasData solo accede a datos disponibles públicamente. Los términos de una plataforma pueden restringir el acceso automatizado, y tú eres responsable de tu propio cumplimiento. Si los datos que recopilas incluyen información personal, asegúrate de tener una base legal para ello según el GDPR, la CCPA o las normas equivalentes de 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 que haya 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 comprobació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 upstream puede cambiar sin que nadie toque este repositorio. Un fallo significa que la lista de herramientas se ha movido, que la clave ha dejado de funcionar o que el endpoint era inalcanzable, y el mensaje de la aserción indica cuál de ellos.

Contribuciones

Las correcciones de la tabla de parámetros y de la muestra de respuesta son la contribución más útil, porque esas son las partes que se desactualizan. Incluye la llamada que hiciste y la respuesta que obtuviste. Las pull requests desde forks ejecutan la suite sin clave, y las comprobaciones en vivo se omiten en lugar de ponerse en rojo.

Licencia

MIT. Consulta LICENSE.