ddg-mcp MCP 服务器

DuckDuckGo 搜索 API MCP - 一个通过 Model Context Protocol 提供 DuckDuckGo 搜索功能的服务器。

组件

提示

服务器提供以下提示：

• search-results-summary: 创建 DuckDuckGo 搜索结果的摘要
  • 需要 "query" 参数作为搜索词
  • 可选 "style" 参数来控制详细程度（简略/详细）

工具

服务器实现了以下 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 安装

# Using uv
uv install ddg-mcp

# Using pip
pip install ddg-mcp

从源代码安装

1. 克隆仓库：

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

1. 安装包：

# Using uv
uv install -e .

# Using pip
pip install -e .

配置

必需依赖

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

如果您需要手动安装：

uv install duckduckgo-search
# or
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 的小型模型

快速开始

安装

Claude 桌面版

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

使用示例

文本搜索

Use the ddg-text-search tool to search for "climate change solutions"

高级示例：

Use the ddg-text-search tool to search for "renewable energy filetype:pdf site:edu" with region "us-en", safesearch "off", timelimit "y", and max_results 20

图片搜索

Use the ddg-image-search tool to find images of "renewable energy" with color set to "Green"

高级示例：

Use the ddg-image-search tool to find images of "mountain landscape" with size "Large", color "Blue", type_image "photo", layout "Wide", and license_image "Public"

新闻搜索

Use the ddg-news-search tool to find recent news about "artificial intelligence" from the last day

高级示例：

Use the ddg-news-search tool to search for "space exploration" with region "uk-en", timelimit "w", and max_results 15

视频搜索

Use the ddg-video-search tool to find videos about "machine learning tutorials" with duration set to "medium"

高级示例：

Use the ddg-video-search tool to search for "cooking recipes" with resolution "high", duration "short", license_videos "creativeCommon", and max_results 10

AI 聊天

Use the ddg-ai-chat tool to ask "What are the latest developments in quantum computing?" using the claude-3-haiku model

搜索结果摘要

Use the search-results-summary prompt with query "space exploration" and style "detailed"

Claude 配置

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

开发

构建和发布

为分发准备包：

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

uv sync

1. 构建包分发：

uv build

这将在 dist/ 目录中创建源码和轮子分发。

1. 发布到 PyPI：

uv publish

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

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

使用 GitHub Actions 自动发布

此仓库包含一个用于自动发布到 PyPI 的 GitHub Actions 工作流。该工作流在以下情况下触发：

1. 创建一个新的 GitHub 发布
2. 通过 GitHub Actions 界面手动触发

要设置自动发布：

1. 生成 PyPI API 令牌：

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

2. 将令牌添加到您的 GitHub 仓库密钥中：

   • 前往您的 GitHub 仓库
   • 导航至 设置 > 密钥和变量 > 操作
   • 单击“新建仓库密钥”
   • 名称：PYPI_API_TOKEN
   • 值：粘贴您的 PyPI 令牌
   • 单击“添加密钥”

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 开始调试。