DuckDuckGo MCP

MCP-сервер, предоставляющий веб-поиск DuckDuckGo и извлечение содержимого веб-страниц. Использует HTML-эндпоинт DuckDuckGo без API-ключа и возвращает результаты поиска и очищенный текст страниц в виде, готовом для непосредственного потребления LLM.

Этот репозиторий — форк nickclyde/duckduckgo-mcp-server с изменениями для развёртывания в Goover MCP Hub. В оригинале настройка transport принималась только через CLI-аргументы, а при контейнерном развёртывании возникали проблемы с проверкой Host-заголовка (421) и SSE-стримингом ответов. В этом репозитории добавлена настройка через переменные окружения и исправлены четыре проблемы, блокировавшие развёртывание.

Основная информация

Related MCP server: DuckDuckGo MCP Server

Введение

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.

На русском

DuckDuckGo MCP — это MCP, предоставляющий веб-поиск и извлечение содержимого веб-страниц без API-ключа. Он скрейпит HTML-эндпоинт DuckDuckGo и возвращает результаты в виде, готовом для непосредственного использования LLM, а инструмент извлечения содержимого возвращает очищенный текст с удалёнными навигацией, заголовками, подвалами, скриптами и стилями, вместе с поддержкой пагинации. К обоим инструментам применяется rate limit на основе скользящего окна. Уровень SafeSearch и регион по умолчанию фиксируются оператором при запуске сервера, и AI-ассистент не может их изменить. Опциональный браузерный бэкенд использует маскировку TLS-отпечатка Chrome от curl_cffi для обхода бот-фильтров. Внешние URL-запросы по умолчанию защищены SSRF-гардом.

Предоставляемые инструменты (2 шт.)

Это чисто инструмент-ориентированный MCP без промптов и ресурсов.

region можно указать для каждого вызова: us-en, cn-zh, jp-ja, de-de, fr-fr, wt-wt и т.д. Если оставить пустым, используется значение по умолчанию с сервера.

Защита от SSRF: fetch_content по умолчанию отклоняет URL, которые разрешаются в loopback, частные (RFC1918), link-local (включая 169.254.169.254 — метаданные облака), reserved, multicast и unspecified адреса, и повторно проверяет каждый хоп редиректа. Разрешены только http/https. В доверенных развёртываниях, где требуется доступ к внутренним хостам, можно отключить с помощью DDG_ALLOW_PRIVATE_URLS=1. Подробнее см. SECURITY.md.

Изменения относительно оригинала

1. Настройка transport не принималась через переменные окружения

В оригинале --transport / --host / --port принимались только как CLI-аргументы (через os.getenv() читались только переменные DDG_*). В таких средах, как Rancher, где сложно задать Arguments контейнера, запуск был невозможен.

Добавлены переменные окружения TRANSPORT / HOST / PORT в качестве fallback. Отсутствие префикса DDG_ связано с совместимостью с предыдущей Node.js-реализацией, которая была на этом месте.

env обрабатывается после parse_args(), а не через default= в argparse. Это нужно, чтобы сохранить оригинальную защиту "если заданы host/port, а transport — stdio, то выход". Если вставить default=os.getenv("HOST"), то при наличии HOST в окружении stdio-запуск немедленно завершится.

Кроме того, argparse не проверяет значения по умолчанию через choices, а в оригинальной ветке transport не было else. Поэтому опечатка вроде TRANSPORT=http приводила к завершению с exit 0 без каких-либо логов, и причину было трудно найти. Добавлены явная проверка и защита через else.

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

TRANSPORT также принимает мультизначения через запятую (sse,streamable-http).

2. При включении allow-list хостов блокировался localhost

Проблема, когда при контейнерном развёртывании запросы с внешних доменов отклонялись с 421 Misdirected Request: Invalid Host header, решается уже существовавшим в оригинале DDG_ALLOWED_HOSTS.

Проблема была дальше. Если передать FastMCP явный TransportSecuritySettings, то значения localhost по умолчанию из SDK (127.0.0.1:*, localhost:*, [::1]:*) полностью перезаписываются. Поэтому как только прокси-хост попадал в allow-list, весь локальный доступ блокировался, и docker healthcheck или локальные пробы молча умирали.

Исправлено слиянием localhost-паттернов. Попутно решена проблема, когда при установке только DDG_ALLOWED_ORIGINS allowed_hosts становился пустым списком и все Host получали 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   (차단 유지)

Сопоставление Host в SDK работает только при точном совпадении или wildcard по порту с суффиксом :*. Даже если поставить * в баре, это не означает "разрешить все хосты" — Host-заголовок будет сопоставляться только если он буквально равен *. Если нужно разрешить всё, используйте DDG_DISABLE_DNS_REBINDING_PROTECTION=1.

3. Блокирующий HTTP-клиент не мог читать SSE-ответы

Hub вызывает через блокирующий HttpURLConnection, а поскольку POST-ответ streamable-http — это SSE-поток, возникали два симптома.

1. {"content":[{"type":"text","text":""}],"isError":false} — читался только первый SSE-чанк (промежуточное notification) и ошибочно считалось, что поток завершён

