DuckDuckGo Search

Realizar pesquisas na web usando a API do DuckDuckGo, com recursos para buscar e analisar conteúdo.

Documentação

Servidor MCP de Pesquisa DuckDuckGo

Um servidor Model Context Protocol (MCP) que fornece recursos de pesquisa na web por meio do DuckDuckGo, com recursos adicionais para busca e análise de conteúdo.

Início Rápido

uvx duckduckgo-mcp-server

Recursos

Pesquisa na Web: Pesquise no DuckDuckGo com limite de taxa avançado e formatação de resultados
Busca de Conteúdo: Recupere e analise conteúdo de páginas da web com extração inteligente de texto
Limite de Taxa: Proteção integrada contra limites de taxa para pesquisa e busca de conteúdo
Tratamento de Erros: Tratamento e registro abrangente de erros
Saída Amigável para LLM: Resultados formatados especificamente para consumo por grandes modelos de linguagem

Instalação

Instale a partir do PyPI usando uv:

uv pip install duckduckgo-mcp-server

Uso

Executando com Claude Desktop

Baixe o Claude Desktop
Crie ou edite sua configuração do Claude Desktop:
- No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- No Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione a seguinte configuração:

Configuração Básica (Sem SafeSearch, Sem Região Padrão):

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

Com Configuração de SafeSearch e Região:

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

Opções de Configuração:

DDG_SAFE_SEARCH: Nível de filtragem do SafeSearch (opcional)
- STRICT: Filtragem máxima de conteúdo (kp=1)
- MODERATE: Filtragem equilibrada (kp=-1, padrão se não especificado)
- OFF: Sem filtragem de conteúdo (kp=-2)
DDG_REGION: Código de região/idioma padrão (opcional, exemplos abaixo)
- us-en: Estados Unidos (Inglês)
- cn-zh: China (Chinês)
- jp-ja: Japão (Japonês)
- wt-wt: Sem região específica
- Deixe vazio para o comportamento padrão do DuckDuckGo
DDG_CA_CERTS: Caminho para um pacote de certificados PEM usado para verificar certificados TLS em solicitações de saída (opcional). Necessário atrás de proxies com interceptação TLS — consulte Executando atrás de um proxy com interceptação TLS.

Reinicie o Claude Desktop

Executando com Claude Code

Baixe o Claude Code
Certifique-se de que uvenv esteja instalado e o comando uvx esteja disponível
Adicione o servidor MCP: claude mcp add ddg-search uvx duckduckgo-mcp-server

Executando com SSE ou Streamable HTTP

O servidor suporta transportes alternativos para uso com outros clientes MCP:

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

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

O transporte padrão é stdio, usado pelo Claude Desktop e Claude Code.

Ao executar com sse ou streamable-http, substitua o endereço de vinculação padrão (127.0.0.1:8000) pelas flags --host e --port:

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

Executando atrás de um proxy reverso ou em Docker

O FastMCP habilita proteção contra rebinding de DNS para os transportes HTTP e, por padrão, só aceita cabeçalhos Host/Origin para localhost. Atrás de um proxy reverso ou em um contêiner, o cabeçalho Host do cliente não corresponderá, então as solicitações falharão com 421 Misdirected Request.

Corrija isso permitindo os hosts e origens que os clientes realmente usam (preferível a desabilitar a proteção). Os valores suportam host, host:port e porta curinga host:*:

uvx duckduckgo-mcp-server --transport streamable-http --host 0.0.0.0 --port 7070 \
  --allowed-hosts ddg-mcp.example.com "ddg-mcp.example.com:*" \
  --allowed-origins "https://ddg-mcp.example.com"

Variáveis de ambiente equivalentes (separadas por vírgula) também estão disponíveis: DDG_ALLOWED_HOSTS, DDG_ALLOWED_ORIGINS.

Como último recurso, você pode desativar completamente a verificação com --disable-dns-rebinding-protection (ou DDG_DISABLE_DNS_REBINDING_PROTECTION=1). Prefira uma lista de permissões — desabilitar a proteção remove uma defesa contra ataques de rebinding de DNS. Quando nada está configurado, o padrão seguro somente-localhost é preservado.

Executando atrás de um proxy com interceptação TLS

Proxies corporativos que reassinam tráfego HTTPS com sua própria CA (via HTTPS_PROXY) fazem com que solicitações de saída falhem com erros de verificação de certificado, porque os clientes HTTP não confiam na CA autoassinada do proxy (e o httpx não lê mais a variável de ambiente SSL_CERT_FILE). Aponte o servidor para o pacote de certificados da CA do seu proxy:

uvx duckduckgo-mcp-server --ca-certs /path/to/proxy-ca.pem

Ou defina DDG_CA_CERTS=/path/to/proxy-ca.pem. O pacote é usado tanto pelas ferramentas search quanto fetch_content, nos backends httpx e curl igualmente.

Como último recurso, --no-ssl-verify (ou DDG_SSL_VERIFY=0) desativa completamente a verificação de certificados. Isso expõe o tráfego à interceptação por qualquer pessoa no caminho da rede — prefira --ca-certs.

Backends (contornando detecção de bots)

Alguns sites — e, recentemente, o próprio endpoint de pesquisa do DuckDuckGo (html.duckduckgo.com) — bloqueiam o cliente padrão httpx por causa de sua impressão digital TLS distinta, independentemente do User-Agent. O Cloudflare Bot Management e filtros semelhantes se baseiam no handshake JA3/TLS, não em cabeçalhos, então html.duckduckgo.com pode responder httpx com uma página HTTP 202 vazia (resultando silenciosamente em "sem resultados"). Um backend opcional, curl (implementado via curl_cffi), imita o handshake TLS de um navegador Chrome real e passa por essas verificações.

