用途

duckduckgo-mcp-server 是一个模型上下文协议（MCP）服务器，用于为 MCP 客户端（如 Claude Desktop、Claude Code 等）提供网页搜索能力，并通过 DuckDuckGo 完成搜索，同时附带内容抓取与解析功能。

主要能力

网页搜索：使用 DuckDuckGo 搜索，带有高级速率限制与结果格式化。
内容抓取：检索并解析网页内容，支持智能文本提取。
长 URL 缩短：过长的结果 URL 会被替换为简短的 ref:// 令牌，fetch_content 可直接接受这些令牌，从而节省上下文。
速率限制：为搜索和内容抓取内置了速率限制保护。
错误处理：全面的错误处理与日志记录。
面向 LLM 的输出：结果专门针对大语言模型的使用进行格式化。

提供的主要工具

搜索工具：在 DuckDuckGo 上执行网页搜索并返回格式化结果。参数包括 query（搜索查询字符串）、max_results（返回结果的最大数量，默认 10）、region（可选，覆盖默认区域/语言代码）。返回包含标题、URL 和摘要的格式化字符串。
内容抓取工具：抓取并解析网页内容。参数包括 url（要抓取内容的网页 URL，或搜索结果中的 ref:// 令牌）、start_index（用于分页的字符偏移起始位置）、max_length（返回的最大字符数）、backend（可选的单次调用抓取后端覆盖）、parse_mode（可选的单次调用提取器）。返回清理并格式化后的网页文本内容，解析后的整页会缓存在内存中（默认 5 分钟）。
链接展开工具：搜索结果中超过阈值（默认 120 字符）的 URL 会被替换为简短稳定的 ref:// 令牌，该工具可将其还原为完整原始 URL。

使用方式

从 PyPI 安装

使用 uv 从 PyPI 安装。

在 Claude Desktop 中运行

下载 Claude Desktop，创建或编辑 Claude Desktop 配置文件（macOS 路径：~/Library/Application Support/Claude/claude_desktop_config.json；Windows 路径：%APPDATA%\Claude\claude_desktop_config.json），添加相应配置后重启 Claude Desktop。

在 Claude Code 中运行

下载 Claude Code，确保已安装 uv 且 uvx 命令可用，然后添加 MCP 服务器：

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

使用 SSE 或 Streamable HTTP 运行

服务器支持用于其他 MCP 客户端的替代传输方式。默认传输是 stdio。使用 sse 或 streamable-http 运行时，可通过 --host 和 --port 标志覆盖默认绑定地址（127.0.0.1:8000）。MCP SDK 为 HTTP 传输启用了 DNS 重绑定保护，默认只接受 localhost 的 Host/Origin 头；在反向代理或容器后可通过 allow-list 配置允许的主机与来源（环境变量 DDG_ALLOWED_HOSTS、DDG_ALLOWED_ORIGINS），也可用 --disable-dns-rebinding-protection 关闭检查（不推荐）。

配置选项

DDG_SAFE_SEARCH：安全搜索过滤级别（STRICT 最大过滤 kp=1；MODERATE 平衡过滤 kp=-1，未指定时为默认；OFF 不过滤 kp=-2）。由管理员在服务器启动时配置，AI 助手无法修改。
DDG_REGION：默认区域/语言代码（如 us-en 美国英语、cn-zh 中国中文、jp-ja 日本日语、wt-wt 无特定区域；留空则使用 DuckDuckGo 默认行为）。可由 AI 助手在每次搜索请求中覆盖。
DDG_CA_CERTS：用于验证出站请求 TLS 证书的 PEM CA 包路径（可选）。
DDG_RATE_LIMIT_STRATEGY：sliding（默认，历史 60 秒窗口）或 token_bucket。
DDG_SEARCH_RPM：每分钟搜索请求数（默认 30）。
DDG_FETCH_RPM：每分钟全局 fetch_content 请求数（默认 20）。
DDG_FETCH_HOST_RPM：可选的每主机抓取上限（默认 0，即关闭）。
DDG_CACHE_TTL：解析页面在内存缓存中保留的秒数（默认 300），设为 0 可禁用。
DDG_CACHE_MAX_ENTRIES：缓存中保留的最大页面数（默认 64），采用最近最少使用淘汰。
DDG_PARSE_MODE：fetch_content 默认提取器（text、main 或 markdown），默认 text。
DDG_REF_URL_THRESHOLD：搜索结果 URL 超过此字符数会被替换为短 ref:// 令牌（默认 120），设为 0 始终显示完整 URL。

后端（绕过机器人检测）

部分网站以及 DuckDuckGo 自身的搜索端点（html.duckduckgo.com）会因默认 httpx 客户端的 TLS 指纹而拦截请求。可选的 curl 后端（通过 curl_cffi 实现）会模拟真实 Chrome 浏览器的 TLS 握手以通过检查。搜索与内容抓取工具均支持这些后端。后端选项包括 httpx、curl、auto；搜索工具默认使用 auto（先尝试 httpx，检测到拦截时回退到 curl，回退需要安装 [browser] 额外依赖）。可通过 --fetch-backend、--search-backend 命令行标志或 DDG_SEARCH_BACKEND 环境变量配置。

安全与限制

速率限制：搜索默认每分钟 30 次请求，内容抓取全局默认每分钟 20 次请求；HTTP 429 响应遵循 Retry-After（上限 30 秒）并重试一次；缓存命中会跳过下载与抓取速率限制。
缓存：内存 TTL 缓存，默认 TTL 300 秒、64 条目，采用 LRU 淘汰，错误不会被缓存。
SSRF 保护：默认 fetch_content 会拒绝解析到回环、私有（RFC1918）、链路本地（包括 169.254.169.254 云元数据端点）、保留、组播或未指定地址的 URL，并对每次重定向跳转重新验证，仅允许 http/https URL；可信本地部署可用 DDG_ALLOW_PRIVATE_URLS=1 或 --allow-private-urls 禁用该保护。
该服务器依赖 DuckDuckGo 的搜索端点，可能受到其反爬或指纹拦截策略的影响。

适用场景

适合需要为 MCP 客户端（Claude Desktop、Claude Code 等）提供网页搜索、网页内容抓取与解析能力的场景，例如让大语言模型检索网络信息并读取网页正文。

许可证

本项目采用 MIT 许可证。

duckduckgo-mcp-server

工具介绍

用途