khshanovskyi/duckduckgo-mcp-server

DuckDuckGo Search MCP Server

A Model Context Protocol (MCP) server that provides web search and content fetching capabilities using DuckDuckGo.

Features

• Web Search: Search DuckDuckGo with customizable result limits
• Content Fetching: Extract and parse text content from web pages
• Rate Limiting: Built-in rate limiting to prevent API abuse
• Clean Text Extraction: Removes navigation, scripts, and styling for clean content
• Dual Transport: Supports both stdio and streamable-http transports

Installation

Standard Installation

# Clone or download the repository
cd ddg-search-mcp

# Install dependencies
pip install -r src/requirements.txt

# Run the server
python src/server.py

Docker Installation

# Build the image
docker build -t ddg-search-mcp .

# Run with stdio transport
docker run -i ddg-search-mcp

# Run with HTTP transport
docker run -e MCP_TRANSPORT=streamable-http -p 8000:8000 ddg-search-mcp

Configuration

Environment Variables

MCP_TRANSPORT: Set to stdio (default) or streamable-http will run http server, port 8000

Rate Limiting

• Search: 30 requests per minute (default)
• Fetch: 20 requests per minute (default)

Modify the requests_per_minute parameter in server.py to adjust these limits.

Tools

search

Search DuckDuckGo and return formatted results.

Parameters:

• query (string, required): The search query
• max_results (integer, optional): Maximum results to return (default: 10, max: 50)

Example:

{
  "query": "python async programming",
  "max_results": 5
}

Returns: Formatted search results with title, URL, and snippet for each result.

fetch_content

Fetch and parse clean text content from a webpage.

Parameters:

• url (string, required): The webpage URL (must start with http:// or https://)

Example:

{
  "url": "https://example.com/article"
}

Returns: Cleaned text content from the webpage (max 8000 characters), with scripts, styles, and navigation elements removed.

Usage with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "ddg-search": {
      "command": "python",
      "args": ["/path/to/src/server.py"]
    }
  }
}

Using Docker with Claude Desktop

{
  "mcpServers": {
    "ddg-search": {
      "command": "docker",
      "args": ["run", "-i", "ddg-search-mcp"]
    }
  }
}

Notes

• DuckDuckGo may occasionally block automated requests; the rate limiter helps prevent this
• Fetched content excludes scripts, styles, navigation, headers, and footers
• Maximum content length is 8000 characters per fetch
• All HTTP requests include a standard browser User-Agent