HasData DuckDuckGo

DuckDuckGo MCP Server

一个托管的 Model Context Protocol (MCP) 服务，可为 Claude、Cursor、Windsurf 和其他 MCP 客户端提供结构化 JSON 格式的 DuckDuckGo 搜索结果。包含按排名排序并带有位置的自然搜索结果、单独数组中的广告、DuckDuckGo 自带的 AI 答案，以及 37 个可定位的地区。专为高频使用和解析而打造，无需本地浏览器，也无需配置备用链。

每月提供 1,000 个免费额度，无需信用卡，可用于 100 次搜索。

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

• 提示词和资源

目录

• 准备工作
• 快速开始
• 提示词示例
• 工具
• 错误和失败路径
• 定价、免费套餐和限制
• 工具选择
• 横向比较
• 常见问题
• HasData 链接
• 开发
• 贡献
• 许可证

准备工作

一个支持可流式传输 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/mcp?apis=duckduckgo" \
  --header "x-api-key: HASDATA_API_KEY"

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

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

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

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

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

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

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

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

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

提示词示例

这些是提示词，不是代码。粘贴一条提示词，Agent 就会自行调用工具。每条提示词都标注了所需调用次数，因为在 MCP 中，模型会决定调用次数，每次成功调用都会消耗 10 个积分。

在 DuckDuckGo 中搜索“model context protocol”，并列出排名前十的结果及其排名和域名。

一次调用，10 个积分。

在德国地区搜索“vpn review”，再在美国地区搜索一次，然后告诉我哪些域名只出现在其中一个地区。

两次调用，20 个积分。地区是一个参数。同一查询在两个市场中执行，需要两次调用。

搜索“best crm software”，只列出付费广告位，并注明每个广告主的域名。

一次调用，10 个积分。广告会单独返回在自己的数组中，无需使用启发式方法进行筛选。

搜索“model context protocol”，浏览前三页，然后告诉我哪些域名占据了多个排名位置。

三次调用，30 个积分。第一页之后的每一页都需要使用游标发起一次新调用；拿到游标后，就从参数中移除 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，并指出这两个字段，因为该要求是有条件的，架构无法将其表示为普通的必填字段列表。两者都发送也不会报错：游标会优先使用，查询词则不起作用。因此，翻页时仍在参数中保留 q 的 Agent 会在不知情的情况下读取错误的结果集。

position 是在其所属页面内计数，而不是在整个结果集中计数。第二页返回的位置会重新从 1 开始，而且每页的大小也不固定，因此可能会出现包含 10、15 和 14 条结果的页面。因此，绝对排名应为已收集的自然搜索结果数量加上 position，而不能从页码推算。若构建排名数据集时不遵循这一点，每一页都会有自己的第一名。

返回 organicResults、ads、searchAssist 和 pagination。自然搜索结果条目包含 position、title、link、displayedLink、source 和 snippet，以及 DuckDuckGo 显示时提供的日期、站点链接和视频元数据。searchAssist 包含 DuckDuckGo 针对该查询生成的 AI 答案。

如果页面没有广告或 Search Assist 答案，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…" }
}

提示词和资源

服务公开了 5 个资源，每个资源对应一个取值范围为固定列表的参数。读取资源比从被拒绝的调用中摸索取值更省力，而且不消耗额度。每个 URI 的格式为 hasdata://duckduckgo/<parameter>。

此列表无需 API 密钥即可获取，因此客户端可以在用户注册之前读取它。

错误和失败路径

客户端几乎不会在工具调用中收到 HTTP 错误代码。MCP 层会返回 200，并将失败信息放在结果中，同时将 isError 设为 true，并以文本说明原因。Agent 读取到的是一条消息，而不是预期中的状态行。

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

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

不符合架构的参数会在发起搜索之前被拒绝。 服务会返回 isError: true，文本为 MCP error -32602: Input validation error，并指出字段名称。不会获取任何内容，也不会扣费。

既没有 q，也没有 nextPageToken 时，会返回 422，其中包含一个 errors 数组，列出这两个字段以及将它们关联起来的 requiredIfNotExists 规则。

即使查询毫无内容，也仍会返回结果。 相关性由 DuckDuckGo 决定，因此毫无意义的字符串也会像普通查询一样返回一页 10 条不太相关的条目，并且不包含 ads 和 searchAssist。没有任何标记表明查询未命中；如果你正在构建用于提醒“未覆盖此品牌”的告警，这一点很重要。

返回数据的结果也会包含 requestMetadata.id，可在联系支持时引用。

定价、免费套餐和限制

每次调用消耗 10 个额度。结果数量不会改变价格。完整的一页和只有一条结果的一页价格相同。

免费套餐每月提供 1,000 个额度，无需信用卡，相当于 100 次搜索。额度会随计费周期续订，因此低频使用的 Agent 可以一直使用免费套餐。

付费套餐起价为 每月 $59，可获得 200,000 个额度，相当于 20,000 次搜索。用量越大，单价越低：入门套餐为 每 1,000 次搜索 $2.95，Basic 套餐为 $1.19，Growth 套餐系列为 $0.83。当前价格请查看定价页面。

套餐也会决定并发数。免费套餐允许同时处理 1 个请求，Startup 为 5 个，Basic 为 15 个，Growth 套餐系列则从 50 个到 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 这样的提供商名称，也接受 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 没有提供返回排名网页结果的官方端点，因此这里的每种方案都会解析页面。

此服务不提供的功能。 不获取页面或提取内容，不提供图片或新闻垂直搜索，也不提供自动补全。它会解析并返回搜索结果页。

常见问题

有官方的 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 登录，而不是粘贴密钥吗？

可以，前提是客户端支持。Claude Desktop 和 Cursor 可以将此端点添加为连接器并登录。无人值守的 Agent 和脚本则使用 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。