# duckduckgo-mcp-server review: DuckDuckGo search and page parsing for MCP clients

> duckduckgo-mcp-server is a Python MCP server for DuckDuckGo web search, page fetching, and text extraction. It suits local MCP clients that need rate-limited search results and content parsing, while its HTTP exposure and TLS handling require careful configuration.

**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.

- Repository: https://github.com/nickclyde/duckduckgo-mcp-server
- Stars: 1,550 · Forks: 195
- Language: Python
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/nickclyde-duckduckgo-mcp-server

## DuckDuckGo search and extraction for MCP clients

duckduckgo-mcp-server addresses a specific integration gap: giving an MCP client a search tool backed by DuckDuckGo, followed by a way to retrieve and parse selected pages. The project is aimed at developers configuring assistants or other MCP-compatible clients that need current web material without building a separate search integration. The README describes web search through DuckDuckGo, content fetching, parsed text extraction, rate limiting, error handling, and output formatted for language-model consumption.

The server does more than return titles and links. Search results can be formatted for an LLM, while long result URLs can be replaced by short ref:// tokens that fetch_content accepts directly. This is a deliberate context-saving mechanism, not a URL-shortening service for publication. A client can receive a compact result list, select a result, and then request its content through the server.

The package metadata identifies the project as an MCP Server for searching via DuckDuckGo. It requires Python 3.10 or later and depends on beautifulsoup4, httpx, httpcore, and mcp[cli]. The repository also includes a Dockerfile, src/, pyproject.toml, and uv.lock. The README labels the project as an alpha release, which is an important adoption boundary even though recent releases are listed.

## Search, ref tokens, and parsed content flow

The documented flow has two principal tools. The search capability queries DuckDuckGo and formats the results for an MCP client. The fetch_content capability retrieves a page and parses its content into text-oriented output. The README lists text, main, and markdown as parse modes, with text as the default historical flattened page format. A per-call parse_mode can override the default, which lets a client choose a representation for a particular page instead of changing the server-wide default.

The ref:// behavior affects the handoff between those tools. Search-result URLs longer than DDG_REF_URL_THRESHOLD are replaced with compact reference tokens, and fetch_content accepts those tokens. The default threshold is 120 characters. Setting it to 0 shows full URLs. This design reduces the amount of URL text sent through model context, but it also makes search output less directly readable to a human inspecting a result list.

Fetched pages can be cached in memory. DDG_CACHE_TTL controls how long a parsed page remains available, with a default of 300 seconds. DDG_CACHE_MAX_ENTRIES limits the cache to 64 pages by default and uses least-recently-used eviction. Setting either value to 0 disables the corresponding cache behavior. Paginated reads of the same URL can reuse one download, according to the README. The cache is process-local and in-memory, so the documentation does not describe persistent storage or cross-instance coordination.

## Rate limits, SafeSearch, and regional results

The server includes separate controls for search and page fetching. DDG_SEARCH_RPM defaults to 30 search requests per minute, while DDG_FETCH_RPM defaults to 20 global fetch_content requests per minute. DDG_FETCH_HOST_RPM can add a per-host cap and defaults to 0, which is off. Rate limiting uses a sliding window by default. DDG_RATE_LIMIT_STRATEGY can change that behavior to token_bucket, described as a burst followed by smoothing. These controls are useful when an MCP client may issue bursts of tool calls.

SafeSearch is configured through DDG_SAFE_SEARCH. STRICT uses kp=1, MODERATE uses kp=-1 and is the default when no value is specified, and OFF uses kp=-2. DDG_REGION selects a default region and language code, including us-en, cn-zh, jp-ja, and wt-wt. Leaving it empty preserves DuckDuckGo's default behavior. Region affects the search request, not the language in which duckduckgo-mcp-server itself logs or communicates.

The configuration is explicit enough for basic deployments, but it also exposes a product limitation. Search quality, available results, and regional behavior remain dependent on DuckDuckGo's endpoint. The README does not claim that this server provides an independent index, guaranteed result completeness, or stable ranking. It is a client-side MCP interface around DuckDuckGo.

## Local installation and a first Claude Desktop connection

The quickest documented start uses uvx, which runs the package without a separate virtual-environment setup step. For an installed package, the README uses uv pip. The project also publishes a package entry point named duckduckgo-mcp-server, but the configuration examples launch it through uvx.

For Claude Desktop, add the server to the platform-specific configuration file and restart the application. The basic configuration uses uvx as the command and duckduckgo-mcp-server as its only argument.

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

The reader should see the server entry appear as ddg-search in Claude Desktop after restarting it. To apply SafeSearch and a region, add the documented environment variables to the same server object.

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

The README says to edit claude_desktop_config.json under ~/Library/Application Support/Claude on macOS or %APPDATA%\Claude on Windows. It does not document a separate first-search prompt, so the first real use is the configured MCP connection followed by a client request that invokes search and, if needed, fetch_content.

## Claude Code and HTTP transport deployment

Claude Code has a shorter registration path. The README requires uvenv to be installed so that the uvx command is available, then gives this command.

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

