DuckDuckGo Search MCP Server

DuckDuckGo Search MCP サーバー

DuckDuckGo を通じてウェブ検索機能を提供する Model Context Protocol（MCP）サーバーです。コンテンツの取得と解析の追加機能も備えています。

クイックスタート

uvx duckduckgo-mcp-server

機能

• ウェブ検索：高度なレート制限と検索結果のフォーマット機能を備えた DuckDuckGo 検索
• コンテンツ取得：インテリジェントなテキスト抽出によるウェブページコンテンツの取得と解析
• 長い URL の短縮：長すぎる検索結果 URL は短い ref:// トークンに置き換えられ、fetch_content にそのまま渡してコンテキストを節約できます
• レート制限：検索とコンテンツ取得の両方で、レート制限を防ぐ機能を内蔵
• エラー処理：包括的なエラー処理とログ記録
• LLM に適した出力：大規模言語モデルでの利用に特化した形式で結果を出力

インストール

uv を使用して PyPI からインストールします。

uv pip install duckduckgo-mcp-server

使用方法

Claude Desktop での実行

1. Claude Desktop をダウンロードします
2. Claude Desktop の設定を作成または編集します。
   • macOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows の場合：%APPDATA%\Claude\claude_desktop_config.json

次の設定を追加します。

基本設定（セーフサーチなし、デフォルトのリージョンなし）：

{
    "mcpServers": {
        "ddg-search": {
            "command": "uvx",
            "args": ["duckduckgo-mcp-server"]
        }
    }
}

セーフサーチとリージョンの設定あり：

{
    "mcpServers": {
        "ddg-search": {
            "command": "uvx",
            "args": ["duckduckgo-mcp-server"],
            "env": {
                "DDG_SAFE_SEARCH": "STRICT",
                "DDG_REGION": "cn-zh"
            }
        }
    }
}

設定オプション：

• DDG_SAFE_SEARCH：セーフサーチのフィルタリングレベル（任意）
  • STRICT：コンテンツを最大限にフィルタリング（kp=1）
  • MODERATE：バランスの取れたフィルタリング（kp=-1、指定がない場合のデフォルト）
  • OFF：コンテンツをフィルタリングしない（kp=-2）
• DDG_REGION：デフォルトのリージョン／言語コード（任意、以下に例を記載）
  • us-en：米国（英語）
  • cn-zh：中国（中国語）
  • jp-ja：日本（日本語）
  • wt-wt：特定のリージョンを指定しない
  • DuckDuckGo のデフォルトの動作を使用する場合は空欄にします
• DDG_CA_CERTS：送信リクエストの TLS 証明書を検証するために使用する PEM CA バンドルのパス（任意）。TLS を中継するプロキシ経由で接続する場合に必要です。TLS を中継するプロキシ経由での実行を参照してください。
• DDG_RATE_LIMIT_STRATEGY：sliding（デフォルト、従来の 60 秒ウィンドウ）または token_bucket（バースト後、平滑化）。
• DDG_SEARCH_RPM：1 分あたりの検索リクエスト数（デフォルト：30）。
• DDG_FETCH_RPM：1 分あたりの fetch_content リクエスト数（全体、デフォルト：20）。
• DDG_FETCH_HOST_RPM：ホストごとの取得上限（任意、デフォルト：0、無効）。有効にするには正の数を設定します。
• DDG_CACHE_TTL：解析済みページをメモリ内の fetch_content キャッシュに保持する秒数（デフォルト：300）。同じ URL のページネーションによる読み取りでは、1 回のダウンロードが再利用されます。無効にするには 0 を設定します。
• DDG_CACHE_MAX_ENTRIES：このキャッシュに保持するページの最大数（デフォルト：64）。最も古く使われていない項目から削除されます。無効にするには 0 を設定します。
• DDG_PARSE_MODE：fetch_content のデフォルトの抽出方法（text、main、または markdown）。デフォルトは text（従来のページ全体をフラット化した形式）です。呼び出しごとの parse_mode で上書きできます。
• DDG_REF_URL_THRESHOLD：この文字数を超える検索結果 URL は、短い ref://<id> トークンに置き換えられます（デフォルト：120）。常に完全な URL を表示するには 0 を設定します。--ref-url-threshold も使用できます。

3. Claude Desktop を再起動します

Claude Code での実行

