DuckDuckGo MCP Server

一个托管的 Model Context Protocol (MCP) 服务器，为 Claude、Cursor、Windsurf 以及任何其他 MCP 客户端提供结构化 JSON 形式的 DuckDuckGo 搜索结果。带排名的自然结果、独立数组中的广告、DuckDuckGo 自己的 AI 答案，以及 37 个可定向的地区。为高并发和解析而构建，无需本地浏览器，也无需配置回退链。

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

目录

• 你需要什么

• 快速开始

• 示例提示词

• 工具

• 错误与失败路径

• 定价、免费档位与限制

• 工具选择

• 对比

• 常见问题

• HasData 链接

• 开发

• 贡献

• 许可证

Related MCP server: duckduckgo-mcp

你需要什么

一个支持 streamable HTTP 和自定义请求头的 MCP 客户端。一个来自仪表盘的 HasData API 密钥，可免费创建。仅此而已。这是一个远程服务器，所以最简单的路径就是 URL 加请求头，无需添加浏览器包，也无需维持本地进程。仅支持 stdio 的客户端可以改用 @hasdata/duckduckgo-mcp (npm) 或 hasdata-duckduckgo-mcp (PyPI) 启动器。

快速开始

服务器 URL 对所有客户端都一样。我们在 Claude Code 和 Claude Desktop 中实际运行过。其余代码块遵循各客户端自己文档中规定的远程服务器格式。

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

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

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

对于配置文件方式，Claude Desktop 只加载本地（stdio）服务器，因此它需要通过一个 stdio 启动器来访问远程服务器。@hasdata/duckduckgo-mcp 包就是这个启动器，它会从环境中读取密钥。将其添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "duckduckgo": {
      "command": "npx",
      "args": ["-y", "@hasdata/duckduckgo-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

用的是 Python 而不是 Node？把启动器换成 PyPI 包，uvx 无需手动安装即可运行：

{
  "mcpServers": {
    "duckduckgo": {
      "command": "uvx",
      "args": ["hasdata-duckduckgo-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

每个项目使用 ~/.cursor/mcp.json，或单个项目使用 .cursor/mcp.json：

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

~/.codeium/windsurf/mcp_config.json。Windsurf 将这个字段称为 serverUrl，而不是 url：

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

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

工作区中的 .vscode/mcp.json：

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

~/.codex/config.toml：

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

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

~/.gemini/settings.json：

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

示例提示词

这些是提示词，不是代码。粘贴一条进去，代理就会自己调用工具。每条都标注了它所消耗的调用次数，因为在 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 积分。

工具

只有一个工具。下面的示例截取自真实调用，其中的结果会随着网络内容的变化而变化。请把它们当作结构形态来看。

这些示例是载荷，而不是完整响应。一次 tools/call 结果携带一个文本块，该文本本身是 JSON，包含 url、status、text 和 json，抓取的数据位于 json 下。对于原始 JSON-RPC 响应，路径是 result.content[0].text，解析后再取 .json。聊天客户端会为你解包，而直接与端点通信的代码则不会。

获取 DuckDuckGo 搜索结果

hasdata_duckduckgo_serp_getSearchResults

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

请发送 q 或 nextPageToken 其中之一。两者都不发送会返回 422，并列出这两个字段，因为该要求是条件性的，schema 无法把它表达成一个普通的必填列表。两者都发送也不算错误，此时游标生效，查询不会执行，因此如果代理在翻页时仍把 q 留在参数中，就会在静默中读取错误的结果集。

position 是在结果所在的页面内计数的，而不是在整个结果集中计数。第二页返回时，position 又从 1 开始；页面大小也不是固定的，所以 10、15、14 条结果的页面都可能出现。因此，绝对排名等于你已经收集到的自然结果数量加上 position，而不是你能从页码推导出的任何值。如果构建排名数据集时不考虑这一点，那么每一页都会贡献出自己的“第 1 名”。

返回 organicResults、ads、searchAssist 和 pagination。自然结果条目带有 position、title、link、displayedLink、source 和 snippet，以及 DuckDuckGo 展示的日期、站点链接和视频元数据。searchAssist 包含 DuckDuckGo 针对该查询给出的 AI 答案。

当页面既没有广告也没有 AI 答案时，ads 和 searchAssist 就不存在，因此读取前要先检查键是否存在。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，并把失败信息放进结果中，isError 设为 true，原因以文本形式给出。在你可能预期看到状态行的地方，代理读到的是一条消息。

错误的密钥会以工具输出的形式暴露出来，而不是连接失败。 工具列表接口接受任何非空密钥，因此客户端会完成握手并显示绿色。第一次工具调用随后会返回 isError: true 以及文本 HasData API error: 401 Unauthorized。请留意这个字符串，因为流程中更早的阶段不会报告这个问题。

缺少密钥是唯一一个真正的 HTTP 错误。 授权在任何工具之前执行，连接本身会以 401 失败。

破坏 schema 的参数会在变成搜索之前就被拒绝。 服务器会返回 isError: true 和文本 MCP error -32602: Input validation error，并指明字段名。不会抓取任何内容，也不会产生任何费用。

q 和 nextPageToken 都不提供 时会返回 422，带有一个 errors 数组，列出这两个字段以及将它们关联起来的 requiredIfNotExists 规则。

背后没有任何真实内容的查询仍然会返回结果。 相关性由 DuckDuckGo 决定，因此一个无意义的字符串会以普通的一页十条松散相关条目返回，ads 和 searchAssist 不存在。没有任何标记表示这是未命中，如果你正在构建针对“该品牌没有覆盖”的告警，这一点很重要。

携带数据的结果还会带有 requestMetadata.id，在联系支持时值得引用。

定价、免费档位与限制

每次调用消耗 10 积分。结果数量不会改变价格。一整页和只有一条结果的页面花费相同。

免费试用是 30 天内 1,000 积分，无需绑卡，也就是 100 次搜索。此后，活跃账户只要余额低于 100，每天都会继续获得 100 积分补充，因此低用量的代理可以无限期地运行在免费档位上。

付费套餐起价为 每月 49 美元，含 200,000 积分，即 20,000 次搜索。单价随用量增加而下降，从入门套餐的 每 1,000 次搜索 2.45 美元，到 Business 套餐的 0.99 美元、Growth 套餐的 0.83 美元，以及最大高用量套餐的 0.75 美元。最新数字见定价页面。

你的套餐还决定了并发数。免费试用允许同时 1 个请求，Startup 为 15，Business 为 30，Growth 为 50，高用量套餐则为 200 到 1,500。在任何无人值守的程序中，都要防御性地处理超出上限的情况，因为一个并行分发的 agent 会比你更早触顶。

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

工具选择

apis 查询参数决定你的 agent 能看到哪些工具。工具越少，花在工具定义上的上下文越少，模型选错工具的机会也越少。

?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 这样的 provider 名称，也接受类似 google_maps_search 这样的单个 API 名称。拼写错误的名称会被忽略。如果所有名称都错误，请求将以 400 失败，响应体会列出它无法识别的名称以及所有有效值。省略该参数后，同一个端点会暴露全部 57 个 HasData 工具。

在一个 agent 中集成三个引擎，是扩大这里列表的常见原因；因为一旦这三个引擎都暴露出来，对同一查询在 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 能让你的 agent 同时获得三个搜索引擎。

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

可以，在支持 OAuth 的客户端中可以。Claude Desktop 和 Cursor 可以将该端点添加为连接器并登录。无人值守的 agents 和脚本使用 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.