DuckDuckGo MCP Server

Ein gehosteter Model Context Protocol (MCP)-Server, der Claude, Cursor, Windsurf und jedem anderen MCP-Client DuckDuckGo-Suchergebnisse als strukturiertes JSON liefert. Organische Ergebnisse mit Rangpositionen, Anzeigen in einem eigenen Array, DuckDuckGos eigene KI-Antwort und 37 Regionen als Ziel. Gebaut für hohes Volumen und für das Parsen, ohne lokalen Browser und ohne zu konfigurierende Fallback-Kette.

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

Inhalt

• Was du brauchst

• Schnellstart

• Beispiel-Prompts

• Tools

• Fehler und Fehlerpfade

• Preise, kostenloses Kontingent und Limits

• Tool-Auswahl

• Wie es sich vergleicht

• FAQ

• HasData-Links

• Entwicklung

• Mitwirken

• Lizenz

Related MCP server: duckduckgo-mcp

Was du brauchst

Ein MCP-Client, der Streamable HTTP mit benutzerdefinierten Headern unterstützt. Ein HasData-API-Schlüssel vom Dashboard, kostenlos zu erstellen. Sonst nichts. Dies ist ein Remote-Server, daher ist der einfachste Weg eine URL und ein Header, ohne Browser-Paket, das du hinzufügen müsstest, und ohne lokalen Prozess, den du am Laufen halten müsstest. Ein reiner stdio-Client kann stattdessen den Launcher @hasdata/duckduckgo-mcp (npm) oder hasdata-duckduckgo-mcp (PyPI) verwenden.

Schnellstart

Die Server-URL ist für jeden Client dieselbe. Wir setzen ihn praktisch in Claude Code und Claude Desktop ein. Die anderen Blöcke folgen dem jeweils dokumetierten Format der Clients für einen Remote-Server.

Clients mit OAuth-Unterstützung können dieselbe URL als Connector hinzufügen und sich anmelden, ohne einen Schlüssel in eine Konfigurationsdatei zu legen.

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

Gehe zu Einstellungen, dann zu Connectors, dann zu „Benutzerdefinierten Connector hinzufügen“, füge https://mcp.hasdata.com/api/mcp?apis=duckduckgo ein und melde dich an.

Für den Weg über die Konfigurationsdatei lädt Claude Desktop nur lokale (stdio) Server, daher erreicht es einen Remote-Server über einen stdio-Launcher. Das Paket @hasdata/duckduckgo-mcp ist dieser Launcher und liest den Schlüssel aus der Umgebung. Füge das zu claude_desktop_config.json hinzu:

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

Python statt Node? Tausche den Launcher gegen das PyPI-Paket aus, das uvx ohne manuelle Installation ausführt:

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

~/.cursor/mcp.json für jedes Projekt oder .cursor/mcp.json für ein einzelnes:

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

~/.codeium/windsurf/mcp_config.json. Windsurf nennt das Feld serverUrl, nicht 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 im Workspace:

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

Beispiel-Prompts

Prompts, kein Code. Füge einen ein, und der Agent ruft das Tool selbst auf. Jeder ist mit den nötigen Aufrufen versehen, denn in MCP entscheidet das Modell, wie viele Aufrufe es macht, und jeder erfolgreiche Aufruf kostet 10 Credits.

Suche bei DuckDuckGo nach „model context protocol“ und gib mir die Top-Ten-Ergebnisse mit ihren Positionen und Domains.

Ein Aufruf, 10 Credits.

Führe die Abfrage „vpn review“ in der deutschen Region und noch einmal in der US-Region aus und sag mir dann, welche Domains in der einen, aber nicht in der anderen vorkommen.

Zwei Aufrufe, 20 Credits. Die Region ist ein Parameter. Dieselbe Abfrage in zwei Märkten ist zwei Aufrufe.

Suche nach „best crm software“ und liste nur die bezahlten Platzierungen mit der jeweiligen Domain des Werbetreibenden.

Ein Aufruf, 10 Credits. Anzeigen kommen in einem eigenen Array an und benötigen keine Filterheuristiken.

