duckduckgo-mcp-server

Purpose

duckduckgo-mcp-server is a Model Context Protocol (MCP) server used to provide web search capabilities for MCP clients (such as Claude Desktop, Claude Code, etc.), completing searches through DuckDuckGo, while also including content fetching and parsing functionality.

Main Capabilities

• Web Search: Uses DuckDuckGo search, with advanced rate limiting and result formatting.
• Content Fetching: Retrieves and parses web page content, supporting intelligent text extraction.
• Long URL Shortening: Overly long result URLs are replaced with short ref:// tokens, and fetch_content can directly accept these tokens, thereby saving context.
• Rate Limiting: Built-in rate limiting protection for search and content fetching.
• Error Handling: Comprehensive error handling and logging.
• LLM-Oriented Output: Results are specifically formatted for use by large language models.

Main Tools Provided

1. Search Tool: Performs a web search on DuckDuckGo and returns formatted results. Parameters include query (search query string), max_results (maximum number of results to return, default 10), region (optional, overrides the default region/language code). Returns a formatted string containing titles, URLs, and summaries.
2. Content Fetching Tool: Fetches and parses web page content. Parameters include url (the web page URL whose content is to be fetched, or a ref:// token from search results), start_index (character offset starting position for pagination), max_length (maximum number of characters to return), backend (optional per-call fetch backend override), parse_mode (optional per-call extractor). Returns cleaned and formatted web page text content; the parsed full page is cached in memory (default 5 minutes).
3. Link Expansion Tool: URLs in search results that exceed a threshold (default 120 characters) are replaced with short, stable ref:// tokens, and this tool can restore them to the full original URL.

Usage

Install from PyPI

Install from PyPI using uv.

Run in Claude Desktop

Download Claude Desktop, create or edit the Claude Desktop configuration file (macOS path:~/Library/Application Support/Claude/claude_desktop_config.json; Windows path:%APPDATA%\Claude\claude_desktop_config.json), add the corresponding configuration, and restart Claude Desktop.

Run in Claude Code

Download Claude Code, make sure uv is installed and the uvx command is available, then add the MCP server:

claude mcp add ddg-search uvx duckduckgo-mcp-server

Run with SSE or Streamable HTTP

The server supports alternative transports for other MCP clients. The default transport is stdio. When running with sse or streamable-http, the default bind address (127.0.0.1:8000) can be overridden via the --host and --port flags. The MCP SDK enables DNS rebinding protection for HTTP transports, and by default only accepts Host/Origin headers from localhost; behind a reverse proxy or in a container, allowed hosts and origins can be configured via an allow-list (environment variables DDG_ALLOWED_HOSTS, DDG_ALLOWED_ORIGINS), or you can use --disable-dns-rebinding-protection Disable checks (not recommended).

Configuration Options

• DDG_SAFE_SEARCH: Safe search filtering level (STRICT maximum filtering kp=1; MODERATE balanced filtering kp=-1, which is the default when unspecified; OFF no filtering kp=-2). Configured by the administrator at server startup; the AI assistant cannot modify it.
• DDG_REGION: Default region/language code (e.g., us-en US English, cn-zh China Chinese, jp-ja Japan Japanese, wt-wt no specific region; leave blank to use DuckDuckGo's default behavior). Can be overridden by the AI assistant in each search request.
• DDG_CA_CERTS: Path to the PEM CA bundle used to verify TLS certificates for outbound requests (optional).
• DDG_RATE_LIMIT_STRATEGY: sliding (default, historical 60-second window) or token_bucket.
• DDG_SEARCH_RPM: Search requests per minute (default 30).
• DDG_FETCH_RPM: Global fetch_content requests per minute (default 20).
• DDG_FETCH_HOST_RPM: Optional per-host fetch limit (default 0, i.e., disabled).
• DDG_CACHE_TTL: Number of seconds parsed pages are kept in the in-memory cache (default 300); set to 0 to disable.
• DDG_CACHE_MAX_ENTRIES: Maximum number of pages kept in the cache (default 64), using least recently used eviction.
• DDG_PARSE_MODE: Default extractor for fetch_content (text, main, or markdown), default text.
• DDG_REF_URL_THRESHOLD: Search result URLs exceeding this character count are replaced with a short ref:// token (default 120); set to 0 to always show the full URL.

Backend (Bypassing Bot Detection)

Some websites, as well as DuckDuckGo's own search endpoint (html.duckduckgo.com), block requests due to the TLS fingerprint of the default httpx client. The optional curl backend (implemented via curl_cffi)simulates a real Chrome browser's TLS handshake to pass checks. Both the search and content fetching tools support these backends. Backend options include httpx, curl, auto; the search tool uses auto by default (tries httpx first, falls back to curl when blocking is detected; the fallback requires installing the [browser] extra dependency). It can be configured via the --fetch-backend、--search-backend command-line flag or the DDG_SEARCH_BACKEND environment variable.

Security and Limits

• Rate limiting: Search defaults to 30 requests per minute, and content fetching defaults to 20 requests per minute globally; HTTP 429 responses honor Retry-After (capped at 30 seconds) and retry once; cache hits skip download and fetch rate limits.
• Cache: In-memory TTL cache, default TTL 300 seconds, 64 entries, using LRU eviction; errors are not cached.
• SSRF protection: By default, fetch_content rejects URLs that resolve to loopback, private (RFC1918), link-local (including the 169.254.169.254 cloud metadata endpoint), reserved, multicast, or unspecified addresses, and revalidates on every redirect hop, allowing only http/https URLs; trusted local deployments can use DDG_ALLOW_PRIVATE_URLS=1 or --allow-private-urls to disable this protection.
• This server relies on DuckDuckGo's search endpoint and may be affected by its anti-scraping or fingerprint-blocking policies.

Use Cases

Suitable for scenarios that need to provide web search, web content fetching, and parsing capabilities for MCP clients (Claude Desktop, Claude Code, etc.), such as enabling large language models to retrieve network information and read web page body text.

License

This project is licensed under the MIT License.