1. Claude Code をダウンロードします
2. uvenv がインストールされ、uvx コマンドを使用できることを確認します
3. MCP サーバーを追加します：claude mcp add ddg-search uvx duckduckgo-mcp-server

SSE または Streamable HTTP での実行

サーバーは、ほかの MCP クライアントで使用できる代替トランスポートに対応しています。

# SSE transport
uvx duckduckgo-mcp-server --transport sse

# Streamable HTTP transport
uvx duckduckgo-mcp-server --transport streamable-http

デフォルトのトランスポートは stdio で、Claude Desktop と Claude Code で使用されます。

sse または streamable-http で実行する場合は、--host フラグと --port フラグでデフォルトのバインドアドレス（127.0.0.1:8000）を上書きします。

uvx duckduckgo-mcp-server --transport streamable-http --host 0.0.0.0 --port 7070

リバースプロキシの背後または Docker で実行する場合

MCP SDK は HTTP トランスポートで DNS リバインディング保護を有効にしており、デフォルトでは localhost の Host／Origin ヘッダーのみを受け付けます。リバースプロキシの背後やコンテナー内では、クライアントの Host ヘッダーが一致しないため、リクエストは 421 Misdirected Request で失敗します。

実際にクライアントが使用するホストとオリジンを許可リストに追加して修正してください（保護を無効にするよりも、この方法を推奨します）。値には host、host:port、ワイルドカードポートの host:* を指定できます。

uvx duckduckgo-mcp-server --transport streamable-http --host 0.0.0.0 --port 7070 \
  --allowed-hosts ddg-mcp.example.com "ddg-mcp.example.com:*" \
  --allowed-origins "https://ddg-mcp.example.com"

同等の環境変数（カンマ区切り）も使用できます：DDG_ALLOWED_HOSTS、DDG_ALLOWED_ORIGINS。

最終手段として、--disable-dns-rebinding-protection（または DDG_DISABLE_DNS_REBINDING_PROTECTION=1）でチェック全体を無効にできます。保護を無効にすると、DNS リバインディング攻撃に対する防御が失われるため、許可リストの使用を推奨します。何も設定されていない場合は、安全な localhost のみを許可するデフォルトが維持されます。

TLS を傍受するプロキシの背後で実行する場合

独自の CA で HTTPS トラフィックを再署名する企業プロキシ（HTTPS_PROXY 経由）を使用すると、HTTP クライアントがプロキシの自己署名 CA を信頼しないため、送信リクエストが証明書検証エラーで失敗します（また、httpx は SSL_CERT_FILE 環境変数を読み取らなくなりました）。サーバーがプロキシの CA バンドルを使用するように設定してください。

uvx duckduckgo-mcp-server --ca-certs /path/to/proxy-ca.pem

または DDG_CA_CERTS=/path/to/proxy-ca.pem を設定します。このバンドルは、httpx と curl の両方のバックエンドで、search ツールと fetch_content ツールに使用されます。

最終手段として、--no-ssl-verify（または DDG_SSL_VERIFY=0）を指定すると、証明書検証を完全に無効にできます。これにより、ネットワーク経路上の誰もがトラフィックを傍受できる状態になるため、--ca-certs の使用を推奨します。

バックエンド（ボット検出の回避）

一部のサイトは、最近では DuckDuckGo 独自の検索エンドポイント（html.duckduckgo.com）も、特徴的な TLS フィンガープリントを理由に、User-Agent に関係なくデフォルトの httpx クライアントをブロックします。Cloudflare Bot Management などのフィルターはヘッダーではなく JA3／TLS ハンドシェイクを判定するため、html.duckduckgo.com が httpx に空の HTTP 202 ページを返し、何も通知されないまま「検索結果なし」になる場合があります。オプトインで使用できるバックエンドの curl（curl_cffi 経由で実装）は、実際の Chrome ブラウザーの TLS ハンドシェイクを偽装し、こうしたチェックを通過します。

search ツールと fetch_content ツールの両方で、これらのバックエンドを使用できます。

インストール：

# Default install (httpx only)
uv pip install duckduckgo-mcp-server

# With the optional browser backend
uv pip install "duckduckgo-mcp-server[browser]"

バックエンドのオプション：

値	動作	[browser] が必要
httpx	軽量な非同期 HTTP です。デフォルトです。ほとんどのサイトで動作します。	いいえ
curl	Chrome 131 の TLS 偽装に curl_cffi を使用します。TLS フィンガープリントベースのフィルターを通過します。	はい
auto	最初に httpx を試し、403 または Cloudflare チャレンジ応答が返された場合は curl で再試行します。	はい

