MCP сервер для поиска информации через DuckDuckGo Search

Этот MCP сервер предоставляет инструменты для поиска информации в интернете с использованием библиотеки DDGS (DuckDuckGo Search).

Установка

Требования

• Python 3.8+

• uv (https://github.com/astral-sh/uv) - рекомендуется для управления зависимостями

• Или стандартный pip и venv

Шаги установки

1. Клонируйте репозиторий или создайте папку проекта:

   mkdir duck_duck_MCP
   cd duck_duck_MCP

2. (Рекомендуется) Создайте виртуальное окружение:

   # С uv
   uv venv
   # Активируйте (Windows)
   venv\Scripts\activate
   # Активируйте (Linux/macOS)
   source .venv/bin/activate

   Примечание: Если вы используете uv, он автоматически создаст и активирует .venv при первом запуске uv pip install.

3. Установите зависимости:

   # С uv (рекомендуется)
   uv pip install -r requirements.txt
   # Или с pip
   pip install -r requirements.txt

   Примечание: ddgs - это библиотека для работы с DuckDuckGo Search.

Related MCP server: MCP DuckDuckGo Search Server

Поддерживаемые методы MCP

Сервер реализует следующие методы протокола MCP:

• initialize - Инициализация сервера

• tools/list - Получение списка доступных инструментов

• tools/call - Вызов инструмента

Доступные инструменты

get_search_operators

Получить документацию по операторам поиска DDG

Параметры: нет

search_text

Текстовый поиск через DDGS

Параметры:

• query (обязательный): Поисковый запрос

• region: Регион (us-en, uk-en, ru-ru, и т.д.) - по умолчанию "us-en"

• safesearch: Уровень фильтрации (on, moderate, off) - по умолчанию "moderate"

• timelimit: Ограничение по времени (d, w, m, y)

• max_results: Максимальное количество результатов - по умолчанию 10

• page: Номер страницы результатов - по умолчанию 1

• backend: Поисковые движки (auto, google, bing, и т.д.) - по умолчанию "auto"

search_images

Поиск изображений через DDGS

Параметры:

• query (обязательный): Поисковый запрос

• region: Регион - по умолчанию "us-en"

• safesearch: Уровень фильтрации (on, moderate, off) - по умолчанию "moderate"

• timelimit: Ограничение по времени (d, w, m, y)

• max_results: Максимальное количество результатов - по умолчанию 10

• page: Номер страницы результатов - по умолчанию 1

• backend: Поисковые движки - по умолчанию "auto"

• size: Размер изображения (Small, Medium, Large, Wallpaper)

• color: Цвет изображения (color, Monochrome, Red, и т.д.)

• type_image: Тип изображения (photo, clipart, gif, и т.д.)

• layout: Макет изображения (Square, Tall, Wide)

• license_image: Лицензия изображения (any, Public, Share, и т.д.)

search_videos

Поиск видео через DDGS

Параметры:

• query (обязательный): Поисковый запрос

• region: Регион - по умолчанию "us-en"

• safesearch: Уровень фильтрации (on, moderate, off) - по умолчанию "moderate"

• timelimit: Ограничение по времени (d, w, m)

• max_results: Максимальное количество результатов - по умолчанию 10

• page: Номер страницы результатов - по умолчанию 1

• backend: Поисковые движки - по умолчанию "auto"

• resolution: Разрешение видео (high, standard)

• duration: Длительность видео (short, medium, long)

• license_videos: Лицензия видео (creativeCommon, youtube)

search_news

Поиск новостей через DDGS

Параметры:

• query (обязательный): Поисковый запрос

• region: Регион - по умолчанию "us-en"

• safesearch: Уровень фильтрации (on, moderate, off) - по умолчанию "moderate"

• timelimit: Ограничение по времени (d, w, m)

• max_results: Максимальное количество результатов - по умолчанию 10

• page: Номер страницы результатов - по умолчанию 1

• backend: Поисковые движки - по умолчанию "auto"

search_books

Поиск книг через DDGS

Параметры:

• query (обязательный): Поисковый запрос

• max_results: Максимальное количество результатов - по умолчанию 10

• page: Номер страницы результатов - по умолчанию 1

• backend: Поисковые движки - по умолчанию "auto"

Примеры использования

Текстовый поиск

{
  "method": "search_text",
  "params": {
    "query": "python programming",
    "max_results": 5,
    "region": "us-en"
  }
}

Поиск изображений

{
  "method": "search_images",
  "params": {
    "query": "cats",
    "max_results": 10,
    "color": "Monochrome"
  }
}

Получение операторов поиска

{
  "method": "get_search_operators",
  "params": {}
}

Операторы поиска DDG

• cats dogs - Результаты о cats или dogs

• "cats and dogs" - Результаты точного совпадения "cats and dogs"

• cats -dogs - Меньше упоминаний dogs в результатах

• cats +dogs - Больше упоминаний dogs в результатах

• cats filetype:pdf - PDF файлы о cats

• dogs site:example.com - Страницы о dogs с сайта example.com

• cats -site:example.com - Страницы о cats, исключая example.com

• intitle:dogs - Заголовок страницы содержит слово "dogs"

• inurl:cats - URL страницы содержит слово "cats"

Примеры конфигов

Конфигурация для запуска напрямую

{
  "mcpServers": {
    "ddg-stdio": {
      "disabled": true,
      "timeout": 60,
      "type": "stdio",
      "command": "python",
      "args": [
        "Path_To\\ddg_mcp_server.py"
      ],
      "env": {}
    }
  }
}

Adding to Github Copilot in VS Code

1. Create a .vscode folder and create a file in it: mcp.json

2. Add the config:

{
  "servers": {
    "ddg-stdio": {
      "type": "stdio",
      "command": "Path_TO\\duck_duck_MCP\\venv\\Scripts\\python.exe",
      "args": [
        "Path_TO\\duck_duck_MCP\\ddg_mcp_server.py"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Running in Opencode

Add the server according to the instructions with this config (this is the global version in the opencode.json file):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "duck_duck_MCP": {
      "type": "local",
      "command": [
        "C:\\Users\\LAB\\Desktop\\duck_duck_MCP\\venv\\Scripts\\python.exe",
        "C:\\Users\\LAB\\Desktop\\duck_duck_MCP\\ddg_mcp_server.py"
      ]
    }
  }
}

Конфигурация с использованием Python из venv (рекомендуется)

Для Windows:

{
  "mcpServers": {
    "ddg-stdio": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "C:\\Users\\Igor\\Desktop\\duck_duck_MCP\\venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\Igor\\Desktop\\duck_duck_MCP\\ddg_mcp_server.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Важно:

• Замените C:\\Users\\Igor\\Desktop\\duck_duck_MCP на ваш реальный путь к проекту

• Используйте двойные обратные слashes (\\) в путях для Windows

• Убедитесь, что в venv установлены все зависимости: pip install -r requirements.txt

• Переменная окружения PYTHONIOENCODING=utf-8 обязательна для правильной работы с кириллицей

Для Linux/macOS:

{
  "mcpServers": {
    "ddg-stdio": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "/path/to/duck_duck_MCP/venv/bin/python",
      "args": ["/path/to/duck_duck_MCP/ddg_mcp_server.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

{ "mcpServers": { "ddg-stdio": { "command": "Полный_путь_к_папке_duck_duck_MCP\venv\Scripts\python.exe", "timeout": 120, "type": "stdio", "args": [ "Полный_путь_к_папке_duck_duck_MCP\ddg_mcp_server.py" ], "env": {}, "active": true } } }

*Замените `Полный_путь_к_папке_duck_duck_MCP` на реальный путь к вашему проекту. Например: `E:\\Users\\Igory\\Desktop\\duck_duck_MCP\\venv\\Scripts\\python.exe`*

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

Сервер может возвращать следующие ошибки:
- Превышение лимита запросов
- Таймаут запроса
- Общие ошибки поиска

## Поддержка прокси
Для использования прокси можно установить переменную окружения `DDGS_PROXY`:
```bash
export DDGS_PROXY="socks5h://user:password@1.2.3.4:8080"

MCP Server for Information Search via DuckDuckGo Search

This MCP server provides tools for searching information on the internet using the DDGS (DuckDuckGo Search) library.

Installation

Requirements

• Python 3.8+

• uv (https://github.com/astral-sh/uv) - recommended for dependency management

• Or standard pip and venv

Installation Steps

1. Clone the repository or create a project folder:

   mkdir duck_duck_MCP
   cd duck_duck_MCP

2. (Recommended) Create a virtual environment:

   # With uv
   uv venv
   # Activate (Windows)
   venv\Scripts\activate
   # Activate (Linux/macOS)
   source .venv/bin/activate

   Note: If you use uv, it will automatically create and activate .venv when you first run uv pip install.

3. Install dependencies:

   # With uv (recommended)
   uv pip install -r requirements.txt
   # Or with pip
   pip install -r requirements.txt

   Note: ddgs is a library for working with DuckDuckGo Search.

Supported MCP Methods

The server implements the following MCP protocol methods:

• initialize - Server initialization

• tools/list - Get list of available tools

• tools/call - Call tool

Available Tools

get_search_operators

Get documentation on DDG search operators

Parameters: none

search_text

Text search via DDGS

Parameters:

• query (required): Search query

• region: Region (us-en, uk-en, ru-ru, etc.) - default "us-en"

• safesearch: Filtering level (on, moderate, off) - default "moderate"

• timelimit: Time limit (d, w, m, y)

• max_results: Maximum number of results - default 10

• page: Result page number - default 1

• backend: Search engines (auto, google, bing, etc.) - default "auto"

search_images

Image search via DDGS

Parameters:

• query (required): Search query

• region: Region - default "us-en"

• safesearch: Filtering level (on, moderate, off) - default "moderate"

• timelimit: Time limit (d, w, m, y)

• max_results: Maximum number of results - default 10

• page: Result page number - default 1

• backend: Search engines - default "auto"

• size: Image size (Small, Medium, Large, Wallpaper)

• color: Image color (color, Monochrome, Red, etc.)

• type_image: Image type (photo, clipart, gif, etc.)

• layout: Image layout (Square, Tall, Wide)

• license_image: Image license (any, Public, Share, etc.)

search_videos

Video search via DDGS

Parameters:

• query (required): Search query

• region: Region - default "us-en"

• safesearch: Filtering level (on, moderate, off) - default "moderate"

• timelimit: Time limit (d, w, m)

• max_results: Maximum number of results - default 10

• page: Result page number - default 1

• backend: Search engines - default "auto"

• resolution: Video resolution (high, standard)

• duration: Video duration (short, medium, long)

• license_videos: Video license (creativeCommon, youtube)

search_news

News search via DDGS

Parameters:

• query (required): Search query

• region: Region - default "us-en"

• safesearch: Filtering level (on, moderate, off) - default "moderate"

• timelimit: Time limit (d, w, m)

• max_results: Maximum number of results - default 10

• page: Result page number - default 1

• backend: Search engines - default "auto"

search_books

Book search via DDGS

Parameters:

• query (required): Search query

• max_results: Maximum number of results - default 10

• page: Result page number - default 1

• backend: Search engines - default "auto"

Usage Examples

Text Search

{
  "method": "search_text",
  "params": {
    "query": "python programming",
    "max_results": 5,
    "region": "us-en"
  }
}

Image Search

{
  "method": "search_images",
  "params": {
    "query": "cats",
    "max_results": 10,
    "color": "Monochrome"
  }
}

Getting Search Operators

{
  "method": "get_search_operators",
  "params": {}
}

DDG Search Operators

• cats dogs - Results about cats or dogs

• "cats and dogs" - Exact match results for "cats and dogs"

• cats -dogs - Fewer mentions of dogs in results

• cats +dogs - More mentions of dogs in results

• cats filetype:pdf - PDF files about cats

• dogs site:example.com - Pages about dogs from example.com

• cats -site:example.com - Pages about cats, excluding example.com

• intitle:dogs - Page title contains the word "dogs"

• inurl:cats - Page URL contains the word "cats"

Configuration Examples

Configuration for Direct Launch

{
  "mcpServers": {
    "ddg-stdio": {
      "command": "python",
      "timeout": 120,
       "type": "stdio",
      "args": [
        "Path_to_duck_duck_MCP_folder\\ddg_mcp_server.py"
      ],
      "env": {},
      "active": true
    }
  }
}

Configuration Using Python from venv (Recommended)

{
  "mcpServers": {
    "ddg-stdio": {
      "command": "Full_path_to_duck_duck_MCP_folder\\venv\\Scripts\\python.exe",
      "timeout": 120,
       "type": "stdio",
      "args": [
        "Full_path_to_duck_duck_MCP_folder\\ddg_mcp_server.py"
      ],
      "env": {},
      "active": true
    }
  }
}

Replace Full_path_to_duck_duck_MCP_folder with the actual path to your project. For example: E:\\Users\\Igory\\Desktop\\duck_duck_MCP\\venv\\Scripts\\python.exe

Error Handling

The server may return the following errors:

• Request limit exceeded

• Request timeout

• General search errors

Proxy Support

To use a proxy, you can set the DDGS_PROXY environment variable:

export DDGS_PROXY="socks5h://user:password@1.2.3.4:8080"