DuckDuck

This MCP server enables information retrieval on the internet using the DuckDuckGo Search (DDGS) library. It provides a programmable interface to perform text, image, video, news, and book searches via MCP tools, making it easy to incorporate DuckDuckGo queries into your automation workflows and agents.

How to use

You will interact with this MCP server through an MCP client by calling one of the available tools. Start by listing the tools your server exposes, then perform searches by selecting a tool and passing the required parameters. Use text search to pull general results, images or videos to gather media, or search news and books for current topics. Each tool returns structured results you can consume in your application or automation.

How to install

Prerequisites: you need Python 3.8 or newer. You should have either uv for dependency management or use the standard Python toolchain with pip and venv.

# Create a project folder
mkdir duck_duck_MCP
cd duck_duck_MCP

# Optional: initialize a virtual environment using uv (recommended)
uv venv
# On Windows
venv\Scripts\activate
# On Linux/macOS
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt
# Or, if not using uv
pip install -r requirements.txt

Additional configuration and notes

You can configure how the MCP server runs by choosing between direct local launch or using a Python virtual environment. The following examples show how to start the MCP server as a stdio process. These blocks assume you have the server code available in the referenced paths and that you run the commands from the project root.

# Direct launch configuration
{
  "mcpServers": {
    "ddg_mcp": {
      "command": "python",
      "timeout": 120,
      "type": "stdio",
      "args": [
        "Path_to_duck_duck_MCP_folder\\ddg_mcp_server.py"
      ],
      "env": {},
      "active": true
    }
  }
}

# Configuration using Python from a virtual environment (recommended)
{
  "mcpServers": {
    "ddg_mcp": {
      "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": {
        "PYTHONIOENCODING": "utf-8"
      },
      "active": true
    }
  }
}

Note that the environment variable PYTHONIOENCODING is important for proper handling of non-English text, and you should replace Full_path_to_duck_duck_MCP_folder with your actual project path. If you use Windows paths, keep double backslashes in JSON strings.

Proxy and environment considerations

If you need to route requests through a proxy, you can set the DDGS_PROXY environment variable to a SOCKS proxy string, for example: socks5h://user:password@1.2.3.4:8080.

Troubleshooting tips

If you encounter request limit errors or timeouts, review your region and safesearch settings, and ensure your network connection is stable. Check that the DDGS backend setting is appropriate for your needs and that the required dependencies are installed in your virtual environment.

Examples of tool usage

You can call the prepared tools to perform different kinds of searches. Here are the available tools you will interact with in practice.

Tool catalog (high level)

• get_search_operators: Retrieve documentation on DDG search operators.

• search_text: Perform a text search using DDGS with configurable region, safesearch, and result paging.

• search_images: Look up images with controls for size, color, type, layout, license, and more.

• search_videos: Find videos with resolution, duration, and license filters.

• search_news: Search current news with region and safety filters.

• search_books: Discover books with paging and backends.

DDG search operators examples

Examples of search operator syntax include combining terms, exact phrases, site restrictions, and filetype filters to refine results.

Available tools

get_search_operators

Retrieve documentation on DDG search operators.

search_text

Perform a text search via the DDGS library with configurable region, safesearch, and pagination.

search_images

Search images with options for size, color, type, layout, and license.

search_videos

Search for videos with resolution, duration, and license controls.

search_news

Search for news results with regional and safety filters.

search_books

Search for books with paging and backend options.