2. java.net.SocketException: Unexpected end of file from server — сбой парсинга chunked/SSE

Добавлены два независимых переключателя, оба по умолчанию выключены.

• DDG_JSON_RESPONSE=1 — возвращает POST-ответ как единое тело application/json без SSE-фреймов

• DDG_DISABLE_PROGRESS_NOTIFICATIONS=1 — отправляет ctx.info/ctx.error в логи сервера вместо MCP-коммуникации

По результатам измерений только подавление notification не решает симптом 2. Количество событий уменьшается, но сами SSE-фреймы остаются.

json_response нужно устанавливать до вызова mcp.streamable_http_app() — потому что FastMCP создаёт и кэширует менеджер сессий при первом вызове.

Даже при подавлении сообщения остаются в логах сервера, а содержимое ошибок также попадает в возвращаемое значение каждого инструмента, так что клиент не пропустит сбой.

4. В Docker-образе отсутствовал curl_cffi

Оригинальный Dockerfile выполнял только pip install ., пропуская extra [browser]. Но значение по умолчанию для поискового бэкенда — auto, поэтому без curl_cffi при блокировке TLS-отпечатка DuckDuckGo (HTTP 202/403) fallback не срабатывал и возвращалось только информационное сообщение. Это была причина симптома "нет результатов", который воспроизводился особенно с корейскими запросами.

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

Справочно — попутно исправленный пункт

__version__ в src/duckduckgo_mcp_server/__init__.py был жёстко закодирован как 0.1.1 и расходился с 0.6.1 из pyproject.toml. Изменено на чтение из метаданных установленного дистрибутива, чтобы устранить двойной источник.

Переменные окружения

Читаются один раз при запуске, для отдельных запросов не применяются.

Transport (новое)

CLI-флаги имеют приоритет над переменными окружения.

Поведение поиска

Сеть / безопасность

Совместимость с клиентами (новое)

Способы запуска

stdio (оригинальный способ, сохранён)

uvx duckduckgo-mcp-server

Настройка Claude Desktop (~/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 (новое, для развёртывания в Goover MCP Hub)

# 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

Поисковый бэкенд (обход бот-блокировки)

Поисковый эндпоинт DuckDuckGo может блокировать TLS-отпечаток httpx и возвращать пустой HTTP 202 (проверяется JA3/TLS-рукопожатие независимо от User-Agent). Бэкенд curl маскирует рукопожатие Chrome через curl_cffi и проходит эту проверку.

Для поиска значение по умолчанию — auto, для fetch_content — httpx, и его можно переопределить аргументом backend при каждом вызове.

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

В Docker-образ уже включён.

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 []

Локальная сборка и смоук-тест

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"}}}'

Причина, по которой в DDG_ALLOWED_HOSTS включены все три формы, — неизвестно, добавляет ли клиент порт к Host-заголовку. example.goover.ai и example.goover.ai:33284 — разные значения, и они не сопоставляются.

Проверенные пункты:

• initialize — запуск только через переменные окружения, корректный ответ

• tools/list — корректно возвращает 2 инструмента: search, fetch_content

• tools/call(search) — успех и с английскими, и с корейскими запросами, нет 202 даже при 5 быстрых последовательных вызовах

• tools/call(fetch_content) — успешное извлечение содержимого реальной страницы

• Пробы 4 типов Host-заголовков — разрешённые хосты, localhost, 127.0.0.1 дают 200, незарегистрированный хост — 421

• 4 комбинации формата ответа — корректное переключение application/json / text/event-stream в зависимости от DDG_JSON_RESPONSE

Разработка

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 — GitHub Actions, запускает pytest на Python 3.10–3.14, а также ruff check (blocking) и pip-audit (non-blocking).

Особенности именно этого форка

• Оригинал был задокументирован для использования только со stdio, а настройки HTTP transport были доступны только через CLI-аргументы, что делало запуск при контейнерном развёртывании затруднительным.

• Устранён режим отказа, когда неверное значение TRANSPORT завершалось с exit 0 без каких-либо логов. Причиной было то, что argparse не проверяет значения по умолчанию через choices.

• Исправлен баг, когда настройка allow-list хостов перезаписывала значения localhost по умолчанию из SDK и молча блокировала локальные пробы. Эта проблема не проявлялась до включения allow-list.

• На основе измерений подтверждено, что совместимость с блокирующим HTTP-клиентом решается не подавлением notification, а изменением самого формата ответа (json_response), и предоставлены оба переключателя.

• Локального состояния нет вообще, поэтому PVC не требуется, а также не нужны аутентификация и API-ключи, поэтому нет проблем с управлением учётными данными.

• Справочно о первопричине: пока HTTP-клиент Hub не будет заменён на стек с полноценной поддержкой SSE-стриминга (Spring WebClient и т.п.), та же проблема будет повторяться при подключении любого другого MCP, отправляющего progress notification. Пункт 3 — это обход на стороне сервера.

Лицензия

Следует MIT-лицензии исходного репозитория (nickclyde/duckduckgo-mcp-server) (Copyright (c) 2025 Nick Clyde). Перед распространением и коммерческим использованием ознакомьтесь с файлом LICENSE.