Tanto a ferramenta search quanto a ferramenta fetch_content suportam esses backends.

Instalação:

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

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

Opções de backend:

Valor	Comportamento	Precisa de `[browser]`
`httpx`	HTTP assíncrono leve. Padrão. Funciona na maioria dos sites.	não
`curl`	Usa `curl_cffi` com impersonação TLS do Chrome 131. Passa por filtros baseados em impressão digital TLS.	sim
`auto`	Tenta `httpx` primeiro; em 403 ou resposta de desafio Cloudflare, tenta novamente com `curl`.	sim

Duas maneiras de configurar o backend:

Padrão do servidor via flag CLI --fetch-backend (aplica-se a cada chamada 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

Substituição por chamada via argumento backend na ferramenta fetch_content (substitui o padrão da CLI para aquela chamada específica). A ferramenta expõe backend em seu esquema de entrada, então um cliente MCP pode escolher "httpx", "curl" ou "auto" em uma busca por busca.

Para fetch_content, o padrão permanece httpx para que usuários que não precisam da impersonação não paguem pela dependência extra.

Backend de pesquisa

Como o endpoint de pesquisa do DuckDuckGo agora bloqueia por impressão digital o httpx simples, a ferramenta search usa por padrão auto: ela tenta httpx primeiro e recorre a curl quando detecta um bloqueio (HTTP 202/403). O fallback só funciona se o extra [browser] estiver instalado; caso contrário, a pesquisa retorna uma mensagem informando para instalá-lo.

Configure o backend de pesquisa com a flag CLI --search-backend ou a variável de ambiente DDG_SEARCH_BACKEND (auto (padrão) / httpx / curl):

# Recommended: install the browser extra so the auto fallback can impersonate Chrome
uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server

# Force curl for every search
uvx --with "duckduckgo-mcp-server[browser]" duckduckgo-mcp-server --search-backend curl

# Opt out of the fallback (legacy behavior — may return no results while blocked)
uvx duckduckgo-mcp-server --search-backend httpx

Desenvolvimento

Para desenvolvimento local:

# 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

Ferramentas Disponíveis

1. Ferramenta de Pesquisa

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

Realiza uma pesquisa na web no DuckDuckGo e retorna resultados formatados.

Parâmetros:

query: String de consulta de pesquisa
max_results: Número máximo de resultados a retornar (padrão: 10)
region: (Opcional) Código de região/idioma para substituir o padrão. Deixe vazio para usar a região padrão configurada.

Exemplos de Códigos de Região:

us-en: Estados Unidos (Inglês)
cn-zh: China (Chinês)
jp-ja: Japão (Japonês)
de-de: Alemanha (Alemão)
fr-fr: França (Francês)
wt-wt: Sem região específica

Retorna: String formatada contendo resultados de pesquisa com títulos, URLs e trechos.

Exemplo de Uso:

Pesquisar com configurações padrão: search("python tutorial")
Pesquisar com região específica: search("latest news", region="jp-ja") para notícias em japonês

2. Ferramenta de Busca de Conteúdo

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

Busca e analisa conteúdo de uma página da web.

Parâmetros:

url: A URL da página da web para buscar conteúdo
start_index: Deslocamento de caracteres para começar a ler (para paginação)
max_length: Número máximo de caracteres a retornar
backend: Substituição opcional por chamada do backend de busca padrão ("httpx", "curl" ou "auto"). Quando omitido, usa o que foi definido via --fetch-backend na inicialização do servidor.

Retorna: Conteúdo de texto limpo e formatado da página da web.

Proteção SSRF: Por padrão, fetch_content recusa URLs que resolvem para loopback, privado (RFC1918), link-local (incluindo o endpoint de metadados da nuvem 169.254.169.254), reservado, multicast ou endereços não especificados, e revalida cada salto de redirecionamento. Apenas URLs http/https são permitidas. Para implantações locais confiáveis que precisam buscar hosts internos, desative a proteção com DDG_ALLOW_PRIVATE_URLS=1 ou --allow-private-urls. Consulte SECURITY.md para detalhes.

Recursos em Detalhe

Limite de Taxa

Pesquisa: Limitada a 30 solicitações por minuto
Busca de Conteúdo: Limitada a 20 solicitações por minuto
Gerenciamento automático de fila e tempos de espera

Processamento de Resultados

Remove anúncios e conteúdo irrelevante
Limpa URLs de redirecionamento do DuckDuckGo
Formata resultados para consumo ideal por LLM
Trunca conteúdo longo adequadamente

Segurança de Conteúdo

Filtragem SafeSearch: Configurada na inicialização do servidor via variável de ambiente DDG_SAFE_SEARCH
- Controlada por administradores, não modificável por assistentes de IA
- Filtra conteúdo inadequado com base no nível selecionado
- Usa o parâmetro oficial kp do DuckDuckGo
Localização de Região:
- Região padrão definida via variável de ambiente DDG_REGION
- Pode ser substituída por solicitação de pesquisa por assistentes de IA
- Melhora a relevância dos resultados para regiões geográficas específicas

Tratamento de Erros

Captura e relato abrangente de erros
Registro detalhado por meio do contexto MCP
Degradação graciosa em limites de taxa ou tempos limite

Contribuindo

Issues e pull requests são bem-vindos! Algumas áreas para melhoria potencial:

Opções aprimoradas de análise de conteúdo
Camada de cache para conteúdo acessado com frequência
Estratégias adicionais de limite de taxa

Licença

Este projeto é licenciado sob a Licença MIT.