DuckDuckGo MCP

An MCP server that provides DuckDuckGo web search and webpage content extraction. It uses DuckDuckGo's HTML endpoint without an API key and returns search results and refined page content in a form that LLMs can consume directly.

This repository is a fork of nickclyde/duckduckgo-mcp-server modified for Goover MCP Hub deployment. The original only accepted transport settings as CLI arguments, which caused problems with Host header validation (421) and SSE streaming responses in container deployments. This repository adds environment-variable-based configuration and fixes four deployment-blocking issues.

Basic Information

Related MCP server: DuckDuckGo MCP Server

Introduction

English

DuckDuckGo MCP provides web search and webpage content extraction without requiring any API key. It scrapes DuckDuckGo's HTML endpoint and returns results formatted for LLM consumption, along with a fetch tool that strips navigation, headers, footers, scripts, and styles to return clean readable text with pagination support. Built-in sliding-window rate limiting protects both tools. SafeSearch level and default region are fixed at server startup by the operator and cannot be changed by an AI assistant. An optional browser backend uses curl_cffi's Chrome TLS impersonation to pass fingerprint-based bot filters. Outbound fetches are guarded against SSRF by default.

Korean

DuckDuckGo MCP is an MCP that provides web search and webpage content extraction without an API key. It scrapes DuckDuckGo's HTML endpoint to return results in a form LLMs can use directly, and the content extraction tool returns refined text with pagination after removing navigation, headers, footers, scripts, and styles. Both tools have sliding-window rate limiting applied. The SafeSearch level and default region are fixed by the operator at server startup and cannot be changed by an AI assistant. The optional browser backend passes bot filters by impersonating Chrome's TLS fingerprint using curl_cffi. Outbound URL access is protected by an SSRF guard by default.

Provided Tools (2)

This is a pure tool-based MCP that does not provide prompts or resources.

region can be specified per call as us-en, cn-zh, jp-ja, de-de, fr-fr, wt-wt, etc.; if left empty, the server default is used.

SSRF protection: fetch_content rejects URLs that resolve to loopback, private (RFC1918), link-local (including 169.254.169.254 cloud metadata), reserved, multicast, and unspecified addresses by default, and re-validates at every redirect hop. Only http/https are allowed. In trusted deployments that need internal host access, this can be disabled with DDG_ALLOW_PRIVATE_URLS=1. See SECURITY.md for details.

Changes from the Original

1. Transport settings could not be read from environment variables

The original only accepted --transport / --host / --port as CLI arguments (the only things read via os.getenv() were the DDG_* variables). It could not be started in environments like Rancher where container Arguments are difficult to set.

Added TRANSPORT / HOST / PORT environment variables as a fallback. The reason they don't have the DDG_ prefix is compatibility with the previous Node.js implementation that was in this spot.

The env vars are interpreted after parse_args(), not as argparse default=. This is to preserve the original guard that exits if host/port are given while transport is stdio. If set as default=os.getenv("HOST"), a stdio run would die immediately just because HOST happens to be set in the environment.

Also, argparse does not validate default values against choices, and the original transport branch had no else. So a typo like TRANSPORT=http would exit with code 0 without any log, making the cause hard to diagnose. Added explicit validation and an else fallback.

$ TRANSPORT=http python -m duckduckgo_mcp_server.server
error: Invalid TRANSPORT value(s) ['http']; choose from stdio, sse, streamable-http

TRANSPORT also accepts comma-separated multi-values (sse,streamable-http).

2. Enabling the Host allow-list blocked localhost

The issue where requests from external domains in container deployments were rejected with 421 Misdirected Request: Invalid Host header was already solvable with the original DDG_ALLOWED_HOSTS.

The problem came next. Passing explicit TransportSecuritySettings to FastMCP overwrites the SDK's localhost defaults (127.0.0.1:*, localhost:*, [::1]:*) entirely. So the moment a proxy host was added to the allow-list, all local access was blocked, silently killing Docker healthchecks and local probes.

Fixed to merge in the localhost patterns. As a side effect, this also fixed the issue where setting only DDG_ALLOWED_ORIGINS left allowed_hosts as an empty list, causing all Hosts to get 421.

DDG_ALLOWED_HOSTS=example.goover.ai:33284 로 기동 시

Host: example.goover.ai:33284 -> 200
Host: localhost:8000          -> 200   (수정 전 421)
Host: 127.0.0.1:8000          -> 200   (수정 전 421)
Host: attacker.example.com    -> 421   (차단 유지)

The SDK's Host matching only handles exact matches or port wildcards with a trailing :*. Putting * in the host does not mean "allow all hosts" — it only matches when the Host header is literally *. If you need to allow everything, use DDG_DISABLE_DNS_REBINDING_PROTECTION=1.

3. Blocking HTTP client could not read SSE responses

The Hub calls with a blocking HttpURLConnection, but since the POST response of streamable-http is an SSE stream, two symptoms occurred.

1. {"content":[{"type":"text","text":""}],"isError":false} — only the first SSE chunk (intermediate notification) was read and the stream was misjudged as ended

2. java.net.SocketException: Unexpected end of file from server — chunked/SSE parsing failure

Added two independent switches, both off by default.

• DDG_JSON_RESPONSE=1 — returns the POST response as a single application/json body without SSE frames

• DDG_DISABLE_PROGRESS_NOTIFICATIONS=1 — sends ctx.info/ctx.error to server logs instead of MCP communication

