Skip to content
Back to search

duckduckgo-mcp-server

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nickclyde--duckduckgo-mcp-server/badge.svg)](/listings/nickclyde--duckduckgo-mcp-server)

HTML

<a href="/listings/nickclyde--duckduckgo-mcp-server"><img src="/api/listings/nickclyde--duckduckgo-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

uvx duckduckgo-mcp-server

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 372 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # DuckDuckGo Search MCP Server
  2. [![PyPI version](https://img.shields.io/pypi/v/duckduckgo-mcp-server)](https://pypi.org/project/duckduckgo-mcp-server/)
  3. [![PyPI downloads](https://img.shields.io/pypi/dm/duckduckgo-mcp-server)](https://pypi.org/project/duckduckgo-mcp-server/)
  4. [![Python versions](https://img.shields.io/pypi/pyversions/duckduckgo-mcp-server)](https://pypi.org/project/duckduckgo-mcp-server/)
  5. A Model Context Protocol (MCP) server that provides web search capabilities through DuckDuckGo, with additional features for content fetching and parsing.
  6. ## Quick Start
  7. ```bash
  8. uvx duckduckgo-mcp-server
  9. ```
  10. ## Features
  11. - **Web Search**: Search DuckDuckGo with advanced rate limiting and result formatting
  12. - **Content Fetching**: Retrieve and parse webpage content with intelligent text extraction
  13. - **Long URL Shortening**: Over-long result URLs become short `ref://` tokens that `fetch_content` accepts directly, saving context
  14. - **Rate Limiting**: Built-in protection against rate limits for both search and content fetching
  15. - **Error Handling**: Comprehensive error handling and logging
  16. - **LLM-Friendly Output**: Results formatted specifically for large language model consumption
  17. ## Installation
  18. Install from PyPI using `uv`:
  19. ```bash
  20. uv pip install duckduckgo-mcp-server
  21. ```
  22. ## Usage
  23. ### Running with Claude Desktop
  24. 1. Download [Claude Desktop](https://claude.ai/download)
  25. 2. Create or edit your Claude Desktop configuration:
  26. - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  27. - On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  28. Add the following configuration:
  29. **Basic Configuration (No SafeSearch, No Default Region):**
  30. ```json
  31. {
  32. "mcpServers": {
  33. "ddg-search": {
  34. "command": "uvx",
  35. "args": ["duckduckgo-mcp-server"]
  36. }
  37. }
  38. }
  39. ```
  40. **With SafeSearch and Region Configuration:**
  41. ```json
  42. {
  43. "mcpServers": {
  44. "ddg-search": {
  45. "command": "uvx",
  46. "args": ["duckduckgo-mcp-server"],
  47. "env": {
  48. "DDG_SAFE_SEARCH": "STRICT",
  49. "DDG_REGION": "cn-zh"
  50. }
  51. }
  52. }
  53. }
  54. ```
  55. **Configuration Options:**
  56. - `DDG_SAFE_SEARCH`: SafeSearch filtering level (optional)
  57. - `STRICT`: Maximum content filtering (kp=1)
  58. - `MODERATE`: Balanced filtering (kp=-1, default if not specified)
  59. - `OFF`: No content filtering (kp=-2)
  60. - `DDG_REGION`: Default region/language code (optional, examples below)
  61. - `us-en`: United States (English)
  62. - `cn-zh`: China (Chinese)
  63. - `jp-ja`: Japan (Japanese)
  64. - `wt-wt`: No specific region
  65. - Leave empty for DuckDuckGo's default behavior
  66. - `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](#running-behind-a-tls-intercepting-proxy).
  67. - `DDG_RATE_LIMIT_STRATEGY`: `sliding` (default, historical 60s window) or `token_bucket` (burst, then smooth).
  68. - `DDG_SEARCH_RPM`: Search requests per minute (default: `30`).
  69. - `DDG_FETCH_RPM`: Global `fetch_content` requests per minute (default: `20`).
  70. - `DDG_FETCH_HOST_RPM`: Optional per-host fetch cap (default: `0`, off). Set a positive number to enable.
  71. - `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.
  72. - `DDG_CACHE_MAX_ENTRIES`: Maximum pages kept in that cache (default: `64`). Least-recently-used eviction. Set `0` to disable.
  73. - `DDG_PARSE_MODE`: Default `fetch_content` extractor (`text`, `main`, or `markdown`). Default is `text` (historical flattened page). Per-call `parse_mode` overrides this.
  74. - `DDG_REF_URL_THRESHOLD`: Search-result URLs longer than this many characters are replaced with short `ref://<id>` tokens (default: `120`). Set `0` to always show full URLs. Also `--ref-url-threshold`.
  75. 3. Restart Claude Desktop
  76. ### Running with Claude Code
  77. 1. Download [Claude Code](https://github.com/anthropics/claude-code)
  78. 2. Ensure [`uvenv`](https://github.com/robinvandernoord/uvenv) is installed and the `uvx` command is available
  79. 3. Add the MCP server: `claude mcp add ddg-search uvx duckduckgo-mcp-server`
  80. ### Running with SSE or Streamable HTTP
  81. The server supports alternative transports for use with other MCP clients:
  82. ```bash
  83. # SSE transport
  84. uvx duckduckgo-mcp-server --transport sse
  85. # Streamable HTTP transport
  86. uvx duckduckgo-mcp-server --transport streamable-http
  87. ```
  88. The default transport is `stdio`, which is used by Claude Desktop and Claude Code.
  89. When running with `sse` or `streamable-http`, override the default bind address (`127.0.0.1:8000`) with the `--host` and `--port` flags:
  90. ```bash
  91. uvx duckduckgo-mcp-server --transport streamable-http --host 0.0.0.0 --port 7070
  92. ```
  93. #### Running behind a reverse proxy or in Docker
  94. 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`**.
  95. 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:*`:
  96. ```bash
  97. uvx duckduckgo-mcp-server --transport streamable-http --host 0.0.0.0 --port 7070 \
  98. --allowed-hosts ddg-mcp.example.com "ddg-mcp.example.com:*" \
  99. --allowed-origins "https://ddg-mcp.example.com"
  100. ```
  101. Equivalent environment variables (comma-separated) are also available: `DDG_ALLOWED_HOSTS`, `DDG_ALLOWED_ORIGINS`.
  102. As a last resort you can turn the check off entirely with `--disable-dns-rebinding-protection` (or `DDG_DISABLE_DNS_REBINDING_PROTECTION=1`). Prefer an allow-list — disabling protection removes a defense against DNS-rebinding attacks. When nothing is configured, the secure localhost-only default is preserved.
  103. #### Running behind a TLS-intercepting proxy
  104. Corporate proxies that re-sign HTTPS traffic with their own CA (via `HTTPS_PROXY`) cause outbound requests to fail with certificate verification errors, because the HTTP clients don't trust the proxy's self-signed CA (and httpx no longer reads the `SSL_CERT_FILE` environment variable). Point the server at your proxy's CA bundle:
  105. ```bash
  106. uvx duckduckgo-mcp-server --ca-certs /path/to/proxy-ca.pem
  107. ```
  108. Or set `DDG_CA_CERTS=/path/to/proxy-ca.pem`. The bundle is used by both the `search` and `fetch_content` tools, on the httpx and curl backends alike.
  109. As a last resort, `--no-ssl-verify` (or `DDG_SSL_VERIFY=0`) disables certificate verification entirely. This exposes traffic to interception by anyone on the network path — prefer `--ca-certs`.
  110. ### Backends (bypassing bot detection)
  111. Some sites — and, as of recently, DuckDuckGo's own search endpoint (`html.duckduckgo.com`) — 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, so `html.duckduckgo.com` may answer `httpx` with an empty **HTTP 202** page (silently yielding "no results"). An opt-in backend, `curl` (implemented via `curl_cffi`), impersonates a real Chrome browser's TLS handshake and passes through those checks.
  112. Both the `search` tool and the `fetch_content` tool support these backends.
  113. **Installation:**
  114. ```bash
  115. # Default install (httpx only)
  116. uv pip install duckduckgo-mcp-server
  117. # With the optional browser backend
  118. uv pip install "duckduckgo-mcp-server[browser]"
  119. ```
  120. **Backend options:**
  121. | Value | Behavior | Needs `[browser]` |
  122. | ------ | ----------------------------------------------------------------------------------------- | ----------------- |
  123. | `httpx` | Lightweight async HTTP. Default. Works on most sites. | no |
  124. | `curl` | Uses `curl_cffi` with Chrome 131 TLS impersonation. Passes TLS-fingerprint-based filters. | yes |
  125. | `auto` | Tries `httpx` first; on 403 or a Cloudflare challenge response, retries with `curl`. | yes |
  126. **Two ways to configure the backend:**
  127. 1. **Server-wide default** via the `--fetch-backend` CLI flag (applies to every `fetch_content` call):
  128. ```bash
  129. # Default behavior — uses httpx
  130. uvx duckduckgo-mcp-server
  131. # Force curl for every fetch (requires the [browser] extra)
  132. uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend curl
  133. # Try httpx first, fall back to curl on 403 / Cloudflare challenge
  134. uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend auto
  135. ```
  136. 2. **Per-call override** via the `backend` argument on the `fetch_content` tool (overrides the CLI default for that single call). The tool exposes `backend` in its input schema, so an MCP client can choose `"httpx"`, `"curl"`, or `"auto"` on a fetch-by-fetch basis.
  137. For `fetch_content`, the default stays `httpx` so users who don't need the impersonation don't pay for the extra dependency.
  138. #### Search backend
  139. Because DuckDuckGo's search endpoint now fingerprint-blocks plain `httpx`, the `search` tool defaults to **`auto`**: it tries `httpx` first and falls back to `curl` when it detects a block (HTTP 202/403). The fallback only works if the `[browser]` extra is installed; otherwise search returns a message telling you to install it.
  140. Configure the search backend with the `--search-backend` CLI flag or the `DDG_SEARCH_BACKEND` environment variable (`auto` (default) / `httpx` / `curl`):
  141. ```bash
  142. # Recommended: install the browser extra so the auto fallback can impersonate Chrome
  143. uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server
  144. # Force curl for every search
  145. uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --search-backend curl
  146. # Opt out of the fallback (legacy behavior — may return no results while blocked)
  147. uvx duckduckgo-mcp-server --search-backend httpx
  148. ```
  149. ### Development
  150. For local development:
  151. ```bash
  152. # Install dependencies
  153. uv sync
  154. # Run with the MCP Inspector
  155. mcp dev src/duckduckgo_mcp_server/server.py
  156. # Install locally for testing with Claude Desktop
  157. mcp install src/duckduckgo_mcp_server/server.py
  158. # Run all tests
  159. uv run python -m pytest src/duckduckgo_mcp_server/ -v
  160. # Run only unit tests
  161. uv run python -m pytest src/duckduckgo_mcp_server/test_server.py -v
  162. # Run only e2e tests
  163. uv run python -m pytest src/duckduckgo_mcp_server/test_e2e.py -v
  164. ```
  165. ## Available Tools
  166. ### 1. Search Tool
  167. ```python
  168. async def search(query: str, max_results: int = 10, region: str = "") -> str
  169. ```
  170. Performs a web search on DuckDuckGo and returns formatted results.
  171. **Parameters:**
  172. - `query`: Search query string
  173. - `max_results`: Maximum number of results to return (default: 10)
  174. - `region`: (Optional) Region/language code to override the default. Leave empty to use the configured default region.
  175. **Region Code Examples:**
  176. - `us-en`: United States (English)
  177. - `cn-zh`: China (Chinese)
  178. - `jp-ja`: Japan (Japanese)
  179. - `de-de`: Germany (German)
  180. - `fr-fr`: France (French)
  181. - `wt-wt`: No specific region
  182. **Returns:**
  183. Formatted string containing search results with titles, URLs, and snippets.
  184. **Example Usage:**
  185. - Search with default settings: `search("python tutorial")`
  186. - Search with specific region: `search("latest news", region="jp-ja")` for Japanese news
  187. ### 2. Content Fetching Tool
  188. ```python
  189. async def fetch_content(
  190. url: str,
  191. start_index: int = 0,
  192. max_length: int = 8000,
  193. backend: Optional[str] = None,
  194. parse_mode: Optional[str] = None,
  195. ) -> str
  196. ```
  197. Fetches and parses content from a webpage.
  198. **Parameters:**
  199. - `url`: The webpage URL to fetch content from, or a `ref://<id>` token from search results
  200. - `start_index`: Character offset to start reading from (for pagination)
  201. - `max_length`: Maximum number of characters to return
  202. - `backend`: Optional per-call override of the default fetch backend (`"httpx"`, `"curl"`, or `"auto"`). When omitted, uses whatever was set via `--fetch-backend` at server startup.
  203. - `parse_mode`: Optional per-call extractor (`"text"`, `"main"`, or `"markdown"`). When omitted, uses `DDG_PARSE_MODE` / `--parse-mode` (default `text`).
  204. **Returns:**
  205. Cleaned and formatted text content from the webpage. The parsed full page is cached in memory (default 5 minutes) so later pages via `start_index` do not re-download. Metadata includes `cache=hit` or `cache=miss` when the cache is enabled.
  206. > **SSRF protection:** By default `fetch_content` refuses URLs that resolve to
  207. > loopback, private (RFC1918), link-local (including the `169.254.169.254` cloud
  208. > metadata endpoint), reserved, multicast, or unspecified addresses, and it
  209. > re-validates every redirect hop. Only `http`/`https` URLs are allowed. For
  210. > trusted local deployments that need to fetch internal hosts, disable the guard
  211. > with `DDG_ALLOW_PRIVATE_URLS=1` or `--allow-private-urls`. See
  212. > [SECURITY.md](SECURITY.md) for details.
  213. ### 3. Link Expansion Tool
  214. ```python
  215. async def expand_link(token: str) -> str
  216. ```
  217. Search results replace URLs longer than `DDG_REF_URL_THRESHOLD` characters (default 120) with short, stable `ref://<id>` tokens so long tracking-laden links do not eat context. `fetch_content` accepts a token in place of a URL, so the model only needs this tool when it has to show or cite the real link.
  218. **Parameters:**
  219. - `token`: A `ref://<id>` token exactly as it appeared in search results (the bare id also works)
  220. **Returns:**
  221. The full original URL, or an error if the token is unknown. Tokens live in memory for the lifetime of the server process (bounded by an LRU cap), so they are forgotten on restart.
  222. ## Features in Detail
  223. ### Rate Limiting
  224. - Search: 30 requests per minute by default (`DDG_SEARCH_RPM` / `--search-rpm`)
  225. - Content fetching: 20 requests per minute globally (`DDG_FETCH_RPM` / `--fetch-rpm`)
  226. - Optional per-host fetch cap, off by default (`DDG_FETCH_HOST_RPM` / `--fetch-host-rpm`)
  227. - Strategies: `sliding` (default) or `token_bucket` via `DDG_RATE_LIMIT_STRATEGY` / `--rate-limit-strategy`
  228. - HTTP 429 responses honor `Retry-After` (capped at 30s) and retry once
  229. - Cache hits on `fetch_content` skip both the download and the fetch rate limiter
  230. ### Content cache
  231. - In-memory TTL cache of the fully parsed page (before pagination)
  232. - Default TTL 300 seconds, 64 entries, least-recently-used eviction
  233. - Errors are never cached
  234. - Configure with `DDG_CACHE_TTL` / `DDG_CACHE_MAX_ENTRIES` or `--cache-ttl` / `--cache-max-entries`
  235. - Set either value to `0` to disable
  236. ### Result Processing
  237. - Removes ads and irrelevant content
  238. - Cleans up DuckDuckGo redirect URLs
  239. - Formats results for optimal LLM consumption
  240. - Truncates long content appropriately
  241. ### Content parsing modes
  242. `fetch_content` accepts `parse_mode`:
  243. | Mode | Behavior |
  244. | --- | --- |
  245. | `text` | Historical default. Strip chrome, return flattened page text. |
  246. | `main` | Keep the primary `article` / `main` / content container only. |
  247. | `markdown` | Same primary content, rendered as lightweight markdown (headings, lists, links, code). |
  248. ### Content Safety
  249. - **SafeSearch Filtering**: Configured at server startup via `DDG_SAFE_SEARCH` environment variable
  250. - Controlled by administrators, not modifiable by AI assistants
  251. - Filters inappropriate content based on the selected level
  252. - Uses DuckDuckGo's official `kp` parameter
  253. - **Region Localization**:
  254. - Default region set via `DDG_REGION` environment variable
  255. - Can be overridden per search request by AI assistants
  256. - Improves result relevance for specific geographic regions
  257. ### Error Handling
  258. - Comprehensive error catching and reporting
  259. - Detailed logging through MCP context
  260. - Graceful degradation on rate limits or timeouts
  261. ## Contributing
  262. Issues and pull requests are welcome!
  263. ## License
  264. This project is licensed under the MIT License.
  265. ## Star History
  266. [![Star History Chart](https://api.star-history.com/svg?repos=nickclyde/duckduckgo-mcp-server&type=Date)](https://star-history.com/#nickclyde/duckduckgo-mcp-server&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.