ddg-search

A DuckDuckGo search MCP server that refuses to have a single point of failure. One process, many backends, automatic failover, honest error messages.

The idea

Web search is load-bearing infrastructure for coding agents, and it fails in boring ways: rate limits, bot detection, your VPS provider having a moment. Most servers give you one HTTP client and hope. This one routes each query across several backends — a local searcher on this machine plus any number of remote duckduckgo-mcp-server instances you happen to run — and keeps trying until something answers or the budget runs out.

Backends that fail get put in timeout. Backends that behave get more traffic. You get the results, one compact block, with a one-line note of who served it.

Install

Requires Python 3.10+ and uv.

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

That is the whole ceremony. uv sync creates .venv, locks dependencies, and installs the package editable, so edits to src/ apply on restart.

Wire it into your agent

Any MCP client that speaks stdio works. For an mcp.json-style config:

{
  "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 is content filtering only — it does nothing against bot detection, and it is off by default because agents doing research want recall, not a chaperone.

Tools

search

Argument	Type	Default	Notes
query	string	required	Exact nouns beat vague one-word vibes
max_results	int	10	Upstream caps around 10–11 regardless
region	string	""	DuckDuckGo region code
route_mode	"auto" | "manual"	"auto"	Manual skips health sorting
target	string	""	One backend name/alias/IP (manual mode)
targets	list	null	Ordered fallback chain (manual mode)

Results come back compact on purpose:

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. ...

Every response states which backend served it. Failed attempts are listed under Attempts: with a tag telling you where it broke:

Tag	Meaning
[empty]	DuckDuckGo returned zero matches — genuine no-results or bot-empty, indistinguishable from here
[local] / [local-transport]	This machine's client failed. Do not blame the remote hosts
[remote-tool-error] / [remote-rpc]	A remote answered badly
[timeout]	The 25s budget ran out while waiting

When things break, you get a log path

The router distinguishes "the internet is being the internet" from "this tool is actually broken". Timeouts and empty result sets just get their [tag]. But when an attempt fails in a way that means our side broke — local transport errors, remote backends answering badly — the response ends with:

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

That file holds everything needed to replay and diagnose: the exact query and arguments, every attempt with its failure detail, and a snapshot of per-backend state at the time. Point DDG_SEARCH_LOGS_DIR somewhere else if you want; logs are never written for timeouts or empty results.

status

Backend table: online flag, observed attempts this minute, last status, cooldown expiry. Pass probe: true to actually ping remote backends instead of trusting cached state.

Configuration

Environment variables, all optional:

Variable	Default	Purpose
DDG_SAFE_SEARCH	OFF	STRICT / MODERATE / OFF
DDG_SEARCH_BACKEND	auto	Local transport: httpx, curl, or auto (curl_cffi Chrome TLS fallback)
DDG_SEARCH_TIMEOUT_MS	25000	Total budget across all backends per query
DDG_SEARCH_TIMEOUT_COOLDOWN_MS	90000	Timeout penalty per backend
DDG_SEARCH_ERROR_COOLDOWN_MS	30000	Error penalty per backend
DDG_SEARCH_PROBE_TIMEOUT_MS	3000	Per-backend probe wait for status with probe: true
DDG_SEARCH_STATE_DIR	<repo>/state	Router state directory

Backends live in src/ddg_search/config.py. The default fleet is local (this machine) plus two remote relays; edit the tuple to match your own infrastructure.

Behavior worth knowing

• Failover prefers healthy backends with the fewest recent attempts, so traffic spreads instead of hammering one poor box.
• Cooldowns are per-backend and time-boxed: a timeout sits a backend out for 90s, a soft failure for 30s. One success clears the slate instantly.
• State survives restarts in state/router-state.json. Delete it if you want amnesia; the server recreates it on next boot.

One quirk deserves its own paragraph. DuckDuckGo serves empty pages to clients it does not trust, so "no results" can mean either genuinely no matches or quiet bot-flagging — the router cannot tell those apart, and it does not pretend to. It treats empty as failure and tries the next backend; if every backend comes back empty you get a banner saying exactly how ambiguous that is.

Last thing: the 30 requests/minute ceiling is enforced by each duckduckgo-mcp-server instance, not here. The router spreads load across backends, but it will not lie about capacity the fleet does not have.

Running your own relays

Any machine that can run the stock server works as a backend:

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

Point a BackendConfig(url="http://that-host/ddg-mcp") at it. The realip/ directory contains a launcher used by a systemd unit to run one such exit behind mullvad-exclude on residential IP — useful if your datacenter egress gets worse captcha treatment than your home connection.

Development

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

A quick manual smoke test through the full router:

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

See also

• fast-webfetch-mcp — the other half: opens the URLs these searches find, through a local Crawl4AI browser
• Model Context Protocol — what "MCP" means
• duckduckgo-mcp-server — the search library doing the actual scraping underneath

License

MIT.