DuckDuckGo MCP Server

호스팅되는 Model Context Protocol (MCP) 서버로, Claude, Cursor, Windsurf 및 기타 모든 MCP 클라이언트에 DuckDuckGo 검색 결과를 구조화된 JSON으로 제공합니다. 순위가 매겨진 유기적 결과와 위치, 자체 배열의 광고, DuckDuckGo의 자체 AI 답변, 그리고 타겟팅 가능한 37개 지역을 포함합니다. 대량 처리와 파싱을 위해 설계되었으며, 로컬 브라우저나 구성할 폴백 체인이 없습니다.

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

목차

• 필요한 것

• 빠른 시작

• 예시 프롬프트

• 도구

• 오류 및 실패 경로

• 가격, 무료 티어 및 한도

• 도구 선택

• 비교

• FAQ

• 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"

설정(Settings), 커넥터(Connectors), 사용자 지정 커넥터 추가(Add custom connector)로 이동한 다음 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을 쓴다면? 런처를 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는 필드 이름을 url이 아니라 serverUrl로 사용합니다:

{
  "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개 결과를 순위와 도메인과 함께 알려줘.

1회 호출, 10크레딧.

"vpn review" 쿼리를 독일 지역에서 실행하고 같은 쿼리를 미국 지역에서도 실행한 다음, 한쪽에만 나타나는 도메인이 무엇인지 알려줘.

2회 호출, 20크레딧. 지역은 매개변수입니다. 같은 쿼리를 두 시장에서 실행하면 두 번의 호출이 필요합니다.

"best crm software"를 검색하고 유료 배치만 나열하되, 각 항목의 광고주 도메인을 함께 표시해 줘.

1회 호출, 10크레딧. 광고는 자체 배열로 제공되므로 필터링 휴리스틱이 필요 없습니다.

"model context protocol" 쿼리로 처음 세 페이지를 탐색한 다음, 두 개 이상의 순위를 가진 도메인이 무엇인지 알려줘.

3회 호출, 30크레딧. 첫 페이지 이후 각 페이지는 커서를 사용한 새로운 호출이며, 커서를 확보한 뒤에는 인자에서 q를 제거하세요.

"who invented the transistor"를 검색하고 DuckDuckGo의 자체 AI 답변을 참조한 유기적 결과 옆에 표시해 줘.

1회 호출, 10크레딧.

그중 두 가지가 이 서버가 존재하는 이유입니다. 지역 타기팅은 37개 시장에 걸친 일급 매개변수입니다. 한 쿼리를 여러 국가에서 비교하는 것은 프록시 설정이 아니라 반복 호출입니다. 그리고 유료 배치는 유기적 결과와 분리되어 반환되므로, 순위 추적이 어떤 결과가 광고인지 추측하는 데 의존하지 않습니다.

페이지를 넘길 때마다 호출이 한 번씩 듭니다. 열 페이지를 탐색하는 프롬프트는 열 번의 호출, 즉 100크레딧입니다.

도구

도구는 하나입니다. 아래 샘플은 실제 호출에서 발췌한 것이며, 그 안의 결과는 웹이 변함에 따라 달라집니다. 형태를 참고하세요.

샘플은 전체 응답이 아니라 페이로드입니다. tools/call 결과에는 텍스트 블록 하나가 담기며, 그 텍스트 자체가 url, status, text, json을 포함하는 JSON이고, 스크래핑된 데이터는 json 아래에 있습니다. 원시 JSON-RPC 응답에서는 result.content[0].text를 파싱한 뒤 .json으로 접근합니다. 채팅 클라이언트는 이를 자동으로 풀어 주지만, 엔드포인트에 직접 말을 거는 코드는 그렇지 않습니다.

DuckDuckGo 검색 결과 가져오기

hasdata_duckduckgo_serp_getSearchResults

DuckDuckGo 결과 페이지를 가져와 파싱된 형태로 반환합니다.

q 또는 nextPageToken 중 하나를 보내세요. 둘 다 보내지 않으면 두 필드를 모두 명시하는 422가 반환됩니다. 요구 사항이 조건부이고 스키마가 이를 단순 필수 목록으로 표현할 수 없기 때문입니다. 둘 다 보내는 것도 오류는 아닙니다. 커서가 우선하고 쿼리는 실행되지 않으므로, 페이지를 넘기면서 인자에 q를 계속 유지하는 에이전트는 조용히 잘못된 결과 집합을 읽게 됩니다.

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로 실패합니다.

스키마를 위반하는 인자는 검색이 되기 전에 거부됩니다. 서버는 isError: true와 MCP error -32602: Input validation error 텍스트로 응답하며 필드를 명시합니다. 아무것도 가져오지 않고 요금도 부과되지 않습니다.

q도 nextPageToken도 없는 경우 두 필드와 두 필드를 연결하는 requiredIfNotExists 규칙을 명시한 errors 배열과 함께 422를 반환합니다.

뒤에 아무것도 없는 쿼리도 결과를 반환합니다. DuckDuckGo가 관련성을 결정하므로, 의미 없는 문자열도 ads와 searchAssist가 없는 느슨하게 관련된 10개 항목의 일반적인 페이지로 돌아옵니다. 실패로 표시되는 것이 없습니다. 이는 "이 브랜드에 대한 커버리지 없음"에 대한 알림을 만들 때 중요합니다.

데이터를 담은 결과에는 지원 티켓에 인용할 만한 requestMetadata.id도 함께 포함됩니다.

가격, 무료 티어 및 한도

모든 호출에는 10크레딧이 듭니다. 결과 수는 가격을 바꾸지 않습니다. 한 페이지가 가득 차든 항목이 하나뿐이든 같은 비용입니다.

무료 평가판은 카드 없이 30일 동안 1,000크레딧으로, 100회 검색에 해당합니다. 그 이후에는 활성 계정의 잔액이 100 미만으로 떨어질 때마다 매일 100크레딧이 충전되므로, 소량 사용 에이전트는 무료 티어에서 무기한 실행됩니다.

유료 플랜은 월 200,000크레딧(20,000회 검색) 기준 월 $49부터 시작합니다. 단가는 볼륨에 따라 낮아져서, 엔트리 플랜의 1,000회 검색당 $2.45부터 비즈니스 $0.99, 그로스 $0.83, 최대 대용량 플랜의 $0.75까지입니다. 현재 수치는 가격 페이지에 있습니다.

플랜은 동시성도 결정합니다. 무료 평가판은 한 번에 1개 요청, Startup은 15개, Business는 30개, Growth는 50개, 대용량 플랜은 200~1,500개입니다. 무인으로 실행되는 무엇이든 오버플로 상황을 방어적으로 처리하세요. 에이전트가 요청을 여러 갈래로 펼치면 당신이 직접 도달하기 전에 한도에 도달하게 되니까요.

200이 아닌 상태로 돌아온 요청은 청구되지 않습니다. 아무것도 찾지 못한 성공 호출도 여전히 호출로 간주됩니다.

Tool selection

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 같은 제공업체 이름과 google_maps_search 같은 개별 API 이름을 받습니다. 철자가 틀린 이름은 무시됩니다. 모든 이름이 틀리면 요청은 400으로 실패하며, 본문에는 인식하지 못한 값과 모든 유효한 값이 함께 나열됩니다. 이 매개변수를 생략하면 동일한 엔드포인트가 HasData의 모든 57개 도구를 노출합니다.

여기서 목록을 넓히는 일반적인 이유는 하나의 에이전트에서 세 엔진을 쓰기 위해서입니다. DuckDuckGo, Google, Bing이 모두 노출되면 같은 쿼리를 세 엔진에서 비교하는 것이 단일 프롬프트로 가능해지기 때문입니다.

How it compares

현실적인 대안은 자체 호스팅 서버입니다. 널리 쓰이는 방식은 로컬에서 실행하는 Python 패키지로, 자신의 머신에서 DuckDuckGo에 접근하고 모델에 포맷된 텍스트 블록을 전달합니다. 이는 한 번에 한 질문에 답하는 연구 어시스턴트에는 잘 맞습니다. 하지만 볼륨과 안정적인 형태가 필요해지면 한계가 드러납니다.

결정에 가장 큰 영향을 주는 행은 두 개입니다. 텍스트 블롭은 채팅 답변에는 올바른 출력이지만 순위 데이터셋에는 잘못된 출력입니다. 문장에서 position을 재구성하는 것은 당신이 하지 말아야 할 작업이기 때문입니다. 그리고 페이지를 가져오는 것이 저희 측이라는 것은 백엔드 문제가 사라진다는 뜻입니다. httpx와 브라우저를 흉내 내는 클라이언트 사이의 선택, 폴백이 의존하는 추가 항목 설치, 일반 HTTP 클라이언트가 더 이상 페이지를 받아오지 못할 때 스택 트레이스를 읽는 일까지 함께 사라집니다.

목록의 나머지 항목은 모두 실제 트레이드오프입니다. 자체 호스팅 서버는 무료이고, 계정이 필요 없으며, 쿼리를 자신의 머신에 보관하고, 이 서버가 하지 않는 페이지 콘텐츠 가져오기를 지원합니다. 하루에 소수의 검색만 하나의 어시스턴트 안에서 실행한다면 자체 호스팅이 더 적합합니다. 이 서버는 검색 수, 지역 수, 또는 출력 형태가 중요해지기 시작할 때를 위한 것입니다.

DuckDuckGo 자체 API와 비교. api.duckduckgo.com은 Instant Answer API로, 결과 페이지 대신 백과사전 요약이 있을 때 그 요약을 반환합니다. 순위가 매겨진 웹 결과를 제공하는 공식 엔드포인트는 없으며, 그래서 여기의 모든 옵션이 페이지를 파싱하는 것입니다.

이 서버가 하지 않는 것. 페이지 가져오기나 콘텐츠 추출, 이미지·뉴스 버티컬, 자동 완성은 없습니다. 결과 페이지를 파싱한 상태로 반환합니다.

FAQ

공식 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 links

Development

이 저장소는 원격 서버를 위한 설정과 문서입니다. 빌드 단계도, 컨테이너화할 것도 없습니다.

test/의 테스트는 도구 계약을 검증합니다. 이 저장소에 커밋이 없어도 깨질 수 있는 부분입니다. ?apis=duckduckgo가 정확히 하나의 도구를 반환하는지, 그 이름이 바뀌지 않았는지, 이 README가 문서화한 매개변수가 인용한 enum과 함께 여전히 존재하는지, 그리고 사용 중인 키가 실제로 승인되는지 확인합니다. 마지막 검사는 실제 검색을 실행하며 10크레딧이 듭니다. 이는 올바른 이유로 실패할 수 있는 카나리의 비용입니다.

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

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

동일한 테스트 묶음은 모든 push 시 CI에서 실행되고, 예약된 작업으로 일주일에 한 번 실행됩니다. 누구도 이 저장소를 건드리지 않아도 업스트림 도구 목록이 바뀔 수 있기 때문입니다. 실패는 도구 목록이 이동했거나, 키가 작동을 멈췄거나, 엔드포인트에 연결할 수 없음을 의미하며, assertion 메시지가 그 원인을 알려줍니다.

Contributing

매개변수 표와 응답 샘플에 대한 수정이 가장 유용한 기여입니다. 그 부분들이 가장 잘 어긋나기 때문입니다. 수행한 호출과 받은 응답을 포함해 주세요. 포크에서 온 Pull Request는 키 없이 테스트 묶음을 실행하며, 실시간 검사는 빨간불이 아니라 건너뛰게 됩니다.

License

MIT. LICENSE를 참조하세요.