Nimm die Abfrage „model context protocol“ und durchlaufe die ersten drei Seiten. Sag mir dann, welche Domains mehr als eine Position belegen.

Drei Aufrufe, 30 Credits. Jede Seite nach der ersten ist ein neuer Aufruf mit dem Cursor; lasse q aus den Argumenten weg, sobald du einen hast.

Suche nach „who invented the transistor“ und zeig mir DuckDuckGos eigene KI-Antwort neben den organischen Ergebnissen, auf die sie sich stützt.

Ein Aufruf, 10 Credits.

Zwei davon sind der Grund, warum dieser Server existiert. Region-Targeting ist ein erstklassiger Parameter über 37 Märkte. Eine Abfrage über Länder hinweg zu vergleichen ist eine Schleife und kein Proxy-Setup. Und bezahlte Platzierungen kommen getrennt von den organischen zurück, sodass das Rank-Tracking nicht davon abhängt, zu raten, welches Ergebnis eine Anzeige war.

Das Blättern kostet jedes Mal einen Aufruf. Ein Prompt, der zehn Seiten durchläuft, sind zehn Aufrufe und 100 Credits.

Tools

Ein Tool. Die folgenden Beispiele sind aus echten Aufrufen gekürzt, und die Ergebnisse darin ändern sich, wenn sich das Web ändert. Betrachte sie als Strukturen.

Die Beispiele sind die Nutzlast, nicht die gesamte Antwort. Ein tools/call-Ergebnis enthält einen Textblock, und dieser Text ist selbst JSON mit url, status, text und json, wobei die gescrapten Daten unter json liegen. Bei einer rohen JSON-RPC-Antwort geht der Pfad über result.content[0].text, das geparst wird, und dann über .json. Ein Chat-Client packt das für dich aus; Code, der direkt mit dem Endpunkt spricht, tut das nicht.

DuckDuckGo-Suchergebnisse abrufen

hasdata_duckduckgo_serp_getSearchResults

Ruft eine DuckDuckGo-Ergebnisseite ab und gibt sie geparst zurück.

Sende entweder q oder nextPageToken. Wenn du keines sendest, wird 422 zurückgegeben, das beide Felder nennt, weil die Anforderung bedingt ist und das Schema sie nicht als einfache Pflichtliste ausdrücken kann. Auch das Senden beider ist kein Fehler; der Cursor gewinnt und die Abfrage geht ins Leere, sodass ein Agent, der beim Blättern q in den Argumenten behält, stillschweigend das falsche Ergebnisset liest.

position zählt innerhalb der Seite, aus der es stammt, nicht über die gesamte Ergebnismenge. Seite zwei kommt mit Positionen zurück, die wieder bei 1 beginnen, und auch die Seitengröße ist nicht festgelegt, sodass Seiten mit 10, 15 und 14 Ergebnissen vorkommen. Der absolute Rang ist also die Anzahl der bereits gesammelten organischen Ergebnisse plus position, nicht etwas, das du aus der Seitennummer ableiten kannst. Wenn du einen Rangdatensatz ohne das aufbaust, trägt jede Seite ihre eigene Nummer eins bei.

Gibt organicResults, ads, searchAssist und pagination zurück. Organische Einträge enthalten position, title, link, displayedLink, source und snippet, zusätzlich ein Datum, Sitelinks und Video-Metadaten, wo DuckDuckGo sie anzeigt. searchAssist enthält DuckDuckGos eigene KI-Antwort für die Abfrage.

ads und searchAssist fehlen, wenn die Seite keines von beiden enthält; prüfe also, ob der Schlüssel vorhanden ist, bevor du ihn liest. organicResults kann ebenfalls fehlen, also lies es mit einem Standardwert, statt sein Vorhandensein als gegeben vorauszusetzen. Eine Abfrage ohne echte Treffer kommt trotzdem als volle Seite loser verwandter Einträge zurück, was nicht wie „nichts gefunden“ aussieht.

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

Fehler und Fehlerpfade

