DuckDuckGo MCP Server

To bypass bot detection (like Cloudflare), you can use the curl backend, which requires the [browser] extra installation.

Available Backends:

• httpx: Lightweight async HTTP. Default. Works on most sites.
• curl: Uses curl_cffi with Chrome 131 TLS impersonation. Passes TLS-fingerprint-based filters. (Requires [browser] extra).
• auto: Tries httpx first; retries with curl on 403 or Cloudflare challenge responses. (Requires [browser] extra).

Server-wide configuration via CLI flags:

• --fetch-backend <value>: Sets the default backend for fetch_content calls.
• --search-backend <value>: Sets the default backend for search calls.

Example: Using the auto backend for fetching:

uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend auto

The server implements automatic queue management and wait times to handle the following rate limits:

• Search: 30 requests per minute
• Content Fetching: 20 requests per minute

To optimize results for LLM consumption, the server automatically:

• Removes ads and irrelevant content
• Cleans up DuckDuckGo redirect URLs
• Formats results for LLMs
• Truncates long content appropriately

You can install the server using uv from PyPI.

For the standard installation (uses httpx backend):

uv pip install duckduckgo-mcp-server

For the installation with the optional browser backend (required for curl and auto backends to bypass bot detection):

uv pip install "duckduckgo-mcp-server[browser]"

To use the server with Claude Desktop, add it to your claude_desktop_config.json file.

Locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Basic Configuration:

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

Advanced Configuration (SafeSearch and Region): Use environment variables to control filtering and localization.

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

To prevent Server-Side Request Forgery (SSRF), the fetch_content tool includes a security guard that rejects URLs resolving to loopback, private (RFC1918), link-local, reserved, multicast, or unspecified addresses.

If you need to fetch from internal/private hosts in a trusted environment, you must:

1. Set the environment variable DDG_ALLOW_PRIVATE_URLS=1.
2. Or, if using the underlying API, set allow_private_urls=True in the WebContentFetcher constructor.

The server supports different HTTP backends to handle bot detection and TLS fingerprinting:

• httpx: The default lightweight async HTTP client.
• curl: Uses curl_cffi for Chrome TLS impersonation. This is highly effective at bypassing Cloudflare and other bot filters. Requires installation via pip install 'duckduckgo-mcp-server[browser]'.
• auto: The recommended setting. It tries httpx first and transparently falls back to curl if it detects a fingerprint-based block (HTTP 202 or 403) or a Cloudflare challenge.

Fetches and parses content from a webpage.

Signature: async def fetch_content(url: str, start_index: int = 0, max_length: int = 8000, backend: Optional[str] = None) -> str

Parameters:

• url: The webpage URL to fetch.
• start_index: Character offset to start reading from (for pagination).
• max_length: Maximum number of characters to return.
• backend: (Optional) Per-call override of the default fetch backend ("httpx", "curl", or "auto").

Returns: Cleaned and formatted text content from the webpage.

Security Note: By default, fetch_content refuses URLs that resolve to loopback, private (RFC1918), link-local, or reserved addresses. To allow these, use DDG_ALLOW_PRIVATE_URLS=1 or the --allow-private-urls flag.

Performs a web search on DuckDuckGo and returns formatted results.

Signature: async def search(query: str, max_results: int = 10, region: str = "") -> str

Parameters:

• query: Search query string.
• max_results: Maximum number of results to return (default: 10).
• region: (Optional) Region/language code to override the default (e.g., us-en, jp-ja).

Returns: Formatted string containing search results with titles, URLs, and snippets.