DuckDuckGo MCP Server
ddg-mcp MCP 服务器
DuckDuckGo 搜索 API MCP - 通过模型上下文协议提供 DuckDuckGo 搜索功能的服务器。
成分
提示
服务器给出如下提示:
search-results-summary :创建 DuckDuckGo 搜索结果的摘要
搜索词的必需“查询”参数
可选的“样式”参数用于控制详细程度(简要/详细)
工具
服务器实现了以下 DuckDuckGo 搜索工具:
ddg-text-search :使用 DuckDuckGo 在网络上搜索文本结果
必需:“关键词” - 搜索查询关键词
可选:“region”、“safesearch”、“timelimit”、“max_results”
ddg-image-search :使用 DuckDuckGo 在网络上搜索图片
必需:“关键词” - 搜索查询关键词
可选:“区域”、“安全搜索”、“时间限制”、“大小”、“颜色”、“类型图像”、“布局”、“许可证图像”、“最大结果”
ddg-news-search :使用 DuckDuckGo 搜索新闻文章
必需:“关键词” - 搜索查询关键词
可选:“region”、“safesearch”、“timelimit”、“max_results”
ddg-video-search :使用 DuckDuckGo 搜索视频
必需:“关键词” - 搜索查询关键词
可选:“区域”、“安全搜索”、“时间限制”、“分辨率”、“持续时间”、“license_videos”、“max_results”
ddg-ai-chat :与 DuckDuckGo AI 聊天
必填:“关键词” - 发送给 AI 的消息或问题
可选:“模型”- 要使用的 AI 模型(选项:“gpt-4o-mini”、“llama-3.3-70b”、“claude-3-haiku”、“o3-mini”、“mistral-small-3”)
Related MCP server: DuckDuckGo MCP Server
安装
先决条件
Python 3.9 或更高版本
uv (推荐)或 pip
从 PyPI 安装
# Using uv
uv install ddg-mcp
# Using pip
pip install ddg-mcp从源安装
克隆存储库:
git clone https://github.com/misanthropic-ai/ddg-mcp.git
cd ddg-mcp安装软件包:
# Using uv
uv install -e .
# Using pip
pip install -e .配置
必需的依赖项
服务器需要duckduckgo-search包,当您安装ddg-mcp时它将自动安装。
如果需要手动安装:
uv install duckduckgo-search
# or
pip install duckduckgo-searchDuckDuckGo 搜索参数
通用参数
这些参数适用于大多数搜索类型:
region :本地化结果的区域代码(默认值:“wt-wt”)
例如:“us-en”(美式英语)、“uk-en”(英式英语)、“ru-ru”(俄语)
查看DuckDuckGo 区域以了解更多选项
safesearch :内容过滤级别(默认值:“中等”)
"on": 严格过滤
“moderate”:中等过滤
“off”:不过滤
timelimit :结果的时间范围
“d”:最后一天
“w”:上周
“m”:上个月
“y”:去年(不适用于新闻/视频)
max_results :返回的最大结果数(默认值:10)
搜索运算符
您可以在搜索关键字中使用这些运算符:
cats 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.comintitle:dogs:页面标题包含单词“dogs”inurl:cats:页面 URL 包含单词“cats”
图像搜索特定参数
尺寸:“小”、“中”、“大”、“壁纸”
颜色:“颜色”、“单色”、“红色”、“橙色”、“黄色”、“绿色”、“蓝色”、“紫色”、“粉色”、“棕色”、“黑色”、“灰色”、“青色”、“白色”
type_image :“照片”、“剪贴画”、“gif”、“透明”、“线条”
布局:“方形”、“高”、“宽”
license_image :“任何”、“公开”、“共享”、“商业共享”、“修改”、“商业修改”
视频搜索特定参数
分辨率:“高”,“标准”
持续时间:“短”、“中”、“长”
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 的小型模型
快速入门
安装
克劳德桌面
在 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人工智能聊天
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"克劳德配置
"ddg-mcp": { "command": "uv", "args": [ "--directory", "/PATH/TO/YOUR/INSTALLATION/ddg-mcp", "run", "ddg-mcp" ] },
发展
构建和发布
准备分发包:
同步依赖项并更新锁文件:
uv sync构建软件包分发版:
uv build这将在dist/目录中创建源和轮子分布。
发布到 PyPI:
uv publish注意:您需要通过环境变量或命令标志设置 PyPI 凭据:
令牌:
--token或UV_PUBLISH_TOKEN或用户名/密码:
--username/UV_PUBLISH_USERNAME和--password/UV_PUBLISH_PASSWORD
使用 GitHub Actions 自动发布
此仓库包含一个 GitHub Actions 工作流,用于自动发布到 PyPI。以下情况会触发该工作流:
创建了一个新的 GitHub 版本
该工作流程通过 GitHub Actions 界面手动触发
要设置自动发布:
生成 PyPI API 令牌:
创建一个范围仅限于
ddg-mcp项目的新令牌复制令牌值(您只会看到一次)
将令牌添加到您的 GitHub 存储库机密中:
前往 GitHub 上的存储库
导航至“设置”>“机密和变量”>“操作”
点击“新建存储库秘密”
名称:
PYPI_API_TOKEN值:粘贴您的 PyPI 令牌
点击“添加秘密”
要发布新版本:
更新
pyproject.toml中的版本号在 GitHub 上创建新版本或手动触发工作流程
调试
由于 MCP 服务器通过 stdio 运行,调试起来可能比较困难。为了获得最佳调试体验,我们强烈建议使用MCP Inspector 。
您可以使用以下命令通过npm启动 MCP Inspector:
npx @modelcontextprotocol/inspector uv --directory /path/to/your/ddg-mcp run ddg-mcp启动后,检查器将显示一个 URL,您可以在浏览器中访问该 URL 以开始调试。
Available Tools
5 toolsddg-ai-chatC
Chat with DuckDuckGo AI
| Name | Required | Description | Default |
|---|---|---|---|
| keywords | Yes | Message or question to send to the AI | |
| model | No | AI model to use | gpt-4o-mini |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers almost none. 'Chat with DuckDuckGo AI' doesn't reveal whether this is a read-only operation, if it requires authentication, what rate limits apply, whether conversations are persistent, or what the typical response format looks like. For a chat tool with zero annotation coverage, this is a significant gap in behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just four words, with zero wasted language. It's front-loaded with the core functionality ('Chat with DuckDuckGo AI') and every word earns its place. This is a model of efficiency in tool description writing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a chat tool with no annotations, no output schema, and 2 parameters, the description is insufficiently complete. It doesn't explain what kind of responses to expect, whether there are conversation contexts, what the AI's capabilities or limitations are, or any behavioral characteristics. For a tool that presumably involves AI interaction, more context about the nature of the chat would be expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so both parameters are well-documented in the schema itself. The description adds no additional parameter information beyond what's already in the schema (keywords for the message, model selection from specific AI models). This meets the baseline expectation when the schema does the heavy lifting, but doesn't provide extra context about parameter usage or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Chat with DuckDuckGo AI' clearly states the verb ('Chat') and resource ('DuckDuckGo AI'), making the purpose immediately understandable. It distinguishes this tool from its siblings (image-search, news-search, text-search, video-search) by specifying it's for AI chat rather than search operations. However, it doesn't specify what kind of chat (e.g., conversational, Q&A) or the scope of the AI's capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus its sibling tools. It doesn't mention that this is for AI-powered conversations rather than traditional search operations, nor does it suggest alternatives like using text-search for factual queries. There's no context about appropriate use cases or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ddg-image-searchC
Search the web for images using DuckDuckGo
| Name | Required | Description | Default |
|---|---|---|---|
| keywords | Yes | Search query keywords | |
| region | No | Region code (e.g., wt-wt, us-en, uk-en) | wt-wt |
| safesearch | No | Safe search level | moderate |
| timelimit | No | Time limit (d=day, w=week, m=month, y=year) | |
| size | No | Image size | |
| color | No | Image color | |
| type_image | No | Image type | |
| layout | No | Image layout | |
| license_image | No | Image license type | |
| max_results | No | Maximum number of results to return |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Search') but doesn't describe what the tool returns (e.g., image URLs, metadata, pagination), potential rate limits, authentication needs, or error conditions. For a search tool with 10 parameters and no annotations, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded with the core action and resource, making it easy to parse. Every part of the sentence earns its place by specifying the service and resource type.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, no annotations, no output schema), the description is insufficient. It doesn't explain return values, behavioral traits like rate limits or errors, or usage context relative to siblings. For a search tool with rich parameters but no structured output or annotations, more descriptive context is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 10 parameters thoroughly with descriptions and enums. The description adds no additional parameter information beyond what the schema provides. According to guidelines, when coverage is high (>80%), the baseline score is 3 even with no param info in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search') and resource ('the web for images') with the specific service ('using DuckDuckGo'), making the purpose immediately understandable. It distinguishes from siblings by specifying 'images' versus text, news, video, or AI chat searches. However, it doesn't explicitly contrast with sibling tools beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention sibling tools or suggest scenarios where image search is preferable over text, news, video, or AI chat searches. Usage is implied by the resource type but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ddg-news-searchC
Search for news articles using DuckDuckGo
| Name | Required | Description | Default |
|---|---|---|---|
| keywords | Yes | Search query keywords | |
| region | No | Region code (e.g., wt-wt, us-en, uk-en) | wt-wt |
| safesearch | No | Safe search level | moderate |
| timelimit | No | Time limit (d=day, w=week, m=month) | |
| max_results | No | Maximum number of results to return |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool searches for news articles but doesn't cover critical aspects like whether it's read-only (implied but not explicit), rate limits, authentication needs, pagination, or error handling. For a search tool with external dependencies, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence—and front-loaded with the core purpose. There's no wasted language or redundancy, making it efficient for quick understanding. Every word earns its place by directly stating the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no annotations, no output schema), the description is incomplete. It doesn't address behavioral traits, usage context, or output format, leaving gaps that could hinder effective tool invocation. For a search tool with multiple parameters and no structured output documentation, more detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-specific information beyond what the input schema provides. Since schema description coverage is 100%, the baseline score is 3. The description doesn't explain parameter interactions, default behaviors, or practical examples, so it doesn't enhance the schema's documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for news articles using DuckDuckGo'. It specifies the verb ('Search') and resource ('news articles'), and distinguishes it from sibling tools like ddg-image-search and ddg-video-search by focusing on news. However, it doesn't explicitly differentiate from ddg-text-search, which might also return news results, keeping it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like ddg-text-search or ddg-ai-chat, nor does it specify scenarios where news search is preferred over general text search or other media types. This lack of comparative context leaves the agent without clear usage directives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ddg-text-searchC
Search the web for text results using DuckDuckGo
| Name | Required | Description | Default |
|---|---|---|---|
| keywords | Yes | Search query keywords | |
| region | No | Region code (e.g., wt-wt, us-en, uk-en) | wt-wt |
| safesearch | No | Safe search level | moderate |
| timelimit | No | Time limit (d=day, w=week, m=month, y=year) | |
| max_results | No | Maximum number of results to return |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool performs a web search but doesn't mention any behavioral traits such as rate limits, authentication needs, response format, or potential side effects. For a search tool with no annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a web search with 5 parameters) and the lack of both annotations and an output schema, the description is insufficient. It doesn't explain what the tool returns, how results are structured, or any behavioral aspects, leaving critical gaps for the agent to understand the tool fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-specific information beyond what the input schema provides. Since schema description coverage is 100%, the baseline score is 3. The description doesn't elaborate on parameter usage, constraints, or examples, so it doesn't add value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search the web for text results') and the resource ('using DuckDuckGo'), which is specific and unambiguous. However, it doesn't explicitly distinguish this tool from its siblings like ddg-image-search or ddg-news-search, though the 'text results' wording implies a distinction from those other search types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus its siblings (ddg-ai-chat, ddg-image-search, ddg-news-search, ddg-video-search). It doesn't mention any prerequisites, alternatives, or exclusions, leaving the agent to infer usage based on the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ddg-video-searchC
Search for videos using DuckDuckGo
| Name | Required | Description | Default |
|---|---|---|---|
| keywords | Yes | Search query keywords | |
| region | No | Region code (e.g., wt-wt, us-en, uk-en) | wt-wt |
| safesearch | No | Safe search level | moderate |
| timelimit | No | Time limit (d=day, w=week, m=month) | |
| resolution | No | Video resolution | |
| duration | No | Video duration | |
| license_videos | No | Video license type | |
| max_results | No | Maximum number of results to return |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but only states the basic action ('Search for videos'). It doesn't mention whether this is a read-only operation, potential rate limits, authentication needs, or what the output format looks like (e.g., list of video metadata). For a search tool with 8 parameters, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste: 'Search for videos using DuckDuckGo'. It's front-loaded with the core purpose and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (8 parameters, no output schema, no annotations), the description is incomplete. It lacks behavioral context (e.g., read-only nature, result format), usage guidance relative to siblings, and any mention of output structure, making it inadequate for full agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with all parameters well-documented in the input schema (e.g., 'keywords' as search query, 'region' with examples, enums for filters). The description adds no additional parameter information beyond what's already in the schema, so it meets the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'Search for videos using DuckDuckGo', which includes a specific verb ('Search') and resource ('videos') with the search engine specified. However, it doesn't explicitly differentiate from sibling tools like ddg-image-search or ddg-text-search beyond the 'videos' keyword, which is why it doesn't reach a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like ddg-image-search or ddg-text-search. There's no mention of specific use cases, prerequisites, or exclusions, leaving the agent with minimal context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
- First observed
ddg-ai-chat - First observed
ddg-image-search - First observed
ddg-news-search - First observed
ddg-text-search - First observed
ddg-video-search
TDQS
Scored across 5 tools
Every tool has a clearly distinct purpose based on media type: chat, images, news, text, and videos. There is no overlap in functionality, making it easy for an agent to select the appropriate tool for each search need.
All tools follow a consistent 'ddg-[media_type]-search' pattern, with the exception of 'ddg-ai-chat' which still fits the 'ddg-[function]' convention. This uniformity makes the tool set predictable and easy to understand.
Five tools is well-scoped for a DuckDuckGo search server, covering key search types (text, image, video, news) plus an AI chat feature. Each tool earns its place without being overwhelming or insufficient.
The tool set covers major search categories effectively, but there is a minor gap in specialized searches like maps or shopping, which are common in search engines. However, core workflows are well-supported, and agents can work around this limitation.
Maintenance
Related MCP Connectors
MCP server for Firecrawl — web search, scraping, and biomedical/arXiv paper search.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Related MCP Servers
- AlicenseAqualityAmaintenanceA Model Context Protocol (MCP) server that provides web search capabilities through DuckDuckGo, with additional features for content fetching and parsing.315,517 PyPI1,510MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server that provides DuckDuckGo search functionality for Claude, enabling web search capabilities through a clean tool interface with rate limiting support.11,589 npm87MIT
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables AI applications like Claude Desktop and Cursor IDE to perform web searches via DuckDuckGo's search engine.-
- AlicenseAqualityDmaintenanceA Model Context Protocol server that exposes DuckDuckGo web and image search to MCP clients.2ISC