DuckDuckGo MCP Server

A simple Model Context Protocol (MCP) server that provides web search, image search, and image download capabilities using the duckduckgo_search library.

Features

• Web Search: Search the web using DuckDuckGo with customizable region and result limits
• Image Search: Search for images with filters for size and type
• Image Download: Download images from URLs to your local machine

Installation

Using uv (Recommended)

1. Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone this repository or download the files

3. Create a virtual environment and install dependencies:

uv venv
uv pip install -r requirements.txt

Using pip

1. Clone this repository or download the files

2. Install dependencies:

pip install -r requirements.txt

Usage

Running the Server

With uv (from the project directory):

uv run python server.py

Or activate the virtual environment first:

source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python server.py

With standard Python:

python server.py

Configuring in Claude Desktop

Add this configuration to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Using uv (recommended):

{
  "mcpServers": {
    "duckduckgo-search": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/websearch_mcp",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

Using Python directly with virtual environment:

{
  "mcpServers": {
    "duckduckgo-search": {
      "command": "/absolute/path/to/websearch_mcp/.venv/bin/python",
      "args": ["/absolute/path/to/websearch_mcp/server.py"]
    }
  }
}

Available Tools

web_search

Search the web using DuckDuckGo.

Parameters:

• query (required): The search query
• max_results (optional): Maximum number of results (default: 10)
• region (optional): Region code (default: "wt-wt" for worldwide)
  • Examples: "us-en", "uk-en", "de-de", "fr-fr"

Example:

Search the web for "Python MCP servers" with max 5 results

image_search

Search for images using DuckDuckGo.

Parameters:

• query (required): The image search query
• max_results (optional): Maximum number of results (default: 10)
• size (optional): Image size filter
  • Options: "small", "medium", "large", "wallpaper"
• type (optional): Image type filter
  • Options: "photo", "clipart", "gif", "transparent", "line"

Example:

Search for "cute puppies" images, large size, photo type, max 5 results

download_image

Download an image from a URL to your local machine.

Parameters:

• url (required): The URL of the image to download
• filename (optional): Custom filename for the downloaded image
• download_dir (optional): Directory to save the image (default: "./downloads")

Example:

Download image from https://example.com/image.jpg to ./my-images/

Dependencies

• duckduckgo_search - DuckDuckGo search library
• mcp - Model Context Protocol SDK
• httpx - HTTP client for downloading images

License

See LICENSE file for details.

Notes

• Images are downloaded to ./downloads by default
• The download directory will be created automatically if it doesn't exist
• Web search respects DuckDuckGo's rate limits
• All searches are anonymous (no tracking)