DuckDuckGo 搜索 MCP 服务器

👁 PyPI version
👁 PyPI downloads
👁 Python versions

一个模型上下文协议 (MCP) 服务器，通过 DuckDuckGo 提供网络搜索功能，并具备内容抓取和解析的附加功能。

快速开始

uvx duckduckgo-mcp-server

Related MCP server: Duck Duck MCP

功能

• 网络搜索：通过 DuckDuckGo 进行搜索，具备高级速率限制和结果格式化功能

• 内容抓取：通过智能文本提取获取并解析网页内容

• 速率限制：内置针对搜索和内容抓取的速率限制保护

• 错误处理：全面的错误处理和日志记录

• LLM 友好输出：专门为大语言模型消费而格式化的结果

安装

使用 uv 从 PyPI 安装：

uv pip install duckduckgo-mcp-server

使用方法

在 Claude Desktop 中运行

1. 下载 Claude Desktop

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 的默认行为

3. 重启 Claude Desktop

在 Claude Code 中运行

1. 下载 Claude Code

2. 确保已安装 uvenv 且 uvx 命令可用

3. 添加 MCP 服务器：claude mcp add ddg-search uvx duckduckgo-mcp-server

使用 SSE 或 Streamable 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 运行时，请使用 --host 和 --port 标志覆盖默认绑定地址 (127.0.0.1:8000)：

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

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

某些网站会因为默认 httpx 客户端独特的 TLS 指纹而将其拦截，无论 User-Agent 如何——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

2. 单次调用覆盖：通过 fetch_content 工具上的 backend 参数（覆盖该次调用的 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 许可证。

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• fetch_contentA
• searchA