ddg-mcp MCP服务器

DuckDuckGo搜索API MCP - 通过模型上下文协议提供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安装

# 使用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迷你模型
• llama-3.3-70b：Meta的Llama 3.3 70B模型
• claude-3-haiku：Anthropic的Claude 3 Haiku模型
• o3-mini：OpenAI的O3迷你模型
• mistral-small-3：Mistral AI的小型模型

快速入门

安装

Claude桌面

在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”，并设置region为“us-en”，safesearch为“off”，timelimit为“y”，max_results为20

图片搜索

使用ddg-image-search工具查找“可再生能源”的图片，并将颜色设置为“Green”

高级示例：

使用ddg-image-search工具查找“山景”的图片，并设置size为“Large”，color为“Blue”，type_image为“photo”，layout为“Wide”，license_image为“Public”

新闻搜索

使用ddg-news-search工具查找最近关于“人工智能”的新闻，时间范围为最近一天

高级示例：

使用ddg-news-search工具搜索“太空探索”，并设置region为“uk-en”，timelimit为“w”，max_results为15

视频搜索

使用ddg-video-search工具查找关于“机器学习教程”的视频，并将duration设置为“medium”

高级示例：

使用ddg-video-search工具搜索“烹饪食谱”，并设置resolution为“high”，duration为“short”，license_videos为“creativeCommon”，max_results为10

AI聊天

使用ddg-ai-chat工具询问“量子计算的最新发展是什么？”并使用claude-3-haiku模型

搜索结果摘要

使用search-results-summary提示，查询“太空探索”，并设置style为“详细”

Claude配置

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

开发

构建和发布

为了准备分发的包：

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

uv sync

2. 构建包分布：

uv build

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

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发行版
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服务器通过标准I/O运行，调试可能会很困难。为了获得最佳的调试体验，我们强烈建议使用MCP Inspector。

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

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

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