DuckDuckGo MCP Server

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

1. Clone this repository or download the files

1. 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

1. Install dependencies:

pip install -r requirements.txt

Usage

Running the Server

With uv (from the project directory): ``bash uv run python server.py ``

Or activate the virtual environment first: ``bash source .venv/bin/activate # On Windows: .venv\Scripts\activate python server.py ``

With standard Python: ``bash 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): ``json { "mcpServers": { "duckduckgo-search": { "command": "uv", "args": [ "--directory", "/absolute/path/to/websearch_mcp", "run", "python", "server.py" ] } } } ``

Using Python directly with virtual environment: ``json { "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)