DuckDuckGo 검색 MCP 서버

👁 PyPI version
👁 PyPI downloads
👁 Python versions

DuckDuckGo를 통한 웹 검색 기능과 콘텐츠 가져오기 및 파싱을 위한 추가 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다.

빠른 시작

uvx duckduckgo-mcp-server

Related MCP server: Duck Duck MCP

기능

• 웹 검색: 고급 속도 제한 및 결과 서식 지정 기능을 갖춘 DuckDuckGo 검색

• 콘텐츠 가져오기: 지능형 텍스트 추출을 통한 웹페이지 콘텐츠 검색 및 파싱

• 속도 제한: 검색 및 콘텐츠 가져오기 모두에 대한 속도 제한 방지 기능 내장

• 오류 처리: 포괄적인 오류 처리 및 로깅

• LLM 친화적 출력: 대규모 언어 모델이 사용하기에 최적화된 결과 서식

설치

uv를 사용하여 PyPI에서 설치합니다:

uv pip install duckduckgo-mcp-server

사용법

Claude Desktop에서 실행

1. Claude Desktop을 다운로드합니다.

2. Claude Desktop 설정을 생성하거나 편집합니다:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

다음 설정을 추가합니다:

기본 설정 (SafeSearch 없음, 기본 지역 없음):

{
 "mcpServers": {
 "ddg-search": {
 "command": "uvx",
 "args": ["duckduckgo-mcp-server"]
 }
 }
}

SafeSearch 및 지역 설정 포함:

{
 "mcpServers": {
 "ddg-search": {
 "command": "uvx",
 "args": ["duckduckgo-mcp-server"],
 "env": {
 "DDG_SAFE_SEARCH": "STRICT",
 "DDG_REGION": "cn-zh"
 }
 }
 }
}

설정 옵션:

• DDG_SAFE_SEARCH: SafeSearch 필터링 수준 (선택 사항)

  • STRICT: 최대 콘텐츠 필터링 (kp=1)

  • MODERATE: 균형 잡힌 필터링 (kp=-1, 지정하지 않을 경우 기본값)

  • OFF: 콘텐츠 필터링 없음 (kp=-2)

• DDG_REGION: 기본 지역/언어 코드 (선택 사항, 아래 예시 참조)

  • us-en: 미국 (영어)

  • cn-zh: 중국 (중국어)

  • jp-ja: 일본 (일본어)

  • wt-wt: 특정 지역 없음

  • DuckDuckGo의 기본 동작을 사용하려면 비워 두세요.

3. Claude Desktop을 재시작합니다.

Claude Code에서 실행

1. Claude Code를 다운로드합니다.

2. uvenv가 설치되어 있고 uvx 명령을 사용할 수 있는지 확인합니다.

3. MCP 서버를 추가합니다: claude mcp add ddg-search uvx duckduckgo-mcp-server

SSE 또는 Streamable HTTP로 실행

이 서버는 다른 MCP 클라이언트와 함께 사용할 수 있도록 대체 전송 방식을 지원합니다:

# SSE transport
uvx duckduckgo-mcp-server --transport sse

# Streamable HTTP transport
uvx duckduckgo-mcp-server --transport streamable-http

기본 전송 방식은 stdio이며, Claude Desktop 및 Claude Code에서 사용됩니다.

sse 또는 streamable-http로 실행할 때는 --host 및 --port 플래그를 사용하여 기본 바인딩 주소(127.0.0.1:8000)를 재정의하세요:

uvx duckduckgo-mcp-server --transport streamable-http --host 0.0.0.0 --port 7070

Fetch 백엔드 (봇 탐지 우회)

일부 사이트는 User-Agent와 관계없이 고유한 TLS 지문 때문에 기본 httpx 클라이언트를 차단합니다. Cloudflare 봇 관리 및 유사한 필터는 헤더가 아닌 JA3/TLS 핸드셰이크를 기준으로 판단합니다. 선택적 백엔드인 curl(curl_cffi를 통해 구현됨)은 실제 Chrome 브라우저의 TLS 핸드셰이크를 모방하여 이러한 검사를 통과합니다.

설치:

# Default install (httpx only)
uv pip install duckduckgo-mcp-server

# With the optional browser backend
uv pip install "duckduckgo-mcp-server[browser]"

백엔드 옵션:

백엔드 설정 방법 두 가지:

1. --fetch-backend CLI 플래그를 통한 서버 전체 기본값 설정 (모든 fetch_content 호출에 적용):

   # Default behavior — uses httpx
   uvx duckduckgo-mcp-server
   
   # Force curl for every fetch (requires the [browser] extra)
   uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend curl
   
   # Try httpx first, fall back to curl on 403 / Cloudflare challenge
   uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --fetch-backend auto

