ddg-search

単一障害点を持たないことを拒否するDuckDuckGo検索MCPサーバー。 1つのプロセス、多数のバックエンド、自動フェイルオーバー、正直なエラーメッセージ。

アイデア

ウェブ検索はコーディングエージェントにとって基幹インフラであり、退屈な形で失敗します。レート制限、ボット検出、VPSプロバイダーの一時的な障害など。ほとんどのサーバーはHTTPクライアントを1つ持って祈るだけです。このサーバーは各クエリを複数のバックエンド（このマシン上のローカル検索エンジンに加えて、実行している任意の数のリモートduckduckgo-mcp-serverインスタンス）にルーティングし、何かが応答するか予算が尽きるまで試行を続けます。

失敗したバックエンドはタイムアウトになります。正常に動作するバックエンドはより多くのトラフィックを受け取ります。結果は1つのコンパクトなブロックとして、誰が提供したかの1行のメモ付きで届きます。

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はコンテンツフィルタリングのみです。ボット検出には何の効果もなく、リサーチを行うエージェントは想起率を求めており chaperone を求めていないため、デフォルトではオフです。

ツール

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:の下に、どこで壊れたかを示すタグ付きでリストされます:

問題が発生したとき、ログパスが得られます

ルーターは「インターネットがいつものように振る舞っている」ことと「このツールが実際に壊れている」ことを区別します。タイムアウトと空の結果セットは単に[タグ]が付くだけです。しかし、試行がこちら側の壊れ方を意味する形で失敗した場合 — ローカル転送エラー、リモートバックエンドの不正な応答など — 応答は次のように終わります:

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

そのファイルには、再生と診断に必要なすべてが含まれています。正確なクエリと引数、失敗の詳細を含むすべての試行、およびその時点のバックエンドごとの状態のスナップショットです。必要に応じてDDG_SEARCH_LOGS_DIRを別の場所に指定してください。ログはタイムアウトや空の結果では決して書き込まれません。

status

バックエンドのテーブル: オンラインフラグ、この1分間の観測された試行数、最後のステータス、クールダウン期限。probe: trueを渡すと、キャッシュされた状態を信頼する代わりに実際にリモートバックエンドにpingを送信します。

設定

環境変数、すべてオプション:

バックエンドはsrc/ddg_search/config.pyにあります。デフォルトのフリートはlocal（このマシン）に加えて2つのリモートリレーです。自分のインフラに合わせてタプルを編集してください。

知っておくべき動作

• フェイルオーバーは、最近の試行が最も少ない健全なバックエンドを優先するため、トラフィックが1台の貧弱なボックスに集中するのではなく分散されます。

• クールダウンはバックエンドごとで時間制限付きです。タイムアウトはバックエンドを90秒間休ませ、ソフト障害は30秒間休ませます。1回の成功で即座にリセットされます。

• 状態はstate/router-state.jsonに再起動後も保持されます。記憶喪失にしたい場合は削除してください。サーバーは次回起動時に再作成します。

1つの癖には専用の段落が必要です。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ユニットがmullvad-excludeの背後で住宅用IP上でそのような出口を1つ実行するために使用するランチャーが含まれています — データセンターの出口が自宅の接続よりもひどいCAPTCHA処理を受ける場合に便利です。

開発

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 — もう半分: これらの検索が見つけたURLをローカルのCrawl4AIブラウザ経由で開く

• Model Context Protocol — 「MCP」の意味

• duckduckgo-mcp-server — 実際のスクレイピングを行う検索ライブラリ

ライセンス

MIT。