ddg-mcp MCP 服务器

DuckDuckGo 搜索 API MCP - 一个通过模型上下文协议提供 DuckDuckGo 搜索功能的服务器。

组件

提示词 (Prompts)

该服务器提供以下提示词：

• search-results-summary: 创建 DuckDuckGo 搜索结果的摘要
  • 必需参数 "query"：搜索词
  • 可选参数 "style"：控制详细程度 (brief/detailed)

工具 (Tools)

该服务器实现了以下 DuckDuckGo 搜索工具：

• ddg-text-search: 使用 DuckDuckGo 搜索网络文本结果

  • 必需参数: "keywords" - 搜索查询关键词
  • 可选参数: "region", "safesearch", "timelimit", "max_results"

• ddg-image-search: 使用 DuckDuckGo 搜索网络图片

  • 必需参数: "keywords" - 搜索查询关键词
  • 可选参数: "region", "safesearch", "timelimit", "size", "color", "type_image", "layout", "license_image", "max_results"

• ddg-news-search: 使用 DuckDuckGo 搜索新闻文章

  • 必需参数: "keywords" - 搜索查询关键词
  • 可选参数: "region", "safesearch", "timelimit", "max_results"

• ddg-video-search: 使用 DuckDuckGo 搜索视频

  • 必需参数: "keywords" - 搜索查询关键词
  • 可选参数: "region", "safesearch", "timelimit", "resolution", "duration", "license_videos", "max_results"

• ddg-ai-chat: 与 DuckDuckGo AI 聊天

  • 必需参数: "keywords" - 发送给 AI 的消息或问题
  • 可选参数: "model" - 使用的 AI 模型 (选项: "gpt-4o-mini", "llama-3.3-70b", "claude-3-haiku", "o3-mini", "mistral-small-3")

安装

前提条件

• Python 3.9 或更高版本
• uv (推荐) 或 pip

从 PyPI 安装

# 使用 uv
uv install ddg-mcp

# 使用 pip
pip install ddg-mcp

从源代码安装

1. 克隆仓库:

git clone https://github.com/misanthropic-ai/ddg-mcp.git
cd ddg-mcp

2. 安装包:

# 使用 uv
uv install -e .

# 使用 pip
pip install -e .

配置

必需依赖

该服务器需要 duckduckgo-search 包，它会在您安装 ddg-mcp 时自动安装。

如果您需要手动安装它：

uv install duckduckgo-search
# 或
pip install duckduckgo-search

DuckDuckGo 搜索参数

常用参数

这些参数适用于大多数搜索类型：

• region: 本地化结果的区域代码 (默认: "wt-wt")

  • 示例: "us-en" (美国英语), "uk-en" (英国英语), "ru-ru" (俄语)
  • 更多选项请参见 DuckDuckGo 区域

• safesearch: 内容过滤级别 (默认: "moderate")

  • "on": 严格过滤
  • "moderate": 中等过滤
  • "off": 无过滤

• timelimit: 结果的时间范围

  • "d": 过去一天
  • "w": 过去一周
  • "m": 过去一个月
  • "y": 过去一年 (不适用于新闻/视频)

• max_results: 返回的最大结果数 (默认: 10)

搜索运算符

您可以在搜索关键词中使用以下运算符：

• cats dogs: 关于猫或狗的结果
• "cats and dogs": 精确术语 "cats and dogs" 的结果
• cats -dogs: 结果中狗较少
• cats +dogs: 结果中狗较多
• cats filetype:pdf: 关于猫的 PDF (支持: pdf, doc(x), xls(x), ppt(x), html)
• dogs site:example.com: 来自 example.com 的关于狗的页面
• cats -site:example.com: 关于猫的页面，排除 example.com
• intitle:dogs: 页面标题包含单词 "dogs"
• inurl:cats: 页面 URL 包含单词 "cats"

图片搜索特定参数

• size: "Small", "Medium", "Large", "Wallpaper"
• color: "color", "Monochrome", "Red", "Orange", "Yellow", "Green", "Blue", "Purple", "Pink", "Brown", "Black", "Gray", "Teal", "White"
• type_image: "photo", "clipart", "gif", "transparent", "line"
• layout: "Square", "Tall", "Wide"
• license_image: "any", "Public", "Share", "ShareCommercially", "Modify", "ModifyCommercially"

视频搜索特定参数

• resolution: "high", "standard"
• duration: "short", "medium", "long"
• license_videos: "creativeCommon", "youtube"