Dein Client sieht bei einem Tool-Aufruf fast nie einen HTTP-Fehlercode. Die MCP-Ebene antwortet mit 200 und legt den Fehler ins Ergebnis, mit isError auf true gesetzt und dem Grund als Text. Der Agent liest eine Nachricht, wo du eine Statuszeile erwarten würdest.

Ein falscher Schlüssel taucht als Tool-Ausgabe auf, nicht als fehlgeschlagene Verbindung. Das Auflisten von Tools akzeptiert jeden nicht-leeren Schlüssel, also schließt der Client seinen Handshake ab und zeigt Grün. Der erste Tool-Aufruf kommt dann mit isError: true und dem Text HasData API error: 401 Unauthorized zurück. Achte auf diesen String, denn nichts früher im Ablauf meldet das Problem.

Ein fehlender Schlüssel ist der einzige echte HTTP-Fehler. Die Autorisierung läuft vor jedem Tool, und die Verbindung selbst schlägt mit 401 fehl.

Ein Argument, das das Schema verletzt, wird abgelehnt, bevor daraus eine Suche wird. Der Server antwortet mit isError: true und dem Text MCP error -32602: Input validation error, wobei das Feld benannt wird. Es wird nichts abgerufen und nichts berechnet.

Wenn weder q noch nextPageToken übergeben wird, wird 422 mit einem errors-Array zurückgegeben, das beide Felder und die requiredIfNotExists-Regel benennt, die sie miteinander verknüpft.

Eine Abfrage, hinter der nichts steht, gibt trotzdem Ergebnisse zurück. DuckDuckGo entscheidet über die Relevanz, also kommt eine unsinnige Zeichenkette als normale Seite mit zehn locker verwandten Einträgen zurück, wobei ads und searchAssist fehlen. Nichts markiert sie als Fehlschlag, was wichtig ist, wenn du einen Alarm für „keine Abdeckung für diese Marke“ baust.

Ergebnisse, die Daten enthalten, enthalten auch eine requestMetadata.id, die es wert ist, im Support angeführt zu werden.

Preise, kostenloses Kontingent und Limits

Jeder Aufruf kostet 10 Credits. Die Anzahl der Ergebnisse ändert den Preis nicht. Eine volle Seite kostet so viel wie eine Seite mit einem Eintrag.

Die kostenlose Testversion umfasst 1.000 Credits über 30 Tage ohne Karte, also 100 Suchen. Danach erhält ein aktives Konto weiterhin täglich 100 Credits gutgeschrieben, immer wenn sein Guthaben unter 100 fällt, sodass ein Agent mit geringem Volumen unbegrenzt auf dem kostenlosen Tarif läuft.

Paid plans start at 49 $ pro Monat für 200.000 Credits, das entspricht 20.000 Suchen. Der Stückpreis sinkt mit dem Volumen, von 2,45 $ pro 1.000 Suchen im Einstiegstarif über 0,99 $ bei Business, 0,83 $ bei Growth bis 0,75 $ bei den größten Tarifen mit hohem Volumen. Aktuelle Zahlen finden Sie auf der Preisseite.

Ihr Tarif legt auch die Nebenläufigkeit fest. Die kostenlose Testversion erlaubt 1 Anfrage gleichzeitig, Startup 15, Business 30, Growth 50, und die Tarife mit hohem Volumen reichen von 200 bis 1.500. Behandeln Sie den Überlastungsfall in unbeaufsichtigten Umgebungen defensiv, denn ein Agent, der viele parallele Anfragen sendet, erreicht die Obergrenze eher als Sie.

Eine Anfrage, die mit einem Status ungleich 200 zurückkommt, wird nicht berechnet. Ein erfolgreicher Aufruf, der nichts findet, ist trotzdem ein Aufruf.

Auswahl der Tools

Der Abfrageparameter apis bestimmt, welche Tools Ihr Agent sieht. Weniger Tools bedeutet weniger Kontext für Tool-Definitionen und weniger Gelegenheiten für das Modell, zum falschen zu greifen.

?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

