DuckDuckGo MCP Server

一个托管的 Model Context Protocol（MCP）服务器，可向 Claude、Cursor、Windsurf 以及任何其他 MCP 客户端提供结构化的 DuckDuckGo 搜索 JSON 结果。按位置排名的自然搜索结果、独立数组中的广告、DuckDuckGo 自有的 AI 回答，以及 37 个可定制的区域。面向高并发和易解析设计，无本地浏览器，也无需配置回退链。

https://mcp.hasdata.com/api/mcp?apis=duckduckgo

目录

• 你需要什么

• 快速开始

• 示例提示

• 工具

• 错误与失败路径

• 定价、免费额度和限制

• 工具选择

• 如何做选择

• 常见问题

• HasData 链接

• 开发

• 参与贡献

• 许可证

Related MCP server: duckduckgo-mcp

你需要什么

支持流式 HTTP 和自定义请求头的一个 MCP 客户端。从 dashboard 获取一个 HasData API 密钥，免费创建。多亏。这是远程服务器，无需管理 Python 环境、无需添加浏览器依赖，也没有需要保持存活的本地进程。

快速开始

服务器 URL 对所有客户端都是相同的。以下配置已在 Claude Code、Claude Desktop、Cursor、Windsurf 和 Cline 上测试通过。

支持 OAuth 的客户端可以把同一 URL 添加为连接器，并直接登录，而无需在配置文件中放置密钥。

claude mcp add --transport http duckduckgo "https://mcp.hasdata.com/api/mcp?apis=duckduckgo" \
  --header "x-api-key: your_key_here"

设置，然后连接器，然后添加自定义连接器，粘贴 https://mcp.hasdata.com/api/mcp?apis=duckduckgo，再登录。

要通过配置文件，则需把下面的内容加入 claude_desktop_config.json：