バックエンドの設定方法は 2 つあります：

1. サーバー全体のデフォルトを --fetch-backend CLI フラグで設定します（すべての fetch_content 呼び出しに適用されます）。

   # Default behavior — uses httpx
   uvx duckduckgo-mcp-server
   
   # Force curl for every fetch (requires the [browser] extra)
   uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend curl
   
   # Try httpx first, fall back to curl on 403 / Cloudflare challenge
   uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend auto
   

2. fetch_content ツールの backend 引数で呼び出しごとに上書きします（その呼び出しに限り CLI のデフォルトを上書きします）。ツールの入力スキーマで backend が公開されるため、MCP クライアントはフェッチごとに "httpx"、"curl"、または "auto" を選択できます。

fetch_content のデフォルトは httpx のままです。偽装が不要なユーザーに追加の依存関係が生じないようにするためです。

検索バックエンド

DuckDuckGo の検索エンドポイントが通常の httpx をフィンガープリントによってブロックするようになったため、search ツールはデフォルトで auto を使用します。まず httpx を試し、ブロック（HTTP 202/403）を検出すると curl にフォールバックします。このフォールバックは [browser] エクストラがインストールされている場合にのみ機能します。インストールされていない場合、検索結果としてインストールを促すメッセージが返されます。

--search-backend CLI フラグまたは DDG_SEARCH_BACKEND 環境変数で検索バックエンドを設定します（auto（デフォルト）／httpx／curl）。

# Recommended: install the browser extra so the auto fallback can impersonate Chrome
uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server

# Force curl for every search
uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --search-backend curl

# Opt out of the fallback (legacy behavior — may return no results while blocked)
uvx duckduckgo-mcp-server --search-backend httpx

開発

ローカルで開発する場合：

# Install dependencies
uv sync

# Run with the MCP Inspector
mcp dev src/duckduckgo_mcp_server/server.py

# Install locally for testing with Claude Desktop
mcp install src/duckduckgo_mcp_server/server.py

# Run all tests
uv run python -m pytest src/duckduckgo_mcp_server/ -v

# Run only unit tests
uv run python -m pytest src/duckduckgo_mcp_server/test_server.py -v

# Run only e2e tests
uv run python -m pytest src/duckduckgo_mcp_server/test_e2e.py -v

利用可能なツール

1. 検索ツール

async def search(query: str, max_results: int = 10, region: str = "") -> str

DuckDuckGo でウェブ検索を行い、整形された検索結果を返します。

パラメーター：

• query：検索クエリ文字列
• max_results：返す検索結果の最大数（デフォルト：10）
• region：（任意）デフォルトを上書きする地域／言語コード。設定済みのデフォルト地域を使用する場合は空欄にします。

地域コードの例：

• us-en：米国（英語）
• cn-zh：中国（中国語）
• jp-ja：日本（日本語）
• de-de：ドイツ（ドイツ語）
• fr-fr：フランス（フランス語）
• wt-wt：特定の地域を指定しない

戻り値： タイトル、URL、スニペットを含む検索結果を整形した文字列。

使用例：

• デフォルト設定で検索：search("python tutorial")
• 地域を指定して検索：日本語のニュースを検索する場合は search("latest news", region="jp-ja")

2. コンテンツ取得ツール

async def fetch_content(
    url: str,
    start_index: int = 0,
    max_length: int = 8000,
    backend: Optional[str] = None,
    parse_mode: Optional[str] = None,
) -> str

ウェブページからコンテンツを取得して解析します。

パラメーター：

• url：コンテンツを取得するウェブページの URL、または検索結果の ref://<id> トークン
• start_index：読み取りを開始する文字オフセット（ページ分割用）
• max_length：返す文字数の最大値
• backend：任意の呼び出しごとのデフォルト取得バックエンドの上書き（"httpx"、"curl"、または "auto"）。省略した場合、サーバー起動時に --fetch-backend で設定した値が使用されます。
• parse_mode：任意の呼び出しごとの抽出方法（"text"、"main"、または "markdown"）。省略した場合、DDG_PARSE_MODE／--parse-mode の設定値（デフォルトは text）が使用されます。

