nickclyde/duckduckgo-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
Features
- **Web Search**: Search DuckDuckGo with advanced rate limiting and result formatting
- **Content Fetching**: Retrieve and parse webpage content with intelligent text extraction
- **Long URL Shortening**: Over-long result URLs become short ref:// tokens that fetch_content accepts directly, saving context
- **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:
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):**
**With SafeSearch and Region Configuration:**
**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
- DDG_CA_CERTS: Path to a PEM CA bundle used to verify TLS certificates on outbound requests (optional). Needed behind TLS-intercepting proxies — see Running behind a TLS-intercepting proxy.
- DDG_RATE_LIMIT_STRATEGY: sliding (default, historical 60s window) or token_bucket (burst, then smooth).
- 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 cap (default: 0, off). Set a positive number to enable.
- DDG_CACHE_TTL: Seconds to keep a parsed page in the in-memory fetch_content cache (default: 300). Paginated reads of the same URL reuse one download. Set 0 to disable.
- DDG_CACHE_MAX_ENTRIES: Maximum pages kept in that cache (default: 64). Least-recently-used eviction. Set 0 to disable.
- DDG_PARSE_MODE: Default fetch_content extractor (text, main, or markdown). Default is text (historical flattened page). Per-call parse_mode overrides this.
- DDG_REF_URL_THRESHOLD: Search-result URLs longer than this many characters are replaced with short ref:// tokens (default: 120). Set 0 to always show full URLs. Also --ref-url-threshold.
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:
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:
Running behind a reverse proxy or in Docker
The MCP SDK enables DNS-rebinding protection for the HTTP transports and, by default, only accepts Host/Origin headers for localhost. Behind a reverse proxy or in a container the client's Host header won't match, so requests fail with **421 Misdirected Request**.
Fix it by allow-listing the host(s) and origin(s) clients actually use (preferred over disabling protection). Values support host, host:port, and wildcard-port host:*:
Equivalent environment variables (comma-separated) are also available: DDG_ALLOWED_HOSTS, DDG_ALLOWED_ORIGINS.