Der Parameter akzeptiert Providernamen wie duckduckgo und einzelne API-Namen wie google_maps_search. Falsch geschriebene Namen werden ignoriert. Wenn jeder Name falsch ist, schlägt die Anfrage mit 400 fehl, und der Body listet sowohl das, was nicht erkannt wurde, als auch alle gültigen Werte auf. Lässt man den Parameter weg, legt derselbe Endpunkt alle 57 HasData-Tools offen.

Drei Suchmaschinen in einem Agenten sind der häufgste Grund, die Liste hier zu erweitern, denn der Vergleich derselben Anfrage über DuckDuckGo, Google und Bing hinweg ist ein einziger Prompt, sobald al e drei verfügbar sind.

Vergleich

Die realistische Alternative ist ein selbst gehosteter Server. Die gängigen Lösungen sind Python-Pakete, die Sie lokal ausführen; sie greifen von Ihrer eigenen Maschinen auf DuckDuckGo zu und übergeben dem Modell einen formatierten Textblock. Das funktioniert gut für einen Recherche-Assistenten, der jeweils eine Frage beantwortet. Es hört auf zu funktioniert, wenn Sie Volumen und eine stabile Form benötigen.

Zwei Zeilen tragen den Großteil der Entscheidung. Ein Textblock ist die richtige Ausgabe für eine Chat-Antwort und die falsche für einen Ranking-Datensatz, denn position aus Prosa zu rekonstruieren, ist Arbeit, die Sie nicht erledigen sollten. Und dass das Abrufen bei uns liegt, macht die Backend-Frage überflüssig – ebenso die Wahl zwischen httpx und einem Browser-imitierenden Client, das Installieren des Zusatzpakets, von dem der Fallback abhängt, und das Lesen eines Stacktraces, wenn ein einfacher HTTP-Client keine Seite mehr zurückbekommt.

Alles andere auf dieser Liste ist ein echter Kompromiss. Ein selbst gehosteter Server ist kostenlos, benötigt kein Konto, behält Ihre Abfragen auf Ihrer eigenen Maschine und ruft Seiteninhalte ab, was dieser Server nicht tut. Wenn Sie täglich eine Handvoll Suchen in einem Assistenten ausführen, ist er die bessere Wahl. Dieser hier ist für den Fall gedacht, wenn die Anzahl der Suchen, die Anzahl der Regionen oder die Form der Ausgabe wichtig wird.

Im Vergleich zu DuckDuckGos eigener API. api.duckduckgo.com ist die Instant Answer API und gibt, sofern vorhanden, eine Enzyklopädie-Zusammenfassung zurück statt einer Ergebnisseite. Es gibt keinen offiziellen Endpunkt, der Ihnen nach Rang geordnete Webergebnisse liefert; deshalb parst jede hier genannte Option die Seite.

Was dieser Server nicht tut. Kein Abruf von Seiten und keine Inhaltsetraktion, keine Bild- oder News-Bereiche, keine Autovervollständigung. Er gibt die Ergebnisseite zurück, geparst.

FAQ

Gibt es einen offiziellen DuckDuckGo-MCP-Server?

Nein. DuckDuckGo veröffentlicht keinen MCP-Server. Jede Option wird von jemand anderem erstellt. Die meisten sind Open-Source-Projekte, die lokal laufen, und dieser hier ist ein von HasData gepflegter gehosteter Server.

Was ist ein DuckDuckGo-MCP-Server?

Ein Server, der die DuckDuckGo-Suche als Tool bereitstellt, das ein KI-Client aufrufen kann. Der Client sendet einen Tool-Aufruf über das Model Context Protocol, der Server führt die Suche aus und gibt strukturiertes JSON zurück, und das Modell arbeitet mit dem Ergebnis und sieht niemals eine HTML-Seite.

Benötige ich ein DuckDuckGo-Konto oder einen API-Schlüssel?

Nein. Die einzige Anmeldeinformation ist Ihr HasData-Schlüssel. DuckDuckGo bietet kein Entwicklerprogramm an, für das Sie sich anmelden könnten, und die Instant Answer API, die es veröffentlicht, liefert keine Suchergebnisse.

Muss ich etwas hosten oder ausführen?