{
  "mcpServers": {
    "duckduckgo": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

~/.cursor/mcp.json 用于所有项目，或者 .cursor/mcp.json 用于单个项目：

{
  "mcpServers": {
    "duckduckgo": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

~/.codeix/windsurf/mcp_config.json。Windsurf 把字段叫成 serverUrl，而不是 url：

{
  "mcpServers": {
    "duckduckgo": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

{
  "mcpServers": {
    "duckduckgo": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=duckduckgo",
      "type": "streamableHttp",
      "headers": { "x-api-key": "your_key_here" },
      "disabled": false
    }
  }
}

在 workspace 里的 .vscode/mcp.json：

{
  "servers": {
    "duckduckgo": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

~/.codex/config.toml：

[mcp_servers.duckduckgo]
url = "https://mcp.hasdata.com/api/mcp?apis=duckduckgo"

[mcp_servers.duckduckgo.headers]
"x-api-key" = "your_key_here"

~/.gemini/settings.json：

{
  "mcpServers": {
    "duckduckgo": {
      "httpUrl": "https://mcp.hasdata.com/api/mcp?apis=duckduckgo",
      "headers": { "x-api-key": "your_key_here" }
    }
  }
}

示例提示

是提示，不是代码。粘贴一个，代理就会自己调用工具。每个提示都标注了它会产生的调用次数，因为在 MCP 中，模型会决定发起多少次调用，而每次成功调用都会消耗 10 个积分。

搜索 DuckDuckGo 上的 "model context protocol"，并给我前十条结果，同时附上它们的位置和域名。

一次调用，10 个积分。

在德国区域运行查询 "vpn review"，再在美国区域运行一次，然后告诉我哪些域名只出现在其中一个结果中。

两次调用，20 个积分。区域是参数。同一个查询在两个市场就是两次调用。

搜索 "best crm software"，只列出付费广告位，并给出每个广告的广告域。

一次调用，10 个积分。广告放在自己的数组里，不需要任何过滤过滤规则。

以查询 "model context protocol" 为例，翻前三页，然后告诉我哪些域名获得了多个位置。

三次调用，每次调用 30 个积分。第一页之后，后面的页都需要用 cursor 发起新的调用，拿到 cursor 后就要把 q 从参数中丢下。

搜索 "who invented the transistor"，并把 DuckDuckGo 自己的 AI 回答与它引用的自然结果并列展示。

一次调用，10 个积分。

上述有一些提示示例正是本服务器的用途。区域定位是 37 个市场中的头等参数。同一查询跨国家比较，是循环调用，而不是代理配置。付费广告和自然生态分开返回，因此不会因为猜测搜索引擎结果哪一部分属于广告而影响排名跟踪。

分页每次调用都会花费一次次数。一个要翻十页的提示，就是十次调用、100 个积分。

工具

只有一个工具。下面的示例来自真实调用，并做了缩略，结果会随网页内容变化而变化。只需把它们视为数据结构即可。

示例文本就是响应里的 payload，不是整个 response。一个 tools/call 结果携带一个 text block，该 text 本身是 JSON，包含 url、status、text 和 json，被解析的数据在 json 下。用原始 JSON-RPC 响应来看，路径是 result.content[0].text 解析后再加上 .json。聊天客户端会帮你打开，直接连接端点的代码则不会。

获取 DuckDuckGo 搜索请求

hasdata_duckduckgo_serp_getSearchResults

获取 DuckDuckGo 结果页，并返回解析后的内容。

请发送 q 或 nextPageToken。两者都不发会返回 422，并列出这两个字段，因为该要求是条件式的，无法用统一的 required 列表表达。两个都发也返回不是错误，cursor 会胜出，而查询被丢弃，所以如果分页时仍把 q 留在参数中，会静默读到错误的结果集。

position 只在所在页面内计数，不对整个结果集计数。第二页返回的 position 会重新从 1 开始，而且页面大小也不固定，因此 10 条、15 条和 14 条结果的页面都可能出现。所以绝对排名是此前累计的自然结果数加上当前 position，而不能从页码推导。如果你没按这种方式建排名数据集，每一页都会产生一个新的第一名。

返回 organicResults、ads、searchAssist 和 pagination。自然结果条目包含 position、title、link、displayedLink、source 和 snippet，另外在 DuckDuckGo 展示的地方还会有日期、站点链接和视频数据。searchAssist 里放的是 DuckDuckGo 对当前查询的 AI 回答。

当页面两者都无时，ads 和 searchAssist 会缺失，所以读取前要先检查 key 是否存在。organicResults 也可能缺失，读取时应给一个默认值，而不能默认它一定有结果。一个没有真正匹配的查询仍会返回一个完整页面，里面可能是一些松散相关的结果，这并不像常规的 “未找到” 情况。

{
  "organicResults": [
    {
      "position": 1,
      "title": "What is the Model Context Protocol (MCP)?",
      "link": "https://modelcontextprotocol.io/docs/getting-started/intro",
      "displayedLink": "modelcontextprotocol.io › docs › getting-started › intro",
      "source": "modelcontextprotocol.io",
      "snippet": "MCP is an open-source standard for connecting AI applications to external systems."
    }
  ],
  "ads": [
    { "position": 1, "title": "Make Agents Accountable", "link": "https://www.gravitee.io/platform/ai-agent-management" }
  ],
  "searchAssist": {
    "answer": "Model Context Protocol (MCP) is an open standard from Anthropic that lets LLMs connect to external tools, systems, and data sources using a shared interface."
  },
  "pagination": { "nextPageToken": "eyJ1cmwiOiJodHRwczovL2xpbmtzLmR1Y2tkdWNrZ28uY29t…" }
}

错误与失败路径

你的客户端几乎永远看不到来自工具调用的 HTTP 错误码。MCP 层返回 200，把失败放在 result 里，同时 isError 设为 true，并把原因写成文本。对代理而言，它读到的一个消息，而不是一状态行状态行。

错误地使用 Key 会表现为工具输出失败，而不是连接失败。 因为列出工具时会接受任何非空 key，所以客户端会完成握手并显示“绿色”。第一次工具调用才会返回 isError: true 和文本 HasData API error: 401 Unauthorized。这类字符串要盯住看，因为前面的流程里没有任何提示。

缺少 key 才是唯一的真实 HTTP 错误。 在任何工具执行前都要做认证，因此连接本身会以 401 失败。

参数不合 schema. 会被拒绝，不会变成搜索。 服务器会返回 isError: true 和文本 MCP error -32602: Input validation error，并指出对应字段。不会产生抓取，也不会产生计费。

既不传 q 也不传 nextPageToken，会返回 422，返回的 errors 数组会指出这两个字段，以及把二者关联在一起的 requiredIfNotExists 规则。

词背后没有任何内容，也仍然会有结果返回。 DuckDuckGo 决定相关性，因此一个无意义的查询也会变成一页 10 条偶尔相关的结果，并且不包含 ads 和 searchAssist。没有任何标记能把它标记为 miss，这对想用“这个品牌没有覆盖”来书写告警的场景很重要。

当结果包含数据时，还会带一个 requestMetadata.id，值得在支持 ticket 中引用。

定价、免费额度和限制

每次调用都消耗 10 个积分。结果数量不改计费，一整页和只有一条结果的一页价格相同。

免费试用是 1000 积分，有效期 30 天，无需信用卡，也就是 100 次搜索。之后，活跃账号只要余额低于 100，每天自动获得 100 个积分补充，因此低用量代理可以在免费额度下无限期运行。

付费计划从 $49/月 起，包含 200,000 积分，也就是 20,000 次搜索。单价随用量像下降一样变化：从入门计划的 每 1000 次搜索 $2.45，到 Business 的 $0.99，Growth 的 $0.83，以及最大高用量计划的 $0.75。当前价格在价格页上可以看到。

你的计划也决定了并发数。免费试用允许 1 个并发请求，Startup 15 个，Business 30 个，Growth 50 个高容量计划从 200 到 1500。任何无人值守的流程都要防御性处理超过并发上限的情况，因为代理如果 fan-out，会比你先撞到上限。

返回非 200 的请求不计费。成功但什么都没找到的调用，也仍然是一次调用。

工具选择

apis 查询参数决定你的代理会看到哪些工具。工具越少，定义工具上下文消耗越少，模型也没有更多机会去抓错误的工具。

?apis=duckduckgo                        the one tool in this repo
?apis=duckduckgo,google_serp            add Google search
?apis=duckduckgo,bing_serp,google_serp  three engines side by side

该参数接受提供方名称（如 duckduckgo）和单个 API 名称（如 google_maps_search）。拼写错误的名称会被忽略。如果所有名称都错误，请求将以 400 失败，响应体会列出无法识别的名称以及所有有效值。省略该参数后，同一端点会暴露全部 57 个 HasData 工具。

在一个代理中集成三个搜索引擎是扩大此处列表的常见原因，因为一旦同时暴露 DuckDuckGo、Google 和 Bing，比较同一查询只需一次提示。

对比

现实中的替代方案是自托管服务器。常见的是在本地运行的 Python 包，它们从你自己的机器访问 DuckDuckGo，并将格式化文本块交给模型。这对于一次回答一个问题的研究助手来说效果很好。当你需要处理量和稳定的输出结构时，它就不适用了。

两行承载了大部分决策。文本块是聊天答案的正确输出，但对于排名数据集则是错误的输出，因为从文本中重建 position 是你本不该做的工作。而抓取由我们负责，意味着后端问题消失了，也无需在 httpx 和模拟浏览器的客户端之间做选择，无需安装回退所依赖的附加组件，也无需在普通 HTTP 客户端无法获取页面时阅读堆栈跟踪。

列表上的其他一切都是真正的权衡。自托管服务器免费，无需账户，将你的查询保留在自己的机器上，并抓取页面内容，而本服务器不提供这些。如果你在一个助手中每天只运行少量搜索，它更合适。本服务器适用于搜索次数、地区数量或输出结构开始变得重要的场景。

对比 DuckDuckGo 自有 API。 api.duckduckgo.com 是 Instant Answer API，当存在百科摘要时，它返回的是摘要而不是结果页。没有官方端点会提供排好序的网页结果，这就是为什么这里的每个选项都解析页面。

本服务器不做什么。 不抓取页面或提取内容，没有图片或新闻垂直搜索，没有自动补全。它返回解析后的结果页。

常见问题

有官方的 DuckDuckGo MCP 服务器吗？

没有。DuckDuckGo 没有发布 MCP 服务器。每个选项都由其他人构建。大多数是在本地运行的开源项目，而这是一个由 HasData 维护的托管服务器。

什么是 DuckDuckGo MCP 服务器？

一个将 DuckDuckGo 搜索暴露为 AI 客户端可调用工具的服务器。客户端通过 Model Context Protocol 发送工具调用，服务器执行搜索并返回结构化 JSON，模型处理结果，永远不会看到 HTML 页面。

我需要 DuckDuckGo 账户或 API 密钥吗？

不需要。唯一的凭证是你的 HasData 密钥。DuckDuckGo 没有可注册的开发者计划，它发布的 Instant Answer API 也不返回搜索结果。

我需要托管或运行什么吗？

不需要。这是一个基于 streamable HTTP 的远程 MCP 服务器。无需安装任何东西，无需 Python 环境，无需浏览器包，无需重启进程。

数据是实时的还是缓存的？

实时的。每次调用在请求时抓取结果页，并带有自己的 requestMetadata.id。两个相同的调用是两次独立的抓取，而不是重放存储的副本。

我可以跨地区比较同一查询吗？

可以，这正是使用参数而不是代理的主要原因。kl 接受 37 个地区代码，cc 与 setLang 可以在你需要将国家和语言分开时分别设置。每个地区都是独立的调用。

当 DuckDuckGo 改变其布局时会发生什么？

你这边什么都不会发生。我们跟踪这些变化并保持响应模式稳定，因此字段名称和类型保持不变。没有可报告内容的块会从响应中省略，因此请为 ads 和 searchAssist 设置默认值。

我可以将它与其它 HasData API 一起使用吗？

可以。apis 参数接受一个列表，?apis=duckduckgo,google_serp,bing_serp 可以让你的代理同时使用三个搜索引擎。

我可以使用 OAuth 登录而不是粘贴密钥吗？

可以，在支持它的客户端中可以。Claude Desktop 和 Cursor 可以将端点添加为连接器并登录。无人值守的代理和脚本使用 x-api-key 请求头。

合规性与个人数据

HasData 仅访问公开可用的数据。平台的条款可能限制自动访问，你需要自行负责合规。如果你收集的数据包含个人信息，请确保你根据 GDPR、CCPA 或你所在司法辖区的等效规则拥有合法的处理依据。

HasData 链接

开发

此仓库是远程服务器的配置和文档。没有构建步骤，也没有需要容器化的内容。

test/ 中的测试断言工具契约，即这里无需提交也可能被破坏的部分。它们检查 ?apis=duckduckgo 是否恰好返回一个工具，其名称是否未改变，此 README 记录的参数是否仍然存在并带有其引用的枚举，以及正在使用的密钥是否确实被接受。最后一项检查会执行一次真实搜索并花费 10 个积分，这是一个可以因正确原因而失败的金丝雀测试的代价。

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

同一套测试在每次推送时于 CI 中运行，并每周定时运行一次，因为上游工具列表可能在没有人在此仓库中做任何改动的情况下发生变化。失败意味着工具列表发生了变动、密钥停止工作或端点无法访问，断言消息会说明是哪一种。

贡献

对参数表和响应示例的修正是最有用的贡献，因为这些部分容易发生偏差。请附上你发出的调用和收到的响应。来自 fork 的拉取请求会在没有密钥的情况下运行测试套件，实时检查会跳过而不是变红。

许可证

MIT。参见 LICENSE。