DuckDuckGo 搜索 MCP 服务器

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

快速开始

uvx duckduckgo-mcp-server

特性

• 网页搜索：使用高级限流和结果格式化功能进行 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 或可流式 HTTP 运输

该服务器支持其他 MCP 客户端使用的替代传输方式：

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

# 可流式 HTTP 传输
uvx duckduckgo-mcp-server --transport streamable-http

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

开发

本地开发步骤：

# 安装依赖
uv sync

# 使用 MCP Inspector 运行
mcp dev src/duckduckgo_mcp_server/server.py

# 本地安装以供 Claude Desktop 测试
mcp install src/duckduckgo_mcp_server/server.py

# 运行所有测试
uv run python -m pytest src/duckduckgo_mcp_server/ -v

# 仅运行单元测试
uv run python -m pytest src/duckduckgo_mcp_server/test_server.py -v

# 仅运行端到端测试
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 教程")
• 指定地区搜索：search("最新新闻", region="jp-ja") 以获取日本新闻

2. 内容抓取工具

async def fetch_content(url: str) -> str

从网页抓取并解析内容。

参数：

• url：要抓取内容的网页 URL

返回值： 清理并格式化后的网页文本内容。

功能详解

限流机制

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

结果处理

• 移除广告和无关内容
• 清理 DuckDuckGo 重定向 URL
• 格式化结果以适应 LLM 最佳使用
• 对过长内容进行适当截断

内容安全

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

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

• 地区本地化：

  • 默认地区通过 DDG_REGION 环境变量设置
  • 可被 AI 助手在每次搜索请求中覆盖
  • 提高特定地理区域的结果相关性

错误处理

• 全面的错误捕获与报告
• 通过 MCP 上下文进行详细日志记录
• 在遇到限流或超时情况时实现优雅降级

贡献

欢迎提交问题和拉取请求！一些潜在的改进方向：

• 更强大的内容解析选项
• 针对频繁访问内容的缓存层
• 更多的限流策略

许可证

本项目采用 MIT 许可证授权。

DuckDuckGo Search MCP Server 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：macOS、Windows 或 Linux
• Python 版本：支持主流 Python 版本（具体兼容版本见 PyPI 页面）
• 前置依赖：推荐安装 uv 包管理器，它是运行此工具最便捷的方式。
  • 安装 uv (macOS/Linux): curl -LsSf https://astral.sh/uv/install.sh | sh
  • 安装 uv (Windows PowerShell): powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
• 客户端软件（可选）：若需集成到桌面端，请提前下载并安装 Claude Desktop。

提示：国内开发者若访问 PyPI 或 GitHub 较慢，可配置国内镜像源加速 uv 或 pip 的下载过程。

安装步骤

推荐使用 uv 进行全局安装或直接通过 uvx 按需运行。

方式一：直接运行（无需显式安装）

使用 uvx 可以直接拉取并运行最新版本的服务器，适合快速测试：

uvx duckduckgo-mcp-server

方式二：正式安装

若需将其作为项目依赖或固定版本使用：

uv pip install duckduckgo-mcp-server

基本使用

本工具主要作为 MCP (Model Context Protocol) 服务器运行，需配合支持 MCP 的客户端（如 Claude Desktop 或 Claude Code）使用。

1. 集成到 Claude Desktop

编辑 Claude Desktop 的配置文件以注册该服务。

• macOS 路径: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows 路径: %APPDATA%\Claude\claude_desktop_config.json

在配置文件的 mcpServers 节点中添加以下内容：

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

进阶配置（设置安全搜索与区域）： 若需针对中国用户优化搜索结果（如设置中文区域），可添加环境变量：

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

• DDG_REGION: 设置为 cn-zh 可优先获取中文结果。
• DDG_SAFE_SEARCH: 可选 STRICT (严格), MODERATE (适中), OFF (关闭)。

保存文件后，重启 Claude Desktop 即可生效。

2. 集成到 Claude Code

如果您使用命令行版的 Claude Code，可通过以下命令添加服务：

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

3. 功能验证

启动客户端后，AI 助手将自动拥有以下两个核心工具能力：

• 网络搜索 (search):
  • 示例指令：“帮我搜索最新的 Python 教程”
  • 底层调用：search(query="最新的 Python 教程", max_results=10, region="cn-zh")
• 内容抓取 (fetch_content):
  • 示例指令：“读取并总结这个网址的内容：https://example.com"
  • 底层调用：fetch_content(url="https://example.com")

工具会自动处理速率限制、广告过滤及格式清洗，返回适合大模型阅读的结构化文本。