DuckDuckGo Search MCP Server

A Model Context Protocol (MCP) server that provides web search capabilities through DuckDuckGo, with additional features for content fetching and parsing.

Quick Start

uvx duckduckgo-mcp-server

Features

• Web Search: Search DuckDuckGo with advanced rate limiting and result formatting
• Content Fetching: Retrieve and parse webpage content with intelligent text extraction
• Rate Limiting: Built-in protection against rate limits for both search and content fetching
• Error Handling: Comprehensive error handling and logging
• LLM-Friendly Output: Results formatted specifically for large language model consumption

Installation

Install from PyPI using uv:

uv pip install duckduckgo-mcp-server

Usage

Running with Claude Desktop

1. Download Claude Desktop
2. Create or edit your Claude Desktop configuration:
   • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • On Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

Basic Configuration (No SafeSearch, No Default Region):

{
    "mcpServers": {
        "ddg-search": {
            "command": "uvx",
            "args": ["duckduckgo-mcp-server"]
        }
    }
}

With SafeSearch and Region Configuration:

{
    "mcpServers": {
        "ddg-search": {
            "command": "uvx",
            "args": ["duckduckgo-mcp-server"],
            "env": {
                "DDG_SAFE_SEARCH": "STRICT",
                "DDG_REGION": "cn-zh"
            }
        }
    }
}

Configuration Options:

• DDG_SAFE_SEARCH: SafeSearch filtering level (optional)
  • STRICT: Maximum content filtering (kp=1)
  • MODERATE: Balanced filtering (kp=-1, default if not specified)
  • OFF: No content filtering (kp=-2)
• DDG_REGION: Default region/language code (optional, examples below)
  • us-en: United States (English)
  • cn-zh: China (Chinese)
  • jp-ja: Japan (Japanese)
  • wt-wt: No specific region
  • Leave empty for DuckDuckGo's default behavior

3. Restart Claude Desktop

Running with Claude Code

1. Download Claude Code
2. Ensure uvenv is installed and the uvx command is available
3. Add the MCP server: claude mcp add ddg-search uvx duckduckgo-mcp-server

Running with SSE or Streamable HTTP

The server supports alternative transports for use with other MCP clients:

# SSE transport
uvx duckduckgo-mcp-server --transport sse

# Streamable HTTP transport
uvx duckduckgo-mcp-server --transport streamable-http

The default transport is stdio, which is used by Claude Desktop and Claude Code.

When running with sse or streamable-http, override the default bind address (127.0.0.1:8000) with the --host and --port flags:

uvx duckduckgo-mcp-server --transport streamable-http --host 0.0.0.0 --port 7070

Fetch Backend (bypassing bot detection)

Some sites block the default httpx client because of its distinctive TLS fingerprint, regardless of User-Agent — Cloudflare Bot Management and similar filters key on the JA3/TLS handshake, not on headers. An opt-in backend, curl (implemented via curl_cffi), impersonates a real Chrome browser's TLS handshake and passes through those checks.

Installation:

# Default install (httpx only)
uv pip install duckduckgo-mcp-server

# With the optional browser backend
uv pip install "duckduckgo-mcp-server[browser]"

... View full README on GitHub