Nein. Dies ist ein entfernter MCP-Server über Streamable HTTP. Nichts zu installieren, keine Python-Umgebung, kein Browserpaket, kein Prozess, der neu gestartet werden muss.

Sind die Daten live oder zwischenspeichert?

Live. Jeder Aufruf ruft die Ergebnisseite zum Zeipunkt der Anfrage ab und trägt eine eigene requestMetadata.id. Zwei identische Aufrufe sind zwei getrennte Abrufe und keine Wiedergabe einer gespeicherten Kopie.

Kann ich dieselbe Abfrage über Regionen hinweg vergleichen?

Ja, und das ist der Hauptgrund, einen Parameter statt eines Proxys zu verwenden. kl akzeptiert 37 Regionscodes, und cc mit setLang trennt Land und Sprache, wenn Sie sie getrennt benötigen. Jede Region ist ein eigener Aufruf.

Was passiert, wenn DuckDuckGo sein Layout ändert?

Auf Ihrer Seite nichts. Wir verfolgen die Änderungen und halten das Antwortschema stabil, sodass Feldnamen und Typen unverändert bleiben. Ein Block ohne etwas zu melden fehlt in der Antwort; lesen Sie ads und searchAssist also mit einem Standardwert.

Kann ich das zusammen mit anderen HasData-APIs verwenden?

Ja. Der Parameter apis akzeptiert eine Liste, und ?apis=duckduckgo,google_serp,bing_serp gibt Ihrem Agenten drei Suchmaschinen auf einmal.

Kann ich mich per OAuth anmelden, anstatt einen Schlüssel einzufügen?

Ja, in Clients, die das unterstützen. Claude Desktop und Cursor können den Endpunkt als Connector hinzufügen und sich anmelden. Unbeaufsichtigte Agenten und Skripte verwenden den x-api-key-Header.

Compliance und personenbezogene Daten

HasData greift ausschließlich auf öffentlich verfügbare Daten zu. Die Nutzungsbedingungen einer Plattform können automatisierten Zugriff einschränken, und Sie sind für Ihre eigene Compliance verantwortlich. Wo die von Ihnen erhobenen Daten personenbezogene Informationenen enthalten, stellen Sie sicher, dass Sie eine rechtmäßige Grundlage dafür gemäß DSGVO, CCPPA oder den entsprechenden Regeln Ihrer Rechtsordnung haben.

HasData-Links

Entwicklung

Dieses Repository ist Konfiguration und Dokumentation für einen entfernten Server. Es gibt keinen Build-Schritt und nichts zu containerisieren.

Die Tests in test/ prüfen den Tool-Vertrag, also den Teil, der ohne einen Commit hier brechen kann. Sie prüfen, dass ?apis=duckduckgo genau ein Tool zurückgibt, dass dessen Name sich nicht geändert hat, dass die in dieser README dokumentierten Parameter weiterhin mit den genannten Enums existieren und dass der verwendete Schlüssel tatsächlich akzeptiert wird. Diese letzte Prüfung führt eine echte Suche aus und kostet 10 Credits – das ist der Preis eines Kanarienvogels, der aus dem richtigen Grund fehlschlagen kann.

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

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

Dieselbe Suite läuft in CI bei jedem Push und planmäßig einmal pro Woche, weil sich die Upstream-Tool-Liste ändern kann, ohne dass jemand dieses Repository berührt. Ein Fehler bedeutet, dass sich die Tool-Liste verschoben hat, der Schlüssel nicht mehr funktioniert oder der Endpunkt nicht erreichbar war, und die Assertion-Meldung sagt, welche Ursache vorliegt.

Mitwirken

Korrekturen an der Parametertabelle und am Antwortbeispiel sind der nützlichste Beitrag, weil diese Teile dazu neigen, abzuweichen. Fügen Sie den von Ihnen durchgeführten Aufruf und die erhaltene Antwort hinzu. Pul Requests aus Forks führen die Suite ohne Schlüssel aus, und die Live-Cheks werden übersprungen, statt rot zu werden.

Lizenz

MIT. Siehe LICENSE.