戻り値： ウェブページから取得した、整理・整形済みのテキストコンテンツ。解析済みのページ全体はメモリー内にキャッシュされます（デフォルトで5分）。そのため、後続のページを start_index で取得する際に再ダウンロードする必要はありません。キャッシュが有効な場合、メタデータには cache=hit または cache=miss が含まれます。

SSRF 保護： デフォルトでは、fetch_content はループバック、プライベート（RFC1918）、リンクローカル（クラウドのメタデータエンドポイント 169.254.169.254 を含む）、予約済み、マルチキャスト、または未指定のアドレスに解決される URL を拒否し、リダイレクトの各段階でも再検証します。許可されるのは http／https URL のみです。内部ホストを取得する必要がある信頼できるローカル環境では、DDG_ALLOW_PRIVATE_URLS=1 または --allow-private-urls でこの保護を無効にできます。詳細は SECURITY.md を参照してください。

3. リンク展開ツール

async def expand_link(token: str) -> str

検索結果では、DDG_REF_URL_THRESHOLD 文字（デフォルトは120文字）を超える URL を、短く安定した ref://<id> トークンに置き換えます。これにより、トラッキング情報を含む長いリンクがコンテキストを圧迫するのを防ぎます。fetch_content では URL の代わりにトークンを指定できます。そのため、実際のリンクを表示または引用する必要がある場合にのみ、このツールを使います。

パラメーター：

• token：検索結果に表示されたものと完全に一致する ref://<id> トークン（ID のみでも使用できます）

戻り値： 元の URL 全体。トークンが不明な場合はエラーが返されます。トークンはサーバープロセスの稼働中、メモリー内に保持され（LRU 上限あり）、再起動すると破棄されます。

機能の詳細

レート制限

• 検索：デフォルトで1分あたり30リクエスト（DDG_SEARCH_RPM / --search-rpm）
• コンテンツ取得：全体で1分あたり20リクエスト（DDG_FETCH_RPM / --fetch-rpm）
• ホストごとの取得上限も設定できます。デフォルトでは無効です（DDG_FETCH_HOST_RPM / --fetch-host-rpm）
• 戦略：DDG_RATE_LIMIT_STRATEGY / --rate-limit-strategy で sliding（デフォルト）または token_bucket を指定します
• HTTP 429 レスポンスでは Retry-After に従って（上限30秒）、1回再試行します
• fetch_content のキャッシュヒット時は、ダウンロードと取得レート制限の両方がスキップされます

コンテンツキャッシュ

• ページ全体を解析した結果をメモリ内に TTL キャッシュします（ページネーション前）
• デフォルトの TTL は300秒、エントリ数は64で、最も古く使われたエントリから削除されます
• エラーはキャッシュされません
• DDG_CACHE_TTL / DDG_CACHE_MAX_ENTRIES または --cache-ttl / --cache-max-entries で設定できます
• いずれかの値を 0 にすると無効になります

結果の処理

• 広告と無関係なコンテンツを削除します
• DuckDuckGo のリダイレクト URL を整理します
• LLM が最適に利用できる形式で結果を整えます
• 長いコンテンツを適切に切り詰めます

コンテンツ解析モード

fetch_content は parse_mode を受け付けます。

モード	動作
text	従来のデフォルトです。ページの不要部分を除去し、ページテキストを平坦化して返します。
main	主要な article / main / コンテンツコンテナーのみを保持します。
markdown	同じ主要コンテンツを、軽量な Markdown（見出し、リスト、リンク、コード）として表示します。

コンテンツの安全性

• セーフサーチフィルタリング：サーバー起動時に DDG_SAFE_SEARCH 環境変数で設定します

  • 管理者が制御し、AI アシスタントは変更できません
  • 選択したレベルに基づいて不適切なコンテンツをフィルタリングします
  • DuckDuckGo の公式 kp パラメーターを使用します

• 地域のローカライズ：

  • デフォルトの地域は DDG_REGION 環境変数で設定します
  • AI アシスタントは検索リクエストごとに上書きできます
  • 特定の地理的地域における結果の関連性を高めます

エラー処理

• エラーを包括的に捕捉して報告します
• MCP コンテキストを通じて詳細にログを記録します
• レート制限やタイムアウト時も適切に機能を縮退させます

コントリビューション

Issue とプルリクエストを歓迎します！

ライセンス

このプロジェクトは MIT License の下でライセンスされています。

Star の履歴