2. fetch_content 도구의 backend 인수를 통한 호출별 재정의 (해당 단일 호출에 대해 CLI 기본값 재정의). 도구의 입력 스키마에 backend가 노출되므로 MCP 클라이언트는 가져오기마다 "httpx", "curl", 또는 "auto"를 선택할 수 있습니다.

search 도구는 항상 httpx를 사용합니다. DuckDuckGo의 검색 엔드포인트는 모방이 필요하지 않습니다.

모방이 필요 없는 사용자가 추가 종속성에 대한 비용을 지불하지 않도록 기본값은 httpx로 유지됩니다.

개발

로컬 개발을 위한 방법:

# Install dependencies
uv sync

# Run with the MCP Inspector
mcp dev src/duckduckgo_mcp_server/server.py

# Install locally for testing with Claude Desktop
mcp install src/duckduckgo_mcp_server/server.py

# Run all tests
uv run python -m pytest src/duckduckgo_mcp_server/ -v

# Run only unit tests
uv run python -m pytest src/duckduckgo_mcp_server/test_server.py -v

# Run only e2e tests
uv run python -m pytest src/duckduckgo_mcp_server/test_e2e.py -v

사용 가능한 도구

1. 검색 도구

async def search(query: str, max_results: int = 10, region: str = "") -> str

DuckDuckGo에서 웹 검색을 수행하고 서식이 지정된 결과를 반환합니다.

매개변수:

• query: 검색 쿼리 문자열

• max_results: 반환할 최대 결과 수 (기본값: 10)

• region: (선택 사항) 기본값을 재정의할 지역/언어 코드. 기본 지역을 사용하려면 비워 두세요.

지역 코드 예시:

• us-en: 미국 (영어)

• cn-zh: 중국 (중국어)

• jp-ja: 일본 (일본어)

• de-de: 독일 (독일어)

• fr-fr: 프랑스 (프랑스어)

• wt-wt: 특정 지역 없음

반환값: 제목, URL, 스니펫이 포함된 검색 결과가 서식 지정된 문자열.

사용 예시:

• 기본 설정으로 검색: search("python tutorial")

• 특정 지역으로 검색: 일본 뉴스 검색 시 search("latest news", region="jp-ja")

2. 콘텐츠 가져오기 도구

async def fetch_content(
 url: str,
 start_index: int = 0,
 max_length: int = 8000,
 backend: Optional[str] = None,
) -> str

웹페이지에서 콘텐츠를 가져와 파싱합니다.

매개변수:

• url: 콘텐츠를 가져올 웹페이지 URL

• start_index: 읽기를 시작할 문자 오프셋 (페이지 매김용)

• max_length: 반환할 최대 문자 수

• backend: 기본 fetch 백엔드에 대한 선택적 호출별 재정의 ("httpx", "curl", 또는 "auto"). 생략 시 서버 시작 시 --fetch-backend를 통해 설정된 값을 사용합니다.

반환값: 웹페이지에서 정리되고 서식이 지정된 텍스트 콘텐츠.

상세 기능

속도 제한

• 검색: 분당 30회 요청으로 제한

• 콘텐츠 가져오기: 분당 20회 요청으로 제한

• 자동 대기열 관리 및 대기 시간

결과 처리

• 광고 및 관련 없는 콘텐츠 제거

• DuckDuckGo 리디렉션 URL 정리

• LLM 소비에 최적화된 결과 서식 지정

• 긴 콘텐츠를 적절하게 자름

콘텐츠 안전

• SafeSearch 필터링: DDG_SAFE_SEARCH 환경 변수를 통해 서버 시작 시 설정

  • 관리자가 제어하며 AI 어시스턴트가 수정할 수 없음

  • 선택한 수준에 따라 부적절한 콘텐츠 필터링

  • DuckDuckGo의 공식 kp 매개변수 사용

• 지역 현지화:

  • DDG_REGION 환경 변수를 통해 기본 지역 설정

  • AI 어시스턴트가 검색 요청별로 재정의 가능

  • 특정 지리적 지역에 대한 결과 관련성 향상

오류 처리

• 포괄적인 오류 포착 및 보고

• MCP 컨텍스트를 통한 상세 로깅

• 속도 제한 또는 시간 초과 시 정상적인 성능 저하(Graceful degradation)

기여

이슈 및 풀 리퀘스트를 환영합니다! 개선 가능한 영역:

• 향상된 콘텐츠 파싱 옵션

• 자주 액세스하는 콘텐츠를 위한 캐싱 계층

• 추가적인 속도 제한 전략

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• fetch_contentA
• searchA