MCP-сервер для поиска DuckDuckGo

👁 PyPI version
👁 PyPI downloads
👁 Python versions

MCP-сервер (Model Context Protocol), предоставляющий возможности веб-поиска через DuckDuckGo, с дополнительными функциями для получения и парсинга контента.

Быстрый старт

uvx duckduckgo-mcp-server

Related MCP server: Duck Duck MCP

Функции

• Веб-поиск: Поиск в DuckDuckGo с расширенным ограничением частоты запросов (rate limiting) и форматированием результатов

• Получение контента: Извлечение и парсинг содержимого веб-страниц с интеллектуальным выделением текста

• Ограничение частоты запросов: Встроенная защита от превышения лимитов как для поиска, так и для получения контента

• Обработка ошибок: Комплексная обработка ошибок и ведение логов

• Вывод, оптимизированный для LLM: Результаты отформатированы специально для использования большими языковыми моделями

Установка

Установите из PyPI с помощью uv:

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

Добавьте следующую конфигурацию:

Базовая конфигурация (без SafeSearch, без региона по умолчанию):

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

С конфигурацией SafeSearch и региона:

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

Параметры конфигурации:

• DDG_SAFE_SEARCH: Уровень фильтрации SafeSearch (опционально)

  • STRICT: Максимальная фильтрация контента (kp=1)

  • MODERATE: Сбалансированная фильтрация (kp=-1, значение по умолчанию, если не указано)

  • OFF: Без фильтрации контента (kp=-2)

• DDG_REGION: Код региона/языка по умолчанию (опционально, примеры ниже)

  • us-en: США (английский)

  • cn-zh: Китай (китайский)

  • jp-ja: Япония (японский)

  • wt-wt: Без конкретного региона

  • Оставьте пустым для использования поведения DuckDuckGo по умолчанию

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 переопределите адрес привязки по умолчанию (127.0.0.1:8000) с помощью флагов --host и --port:

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

Бэкенд получения данных (обход защиты от ботов)

Некоторые сайты блокируют стандартный клиент httpx из-за его характерного TLS-отпечатка, независимо от User-Agent — системы управления ботами Cloudflare и аналогичные фильтры ориентируются на рукопожатие JA3/TLS, а не на заголовки. Опциональный бэкенд curl (реализованный через curl_cffi) имитирует рукопожатие TLS реального браузера Chrome и проходит через эти проверки.

Установка:

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

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

Параметры бэкенда:

Два способа настройки бэкенда:

1. Глобальный параметр сервера через флаг CLI --fetch-backend (применяется к каждому вызову 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. Переопределение для конкретного вызова через аргумент backend в инструменте fetch_content (переопределяет значение по умолчанию для этого конкретного вызова). Инструмент предоставляет backend в своей схеме ввода, поэтому MCP-клиент может выбирать "httpx", "curl" или "auto" для каждого запроса отдельно.

Инструмент search всегда использует httpx — поисковая конечная точка DuckDuckGo не требует имитации.

Значение по умолчанию остается 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. Инструмент поиска (Search Tool)

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. Инструмент получения контента (Content Fetching Tool)

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

Получает и парсит контент с веб-страницы.

Параметры:

• url: URL веб-страницы для получения контента

• start_index: Смещение символа, с которого нужно начать чтение (для пагинации)

• max_length: Максимальное количество возвращаемых символов

• backend: Опциональное переопределение бэкенда получения данных для конкретного вызова ("httpx", "curl" или "auto"). Если не указано, используется значение, установленное через --fetch-backend при запуске сервера.

Возвращает: Очищенный и отформатированный текстовый контент с веб-страницы.

Подробности функций

Ограничение частоты запросов (Rate Limiting)

• Поиск: ограничено 30 запросами в минуту

• Получение контента: ограничено 20 запросами в минуту

• Автоматическое управление очередью и временем ожидания

Обработка результатов

• Удаление рекламы и нерелевантного контента

• Очистка URL-адресов перенаправления DuckDuckGo

• Форматирование результатов для оптимального использования LLM

• Соответствующее усечение длинного контента

Безопасность контента

• Фильтрация SafeSearch: Настраивается при запуске сервера через переменную окружения DDG_SAFE_SEARCH

  • Контролируется администраторами, не может быть изменена ИИ-ассистентами

  • Фильтрует неприемлемый контент на основе выбранного уровня

  • Использует официальный параметр kp от DuckDuckGo

• Локализация региона:

  • Регион по умолчанию устанавливается через переменную окружения DDG_REGION

  • Может быть переопределен ИИ-ассистентами для каждого поискового запроса

  • Улучшает релевантность результатов для конкретных географических регионов

Обработка ошибок

• Комплексный перехват и отчетность об ошибках

• Подробное логирование через контекст MCP

• Плавная деградация при достижении лимитов или тайм-аутах

Участие в разработке

Приветствуются сообщения об ошибках и pull-запросы! Области для потенциального улучшения:

• Расширенные опции парсинга контента

• Уровень кэширования для часто запрашиваемого контента

• Дополнительные стратегии ограничения частоты запросов

Лицензия

Этот проект распространяется под лицензией MIT.

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• fetch_contentA
• searchA