Measured results show that suppressing notifications alone does not fix symptom 2. It only reduces the number of events; the SSE frames themselves remain.

json_response must be set before calling mcp.streamable_http_app() — FastMCP creates and caches a session manager on the first call.

Even when suppressed, the messages remain in the server logs, and error details are also included in each tool's return value, so the client never misses a failure.

4. curl_cffi missing from the Docker image

The original Dockerfile only ran pip install ., omitting the [browser] extra. But the search backend default is auto, so without curl_cffi, the fallback could not work when DuckDuckGo's TLS fingerprint blocking (HTTP 202/403) occurred — it only returned a notice message. This was the cause of the "no results" symptom that reproduced especially with Korean queries.

RUN pip install --no-cache-dir --upgrade pip \
    && pip install --no-cache-dir ".[browser]"

Note — items cleaned up together

__version__ in src/duckduckgo_mcp_server/__init__.py was hardcoded to 0.1.1, out of sync with 0.6.1 in pyproject.toml. Changed it to read from the installed distribution metadata to eliminate the dual source.

Environment Variables

Read once at startup; not applied per request.

Transport (new)

CLI flags take precedence over environment variables.

Search Behavior

Network / Security

Client Compatibility (new)

How to Run

stdio (original method, kept as-is)

uvx duckduckgo-mcp-server

Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Claude Code:

claude mcp add ddg-search uvx duckduckgo-mcp-server

streamable HTTP (new, for Goover MCP Hub deployment)

# CLI 인자로
uvx duckduckgo-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

# 환경변수만으로 (Arguments를 넣기 어려운 환경)
TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 uvx duckduckgo-mcp-server

Search Backend (bot-block bypass)

DuckDuckGo's search endpoint can block httpx's TLS fingerprint and return an empty HTTP 202 (it inspects the JA3/TLS handshake regardless of User-Agent). The curl backend impersonates a Chrome handshake with curl_cffi to get past this.

Search defaults to auto, fetch_content defaults to httpx, and both can be overridden with the per-call backend argument.

uv pip install "duckduckgo-mcp-server[browser]"

It is already included in the Docker image.

Docker

Dockerfile

FROM python:3.13-slim

WORKDIR /app

COPY . /app

RUN pip install --no-cache-dir --upgrade pip \
    && pip install --no-cache-dir ".[browser]"

ENTRYPOINT ["python", "-m", "duckduckgo_mcp_server.server"]
CMD []

Local Build and Smoke Test

docker build --no-cache --platform linux/amd64 -t duckduckgo-mcp:latest .

docker run -d --name duckduckgo-mcp-test -p 8069:8000 \
  -e TRANSPORT=streamable-http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e DDG_REGION=wt-wt \
  -e DDG_SAFE_SEARCH=OFF \
  -e DDG_ALLOWED_HOSTS=example.goover.ai:33284,example.goover.ai:*,example.goover.ai \
  -e DDG_JSON_RESPONSE=1 \
  -e DDG_DISABLE_PROGRESS_NOTIFICATIONS=true \
  duckduckgo-mcp:latest

curl -s -X POST http://localhost:8069/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

The reason all three forms are included in DDG_ALLOWED_HOSTS is that it is unclear whether the client appends a port to the Host header. example.goover.ai and example.goover.ai:33284 are different values and do not match each other.

Verified items:

• initialize — starts with environment variables only, responds correctly

• tools/list — returns search and fetch_content correctly

• tools/call(search) — succeeds with both English and Korean queries, no 202 even with 5 rapid consecutive calls

• tools/call(fetch_content) — successfully extracts content from a real page

• Host header probes with 4 variants — allowed hosts, localhost, and 127.0.0.1 return 200; unregistered hosts return 421

• 4 response format combinations — correctly switches between application/json / text/event-stream depending on DDG_JSON_RESPONSE

Development

uv sync                                                    # 의존성 설치
uv run duckduckgo-mcp-server                               # 실행
mcp dev src/duckduckgo_mcp_server/server.py                # MCP Inspector

uv run python -m pytest src/duckduckgo_mcp_server/ -v      # 전체 테스트 (106개)
uv run ruff check .                                        # 린트 (CI quality 잡과 동일)

CI runs pytest on Python 3.10–3.14 via GitHub Actions, plus ruff check (blocking) and pip-audit (non-blocking).

Notable Features of This Fork

• The original was documented for stdio-only use, and HTTP transport settings were only exposed as CLI arguments, making container deployment difficult to start at all.

• Removed the failure mode where an invalid TRANSPORT value exited with code 0 without any log. The cause was that argparse does not validate default values against choices.

• Fixed the bug where setting the Host allow-list overwrote the SDK's localhost defaults, silently blocking local probes. This issue does not surface until the allow-list is enabled.

• Confirmed by measurement that blocking HTTP client compatibility requires changing the response format itself (json_response), not just suppressing notifications, and provides both switches.

• No local state at all, so no PVC is needed; no authentication or API keys either, so there are no credential management issues.

• Root cause note: until the Hub's HTTP client is replaced with a stack that natively supports SSE streaming (such as Spring WebClient), the same problem will recur whenever connecting another MCP that sends progress notifications. Item 3 is a server-side workaround.

License

Follows the MIT license of the original repository (nickclyde/duckduckgo-mcp-server) (Copyright (c) 2025 Nick Clyde). Please check the LICENSE file before redistribution or commercial use.