ddg-search

一个拒绝单点故障的 DuckDuckGo 搜索 MCP 服务器。一个进程，多个后端，自动故障转移，诚实的错误信息。

理念

网络搜索是编码代理的承重基础设施，而它总是以乏味的方式失败：速率限制、机器人检测、你的 VPS 提供商一时抽风。大多数服务器只给你一个 HTTP 客户端，然后寄希望于运气。这个服务器会把每个查询路由到多个后端——本机上的本地搜索器，加上你碰巧运行的任意数量的远程 duckduckgo-mcp-server 实例——并持续尝试，直到有响应或预算耗尽。

失败的后端会被超时隔离。表现良好的后端会获得更多流量。你得到的结果是一个紧凑的块，附有一行说明，注明是哪个后端提供的。

Related MCP server: DuckDuckGo Search MCP Server

安装

需要 Python 3.10+ 和 uv。

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

这就是全部仪式。uv sync 会创建 .venv、锁定依赖，并以可编辑模式安装包，因此对 src/ 的修改会在重启后生效。

接入你的代理

任何支持 stdio 的 MCP 客户端都可以。对于 mcp.json 风格的配置：

{
  "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 仅用于内容过滤——它对机器人检测毫无作用，而且默认关闭，因为做研究的代理想要的是召回率，而不是一个监护人。

工具

search

结果有意以紧凑形式返回：

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

每个响应都会说明是哪个后端提供的。失败的尝试会列在 Attempts: 下，并带有一个标签，告诉你它是在哪里出错的：

当事情出错时，你会得到一个日志路径

路由器会区分“互联网只是在做互联网该做的事”和“这个工具真的坏了”。超时和空结果集只会得到它们的 [tag]。但当一次尝试以意味着我们这边出了问题的方式失败时——本地传输错误、远程后端响应异常——响应会以如下内容结尾：

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

该文件包含重放和诊断所需的一切：确切的查询和参数、每次尝试及其失败详情，以及当时每个后端状态的快照。如果你愿意，可以把 DDG_SEARCH_LOGS_DIR 指向其他位置；超时或空结果永远不会写入日志。

status

后端表：在线标志、本分钟观察到的尝试次数、最后状态、冷却到期时间。传入 probe: true 可以实际 ping 远程后端，而不是信任缓存状态。

配置

环境变量，全部可选：

后端位于 src/ddg_search/config.py。默认舰队是 local（本机）加上两个远程中继；编辑该元组以匹配你自己的基础设施。

值得了解的行为

• 故障转移优先选择健康且近期尝试次数最少的后端，这样流量会分散开来，而不是猛击一个可怜的盒子。

• 冷却按后端分别计时且有时间上限：超时让后端休息 90 秒，软失败休息 30 秒。一次成功会立即清零。

• 状态在重启后仍会保留在 state/router-state.json 中。如果你想要失忆，就删除它；服务器会在下次启动时重新创建。

有一个怪癖值得单独说一段。DuckDuckGo 会向它不信任的客户端提供空页面，因此“无结果”可能意味着真的没有匹配，也可能是悄无声息的机器人标记——路由器无法区分这两者，它也不会假装能区分。它把空结果视为失败，并尝试下一个后端；如果每个后端都返回空结果，你会看到一个横幅，明确说明这有多模棱两可。

最后一件事：30 次/分钟的请求上限由每个 duckduckgo-mcp-server 实例强制执行，而不是在这里。路由器会在后端之间分散负载，但它不会谎称舰队并不具备的容量。

运行你自己的中继

任何能运行标准服务器的机器都可以作为后端：

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

将 BackendConfig(url="http://that-host/ddg-mcp") 指向它。realip/ 目录包含一个启动器，systemd 单元用它来在住宅 IP 上通过 mullvad-exclude 运行这样一个出口——如果你的数据中心出口比家庭连接遭受更糟糕的验证码待遇，这会很有用。

开发

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

通过完整路由器进行快速手动冒烟测试：

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

另请参阅

• fast-webfetch-mcp — 另一半：通过本地 Crawl4AI 浏览器打开这些搜索找到的 URL

• Model Context Protocol — “MCP”的含义

• duckduckgo-mcp-server — 底层实际执行抓取的搜索库

许可证

MIT。