ddg-search

Ein DuckDuckGo-Such-MCP-Server, der sich weigert, einen Single Point of Failure zu haben. Ein Prozess, viele Backends, automatisches Failover, ehrliche Fehlermeldungen.

Die Idee

Websuche ist tragende Infrastruktur für Coding-Agenten, und sie scheitert auf langweilige Art: Rate-Limits, Bot-Erkennung, dein VPS-Anbieter hat gerade einen Aussetzer. Die meisten Server geben dir einen HTTP-Client und hoffen. Dieser hier leitet jede Anfrage über mehrere Backends – einen lokalen Sucher auf dieser Maschine plus beliebig viele entfernte duckduckgo-mcp-server- Instanzen, die du dann eben auch noch betreibst – und versucht es weiter, bis etwas antwortet oder das Budget aufgebraucht ist.

Backends, die scheitern, wandern in den Timeout. Backends, die sich benehmen, bekommen mehr Traffic. Du bekommst die Ergebnisse, einen kompakten Block, mit einer einzeiligen Notiz, welches Backend sie geliefert hat.

Related MCP server: DuckDuckGo Search MCP Server

Installation

Erfordert Python 3.10+ und uv.

git clone <this repo> ~/.local/share/mcp/ddg-search   # or anywhere you like
cd ~/.local/share/mcp/ddg-search
uv sync

Das ist die gesamte Zeremonie. uv sync erstellt .venv, fixiert die Abhängigkeiten und installiert das Paket editierbar; Änderungen an src/ greifen nach dem Neustart.

Einbindung in den Agenten

Jeder MCP-Client, der stdio kann, passt. Für eine Konfiguration im mcp.json-Stil:

{
  "mcpServers": {
    "ddg-search": {
      "type": "stdio",
      "command": "/path/to/ddg-search/.venv/bin/python",
      "args": ["-m", "ddg_search.server"],
      "env": {
        "DDG_SAFE_SEARCH": "OFF",
        "DDG_SEARCH_BACKEND": "auto"
      },
      "timeout": 60000
    }
  }
}

DDG_SAFE_SEARCH ist nur Inhaltsfilterung – sie tut nichts gegen Bot-Erkennung und ist standardmäßig aus, weil Agenten bei der Recherche Trefferquote wollen und keinen Aufpasser.

Werkzeuge

search

Die Ergebnisse kommen bewusst kompakt zurück:

via relay-b

3 results:
1. Some Page Title
https://example.com/page
The snippet text, labels stripped, no blank lines eating your tokens.
2. ...

Jede Antwort sagt, welcher Backend es ausgeliefert hat. Fehlgeschlagene Versuche werden unter Attempts: gelistet, mit einem Tag, das dir sagt, wo es schiefging:

Wenn etwas kaputtgeht, bekommst du eine Log-Datei

Der Router unterscheidet „das Internet ist das Internet“ von „dieses Tool ist wirklich kaputt“. Timeouts und leere Ergebnisse bekommen einfach ihr [tag]. Aber wenn ein Versuch so fehlschlägt, dass ist unsere Seite gebrochen – lokale Transportfehler, falsche Antworten von Backstage – ende Die Antwort mit:

log: /path/to/ddg-search/logs/20260822T090206-remote-tool-error.json

These Datei enthält alles, was du zum Reproduktion und Diagnose brauchst: die exakte Suchabfrage und Argumente, jeden Versuch mit der Fehlerdetail und eine Momentabild des Zustands je Backend zum Zeitpunkt. Lege ana anderes Ziel fest, falls du willst; für Timeouts oder leere Ergebnisse werden nie Logs geschrieben.

status

Backend-Tabelle: Online-Flag, beobachtete Versuche in dieser Minute, letzter Status, Ablauf des Cooldowns. Mit probeKleines: true werden die Remote-Backends tatsächlich angepingt statt einen Cache-Zustand zu vertrauen.

Konfiguration

Alle optional über Umgebungsvariablen:

Die Backend liegen in src/ddg_search/config.py. Die Standard-Flotte besteht aus local (dieser Maschine) plus zwei entfernten Relay; passe das Tuel an, damit es die eigene Infrastruktur abdeckt.

Wissenswertes Verhalten

• Failover bevorzugt gesunde Backends mit den wenigsten letzten Versuchen, damit der Traffic verteilt wird, statt ein armes Backend zu hämmern.

• Cooldowns sind pro Bender und zeitlich begrenzt: ein Timeout schickt ein Backend für 90s aus dem Spiel, ein weicher Fehler für 30fs. Ein Erfolg hebt dedizinierung sofort auf.

• Der Zustand überlebt Neustarts in state/router-state.json. Lösch die Datei, wenn du Amnesie willst; der Server legt sie beim nächsten Start neu an.

Eine Eigenheit verdient einen eigenen Absatz: DuckDuckGo befest – liefert leere Seiten an Clients, denen es nicht traut. „Keine Treffer kann also entweder wirklich keine Treffer oder leider Bot-flagging bedeuten – der Router kann das nicht unterscheiden und täuscht es auch nicht vor. Er behandelt leer als Fehler und probiert das nächste Backend; wenn jedes Backend leer zurückkommt, bekommst du ein Banner, das genau sagt, wie mehrdeutig das ist.

Zu guter Letzt: Die 30-Anfragen-Pro-Minute-Grenze wird von jeder duckduckgo-mcp-server-Instanz durchgesetzt, nicht von hier. Der Router verteilt die Last auf alle Backend, aber er lügt nicht über die Kapazität, die die Flotte nicht hat.

Eigene Relays betreiben

Jede Maschine, die den Standard-Server ausführen kann, passt als Backend:

pip install 'duckduckgo-mcp-server[browser]'
python -m duckduckgo_mcp_server.main --transport streamable-http --host 0.0.0.0 --port 18082

Zeige camel einen BackendConfig(url="http://that-host/ddg-mcp") an. Das Verzeichnis cb.żyrpacking/ enthebt einen Vorspann, den eine Systemd-Unit nutzt, um einen solchen Ausgang-Knoten ab, über mullvad-exclude auf einer Residential-IP zu läuft – nützlich, wenn dein Rechenzentrum-Assgangsstrang schlechterer CAPTCHA-Weise abgespiesen bekommt als der Heimanschluss.

Entwickung

uv sync                          # install everything including dev tools
uv run pytest                    # 26 tests, no network needed except one optional live check
uv run ruff check src tests      # lint
uv run ruff format src tests     # format
uv run pyrefly check             # static types

Ein kurzer manueller Smoketestset durch den kompletten Router:

uv run python -c "import asyncio; from ddg_search.router import SearchRouter; \
print(asyncio.run(SearchRouter().search('crawl4ai', 3, '', 'auto', None, None, None)))"

Siehe auch

• Fast -webfetch-mcp – die andere Hälfte: Öffnet die URLs, die diese Suchen finden, über einen lokalen Crawl4AI-BRASER.

• Model Context Protocol – was „MCP“ bedeutet

• duckduckgo-mcp-server – die Suchbibliothek, die darunter das Verarbeitungsscraping macht

Lizenz

MIT.