DuckDuckGo MCP

DuckDuckGo搜索MCP服务器

](https://pypi.org/project/duckduckgo-mcp-server/) ](https://pypi.org/project/duckduckgo-mcp-server/) ](https://pypi.org/project/duckduckgo-mcp-server/)

一种模型上下文协议（MCP）服务器，通过DuckDuckGo提供网络搜索功能，并具有用于内容获取和解析的附加功能。

快速开始

uvx duckduckgo-mcp-server

特性

• 网络搜索：使用高级速率限制和结果格式搜索DuckDuckGo
• 内容获取：通过智能文本提取检索和解析网页内容
• 速率限制：内置对搜索和内容获取速率限制的保护
• 错误处理：全面的错误处理和记录
• LLM友好输出：专门为大型语言模型使用而格式化的结果

安装

使用以下命令从PyPI安装 uv:

uv pip install duckduckgo-mcp-server

用法

使用Claude Desktop运行

1. 下载 克劳德桌面版
2. 创建或编辑您的Claude Desktop配置：

- 在macOS上： ~/Library/Application Support/Claude/claude_desktop_config.json - 在Windows上： %APPDATA%\Claude\claude_desktop_config.json

添加以下配置：

基本配置（无安全搜索，无默认区域）：

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

使用安全搜索和区域配置：

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

配置选项：

• DDG_SAFE_SEARCH：安全搜索过滤级别（可选）

- STRICT：最大内容过滤（kp=1） - MODERATE：平衡过滤（kp=-1，如果未指定，则默认值） - OFF：无内容过滤（kp=-2）

• DDG_REGION：默认地区/语言代码（可选，示例如下）

- us-en：美国（英语） - cn-zh：中国（中文） - jp-ja：日本（日语） - wt-wt：无特定区域 - 为DuckDuckGo的默认行为留空

1. 重新启动克劳德桌面

使用Claude代码运行

1. 下载 克劳德代码
2. 确保 uvenv 已安装 uvx 命令可用
3. 添加MCP服务器： claude mcp add ddg-search uvx duckduckgo-mcp-server

使用SSE或流式HTTP运行

服务器支持与其他MCP客户端一起使用的替代传输：

# SSE transport
uvx duckduckgo-mcp-server --transport sse

# Streamable HTTP transport
uvx duckduckgo-mcp-server --transport streamable-http

默认传输方式为 stdio，由Claude Desktop和Claude Code使用。

跑步时 sse 或 streamable-http，覆盖默认绑定地址(127.0.0.1:8000)与 --host 和 --port 旗帜：

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

获取后端（绕过机器人检测）

某些网站会阻止默认设置 httpx 客户端，因为其独特的TLS指纹，无论用户代理——Cloudflare Bot Management和类似的过滤器密钥是在JA3/TLS握手上，而不是在标头上。选择加入后端， curl （通过实施 curl_cffi)，模拟真实Chrome浏览器的TLS握手并通过这些检查。

安装：

# Default install (httpx only)
uv pip install duckduckgo-mcp-server

# With the optional browser backend
uv pip install "duckduckgo-mcp-server[browser]"

后端选项：

配置后端的两种方法：

1. 服务器范围默认值 通过 --fetch-backend CLI标志（适用于每个 fetch_content 呼叫）：

   # Default behavior — uses httpx
   uvx duckduckgo-mcp-server

   # Force curl for every fetch (requires the [browser] extra)
   uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend curl

   # Try httpx first, fall back to curl on 403 / Cloudflare challenge
   uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend auto

1. 每次呼叫覆盖 通过 backend 关于 fetch_content 工具（覆盖该单个调用的CLI默认值）。该工具暴露 backend 在其输入模式中，因此MCP客户端可以选择 "httpx", "curl"，或 "auto" 以逐个提取为基础。

这 search 工具总是使用 httpx --DuckDuckGo的搜索端点不需要模拟。

默认值保持不变 httpx 因此，不需要模拟的用户不会为额外的依赖性付费。

发展

对于当地发展：

# Install dependencies
uv sync

# Run with the MCP Inspector
mcp dev src/duckduckgo_mcp_server/server.py

# Install locally for testing with Claude Desktop
mcp install src/duckduckgo_mcp_server/server.py

# Run all tests
uv run python -m pytest src/duckduckgo_mcp_server/ -v

# Run only unit tests
uv run python -m pytest src/duckduckgo_mcp_server/test_server.py -v

# Run only e2e tests
uv run python -m pytest src/duckduckgo_mcp_server/test_e2e.py -v

可用工具

1.搜索工具

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

在DuckDuckGo上执行网络搜索并返回格式化结果。

参数：

• query：搜索查询字符串
• max_results：要返回的最大结果数（默认值：10）
• region：（可选）覆盖默认值的地区/语言代码。留空以使用配置的默认区域。

地区代码示例：

• us-en：美国（英语）
• cn-zh：中国（中文）
• jp-ja：日本（日语）
• de-de：德国（德语）
• fr-fr：法国（法语）
• wt-wt：无特定区域

退货： 包含带有标题、URL和片段的搜索结果的格式化字符串。

示例用法：

• 使用默认设置搜索： search("python tutorial")
• 按特定地区搜索： search("latest news", region="jp-ja") 日本新闻

2.内容获取工具

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

从网页中获取和解析内容。

参数：

• url：从中获取内容的网页URL
• start_index：开始读取的字符偏移量（用于分页）
• max_length：要返回的最大字符数
• backend：默认获取后端的可选每次调用覆盖("httpx", "curl"，或 "auto").省略时，使用通过设置的任何内容 --fetch-backend 在服务器启动时。

退货： 已清理并格式化网页中的文本内容。

详细功能

速率限制

• 搜索：每分钟限制30个请求
• 内容获取：每分钟限制20个请求
• 自动队列管理和等待时间

结果处理

• 删除广告和无关内容
• 清理DuckDuckGo重定向URL
• 格式化结果以实现最佳LLM消耗
• 适当截断长内容

内容安全

• 安全搜索过滤：在服务器启动时通过配置 DDG_SAFE_SEARCH 环境变量

- 由管理员控制，不可由AI助手修改 - 根据所选级别过滤不合适的内容 - 使用DuckDuckGo官方 kp 参数

• 区域定位:

- 通过设置默认区域 DDG_REGION 环境变量 - AI助手可以根据搜索请求覆盖 - 提高特定地理区域的结果相关性

错误处理

• 全面的错误捕获和报告
• 通过MCP上下文进行详细日志记录
• 在速率限制或超时方面表现良好

贡献

欢迎问题和拉取请求！一些有待改进的领域：

• 增强的内容解析选项
• 用于频繁访问内容的缓存层
• 额外的限速策略

许可证

该项目根据MIT许可证获得许可。

明星历史