After registration, the command stores the MCP server definition for that client. The README does not provide a specific prompt or output transcript for the first search.

For clients other than Claude Desktop and Claude Code, the server supports sse and streamable-http transports. The default transport is stdio. The HTTP transports bind to 127.0.0.1:8000 by default, and --host and --port change the bind address.

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

Binding to 0.0.0.0 changes the reachable network scope. The MCP SDK enables DNS-rebinding protection for HTTP transports and accepts localhost Host and Origin headers by default. A reverse proxy or container can therefore receive 421 Misdirected Request unless the actual host and origin are allow-listed with --allowed-hosts and --allowed-origins. Equivalent environment variables are DDG_ALLOWED_HOSTS and DDG_ALLOWED_ORIGINS. The README presents --disable-dns-rebinding-protection as a last resort and recommends the allow-list instead.

## TLS proxies, fetch backends, and deployment constraints

The server documents two operational boundaries that matter outside a local desktop setup. First, TLS-intercepting corporate proxies can break outbound requests because the proxy presents its own certificate authority. Instead of disabling verification broadly, the documented option is --ca-certs or DDG_CA_CERTS, pointing to a PEM CA bundle. The setting applies to search and fetch_content requests across httpx and curl backends. The README also documents --no-ssl-verify, but explicitly warns that it exposes traffic to interception and should be a last resort.

```bash
uvx duckduckgo-mcp-server --ca-certs /path/to/proxy-ca.pem
```

Second, the project includes an optional browser extra. The pyproject.toml defines browser as curl_cffi>=0.7.0. It enables --fetch-backend curl and auto fallback, using curl_cffi to impersonate a browser TLS fingerprint for fetch_content requests blocked by TLS-fingerprint-based bot filters. Basic use does not require this extra. The README also mentions that some sites block the default httpx client, which means fetching success is not guaranteed for every destination.

The Dockerfile uses python:3.13-slim, copies the repository into /app, installs the project, and sets the Python module entrypoint. The repository includes this container path, but the README does not document a complete Docker deployment configuration, including an MCP client network setup. That omission matters for operators who need to publish the HTTP transport beyond localhost.

## Maintenance, licensing, and adoption limits

The repository is not archived, and the listed release history includes v0.7.0 dated 2026-09-04, v0.6.1 dated 2026-07-28, and v0.6.0 dated 2026-07-27. The last push was on 2026-09-04. This information supports recent project activity at that point, but it does not establish long-term stability or compatibility guarantees. The package metadata still classifies development status as Alpha.

The license is MIT, so the repository carries a permissive open-source license. The metadata includes a LICENSE file and an MIT classifier. License obligations and suitability for a particular deployment should be checked against the actual LICENSE file and organizational policy; the project description alone is not legal advice.

The clearest wrong-tool case is a workload requiring authenticated or first-party search data, guaranteed freshness, a complete web index, or high-volume retrieval beyond the configured request limits. It is also a poor fit for unattended exposure of an HTTP MCP server without a deliberate host and origin policy. For a local assistant that needs DuckDuckGo search plus readable page content, the package offers a compact and configurable starting point, with the main adoption caveat being its alpha status and dependence on upstream search and page-access behavior.

## Conclusion

Adopt this server for a local MCP workflow that needs DuckDuckGo search and page extraction with modest control over formatting and throttling. Do not treat it as a general web index, a high-volume crawler, or a replacement for an authenticated search product, and first verify the client configuration, transport binding, rate limits, and certificate settings. The MIT-licensed Python project requires Python 3.10 or later and is classified as Development Status :: 3 - Alpha.

## FAQ

### How do I install duckduckgo-mcp-server?

The README documents running it with `uvx duckduckgo-mcp-server`. For an installed package, it gives `uv pip install duckduckgo-mcp-server`. The package requires Python 3.10 or later.

### How do I configure DuckDuckGo region and SafeSearch in duckduckgo-mcp-server?

Set `DDG_SAFE_SEARCH` to `STRICT`, `MODERATE`, or `OFF`, and set `DDG_REGION` to a code such as `us-en`, `cn-zh`, `jp-ja`, or `wt-wt`. The default SafeSearch mode is `MODERATE` when no value is specified.

### What is the purpose of ref:// tokens in duckduckgo-mcp-server?

Search-result URLs longer than the configured threshold are replaced with `ref://<id>` tokens to reduce context usage. The `fetch_content` tool accepts those tokens, and setting `DDG_REF_URL_THRESHOLD` to `0` disables replacement.

## Sources

- [Issues](https://github.com/nickclyde/duckduckgo-mcp-server/issues)
- [License: MIT](https://github.com/nickclyde/duckduckgo-mcp-server/blob/main/LICENSE)
- [nickclyde/duckduckgo-mcp-server on GitHub](https://github.com/nickclyde/duckduckgo-mcp-server)
- [README](https://github.com/nickclyde/duckduckgo-mcp-server/blob/main/README.md)
- [Releases](https://github.com/nickclyde/duckduckgo-mcp-server/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nickclyde-duckduckgo-mcp-server