AI 聊天模型

• gpt-4o-mini: OpenAI 的 GPT-4o mini 模型
• llama-3.3-70b: Meta 的 Llama 3.3 70B 模型
• claude-3-haiku: Anthropic 的 Claude 3 Haiku 模型
• o3-mini: OpenAI 的 O3 mini 模型
• mistral-small-3: Mistral AI 的 small 模型

快速开始

安装

Claude Desktop

在 MacOS 上: ~/Library/Application\ Support/Claude/claude_desktop_config.json 在 Windows 上: %APPDATA%/Claude/claude_desktop_config.json

<details> <summary>开发/未发布的服务器配置</summary>

"mcpServers": {
  "ddg-mcp": {
    "command": "uv",
    "args": [
      "--directory",
      "/Users/shannon/Workspace/artivus/ddg-mcp",
      "run",
      "ddg-mcp"
    ]
  }
}

</details>

<details> <summary>已发布的服务器配置</summary>

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

</details>

使用示例

文本搜索

使用 ddg-text-search 工具搜索 "气候变化解决方案"

高级示例:

使用 ddg-text-search 工具搜索 "可再生能源 filetype:pdf site:edu"，区域为 "us-en"，安全搜索为 "off"，时间限制为 "y"，最大结果数为 20

图片搜索

使用 ddg-image-search 工具查找颜色设置为 "绿色" 的 "可再生能源" 图片

高级示例:

使用 ddg-image-search 工具查找大小为 "Large"，颜色为 "Blue"，图片类型为 "photo"，布局为 "Wide"，许可证为 "Public" 的 "山地景观" 图片

新闻搜索

使用 ddg-news-search 工具查找过去一天关于 "人工智能" 的最新新闻

高级示例:

使用 ddg-news-search 工具搜索 "太空探索"，区域为 "uk-en"，时间限制为 "w"，最大结果数为 15

视频搜索

使用 ddg-video-search 工具查找持续时间设置为 "medium" 的关于 "机器学习教程" 的视频

高级示例:

使用 ddg-video-search 工具搜索分辨率为 "high"，持续时间为 "short"，视频许可证为 "creativeCommon"，最大结果数为 10 的 "烹饪食谱"

AI 聊天

使用 ddg-ai-chat 工具，使用 claude-3-haiku 模型提问 "量子计算的最新进展是什么？"

搜索结果摘要

使用 search-results-summary 提示词，查询 "太空探索"，样式为 "detailed"

Claude 配置

"ddg-mcp": { "command": "uv", "args": [ "--directory", "/PATH/TO/YOUR/INSTALLATION/ddg-mcp", "run", "ddg-mcp" ] },

开发

构建和发布

要准备用于分发的软件包：

1. 同步依赖项并更新锁定文件：

uv sync

2. 构建软件包分发：

uv build

这将在 dist/ 目录中创建源和 wheel 分发。

3. 发布到 PyPI：

uv publish

注意：您需要通过环境变量或命令标志设置 PyPI 凭据：

• Token: --token 或 UV_PUBLISH_TOKEN
• 或用户名/密码：--username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

使用 GitHub Actions 自动发布

此存储库包含一个 GitHub Actions 工作流程，用于自动发布到 PyPI。 当以下情况发生时，将触发该工作流程：

1. 创建新的 GitHub Release
2. 通过 GitHub Actions 界面手动触发工作流程

要设置自动发布：

1. 生成 PyPI API 令牌：

   • 转到 https://pypi.org/manage/account/token/
   • 创建一个新令牌，其范围仅限于 ddg-mcp 项目
   • 复制令牌值（您只会看到一次）

2. 将令牌添加到您的 GitHub 存储库机密：

   • 转到 GitHub 上的存储库
   • 导航到 Settings > Secrets and variables > Actions
   • 点击“New repository secret”
   • 名称：PYPI_API_TOKEN
   • 值：粘贴您的 PyPI 令牌
   • 点击“Add secret”

3. 要发布新版本：

   • 更新 pyproject.toml 中的版本号
   • 在 GitHub 上创建一个新版本或手动触发工作流程

调试

由于 MCP 服务器通过 stdio 运行，因此调试可能具有挑战性。 为了获得最佳调试体验，我们强烈建议使用 MCP Inspector。

您可以通过 npm 使用以下命令启动 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /path/to/your/ddg-mcp run ddg-mcp

启动后，Inspector 将显示一个 URL，您可以在浏览器中访问该 URL 以开始调试。