Hound Web MCP

Os servidores MCP Hound fornecem ao seu agente um fetch + busca realmente bons por 0$, sem pegadinhas, sem chaves de API ou tiers gratuitos, totalmente grátis.

Documentação

Hound logo

🐕 Hound

Dê à sua IA o poder da web. $0. Dois comandos. Sem chaves.

Fetch · crawl · contorne bloqueios de bots · leia PDFs (até escaneados) · pesquise na web Um servidor MCP · um navegador aquecido · zero contas · roda na sua máquina

PyPI Python License: MIT CI Downloads GitHub stars

pip install hound-mcp[all] && playwright install chromium

Instalar · As 6 ferramentas · Busca · Comparação · Armadilhas · Limites honestos


Hound gives your AI agent the web

🎬 Demonstração

Mesmo prompt, três ferramentas. O Hound faz tudo sozinho — busca + fetch + crawl, localmente. Os outros travam nas partes que não sabem fazer.

OpenCode + Hound

Pi + Hound


✨ Novidades na 12.1.2

Busca BYOK · fan-out multi-consulta com detecção de intenção · ranqueamento de seis sinais · motor stealth de nova geração.

  • 🔑 Busca Bring Your Own Key (BYOK): adicione suas próprias chaves de API para Serper, Tavily, Exa, Firecrawl ou TinyFish via hound keys add. As chaves se tornam a fonte primária de busca com empilhamento de chaves (várias chaves por provedor, rotação automática em caso de rate limit), com fallback automático para os motores locais sem chave do Hound quando todas as chaves se esgotarem. Gerenciamento de chaves via CLI: hound keys add/list/test/remove/clear.
  • 🧠 Fan-out multi-consulta com detecção de intenção: o Hound detecta a intenção da consulta (comparação, tutorial, pesquisa, código, referência, notícias, factual) e gera variantes expandidas da consulta distribuídas entre motores diversos. Mesma quantidade de requisições paralelas, zero latência adicional, maior cobertura. Consenso entre variantes: uma URL encontrada por consultas diferentes em motores diferentes é um sinal de autoridade mais forte.
  • 📊 Ranqueamento de seis sinais: consenso entre variantes + reputação de domínio + pontuação de sinal de resposta + relevância do título + relevância da URL + diversidade de resultados (máx. 2 por domínio nos primeiros resultados). A detecção de tipo de fonte etiqueta cada resultado como docs/paper/repo/blog/forum/referência/notícias.
  • 🧬 Motor stealth de nova geração: detecção automática do Chrome do sistema, 4 perfis de fingerprint coerentes, patches na camada JS (correção de UA do HeadlessChrome, navigator.webdriver=undefined, ruído no canvas, API de permissões), simulação de comportamento humano (curvas de mouse de Bézier, rolagem natural), resolvedor de CF Turnstile com movimento de mouse humanizado. Passa no bot.sannysoft.com, contorna o Cloudflare Turnstile no CanadianInsider (o mais difícil em um benchmark de 31 sites), Medium, StackOverflow, NowSecure, Glassdoor (DataDome). Veja o benchmark de stealth abaixo.
  • 🐍 Sem mais scrapling. Toda a funcionalidade do scrapling foi substituída por módulos próprios do hound: fetcher.py (HTTP baseado em primp), browser.py (navegador baseado em patchright), extractor.py (trafilatura + markdownify). Instalação menor, menos dependências transitivas, cold start mais rápido.
  • 📱 Funciona em qualquer lugar. A instalação enxuta pip install hound-mcp não puxa dependências de navegador. Em plataformas sem playwright (Termux, aarch64), o hound roda em modo somente HTTP com degradação graciosa.
  • 🔒 Correções de confiabilidade: detecção universal de erros (páginas de erro não parecem mais sucesso), fallback morto do Internet Archive removido, CLI com autocorreção + limpeza de processos obsoletos, erros de seletor CSS propagam em vez de retornar silenciosamente [], falha de inicialização do navegador limpa sessões parciais, hound --rollback funciona para versões antigas fixadas, focus e actions agora são encaminhados do dispatcher MCP para smart_fetch.
  • 🐳 Suporte a Docker: Dockerfile multi-estágio, docker-compose com shm_size 1gb, usuário não-root, healthcheck. Por @imonlinux.
  • 🧪 673 testes.

Por que você deve escolher o Hound

O Hound é um servidor MCP que dá a qualquer agente (Claude Code, Cursor, OpenCode, Hermes, Pi, qualquer coisa que fale MCP) pesquisa web completa a partir de um único processo local.

  • 🆓 $0 para sempre, MIT: sem chaves, sem contas, sem cobrança por requisição, sem dados roteados para um scraper de terceiros. A busca é sem chave e local.
  • 🧠 Dominado na conexão: um bloco instructions único entrega ao agente o modelo mental, o fluxo de trabalho nº 1 e os limites conhecidos. Eficaz desde o primeiro turno.
  • 📐 ~2,9K tokens, 6 ferramentas: definições de ferramentas feitas à mão, sem inchaço de schema Pydantic. Mais capacidade do que ferramentas que entregam 5K+.
  • 🎯 Toda resposta é acionável: content_ok, next_action, summary, page_type, content_age_days/is_stale, source_type/is_official, relevance_score, fetch_relevance. Os agentes ramificam com base em campos estruturados, não em texto de erro. Bloqueios rígidos (404/bot/auth) retornam erros limpos, não conteúdo falso.
  • 🛡️ Inicialização e desligamento seguros para produção: cold start abaixo de 1s para o handshake MCP nunca expirar; sai com código 0 e stderr limpo, sem ruído de encerramento que pareça crash.

O Hound é para o próprio agente. Você instala uma vez; o agente o chama sempre que precisar da web.


🚀 Início rápido

pip install hound-mcp[all]          # fetch + crawl + keyless search + PDF + OCR + neural rerank
playwright install chromium         # the anti-detect browser engine

Depois aponte qualquer cliente MCP para o comando hound. Sem argumentos, sem chaves, sem variáveis de ambiente. Veja Instalar para a opção enxuta e Diga ao seu agente para instalar para um prompt de copiar e colar.

hound -v          # version + update status
hound -u          # update to latest (brick-proof, self-healing)
hound --doctor    # health check + fix advice
hound --rollback  # undo the last update

Se o hound quebrar (uma atualização falha, um launcher travado), recupere com python ~/.hound/repair.py, ou execute hound --doctor para diagnosticar.


🐳 Docker

O Hound pode rodar em Docker com modo HTTP, ideal para:

  • Rodar em um servidor
  • Implantação isolada

Início rápido com Docker Compose

git clone https://github.com/dondai1234/master-fetch.git
cd master-fetch
docker-compose up -d

O Hound estará disponível em http://<your-host-ip>:8765/mcp como um servidor MCP HTTP (use localhost se estiver rodando na mesma máquina).

Build manual do Docker

docker build -t hound-mcp .
docker run -p 8765:8765 hound-mcp

Variáveis de ambiente

VariávelPadrãoDescrição
HOUND_BROWSER_IDLE_TIMEOUT300Segundos antes do navegador fechar (0 = nunca)
HOUND_SEARCH_PROXY-Proxy para todos os backends de busca (http/https/socks5/socks5h)
HOUND_SEARCH_DEADLINE8Prazo da busca em segundos
HTTP_PROXY-Proxy para requisições de fetch HTTP
HTTPS_PROXY-Proxy para requisições de fetch HTTPS

Conectando ao modo HTTP

Para clientes MCP que suportam HTTP (Claude Code, Open WebUI), use o IP LAN do seu host:

http://<your-host-ip>:8765/mcp

(Ou localhost:8765/mcp se estiver rodando na mesma máquina.)


🧰 As 6 ferramentas

FerramentaResumo
smart_fetchBusca qualquer URL. HTTP primeiro, com escalada automática para o navegador anti-detecção se bloqueado. Em lote, PDFs (com OCR + pontuação de qualidade), css_selector, focus, actions, paginação.
smart_crawlCrawl de mesmo domínio, melhor-primeiro. Cada página como markdown com content_ok + page_type (artigo / lista / js_shell). discover_only, crawl_urls, focus, modo sitemap, limites de tempo e tokens.
smart_searchBusca web local sem chave. 10 backends em paralelo, mescla e ranqueia com rerank neural + consenso entre backends. relevance_score + engines_consensus por resultado.
screenshotCaptura uma página como imagem. Para agentes multimodais (canvas, imagem-de-texto, layout visual).
cache_clearLimpa o cache de fetch. all=true apaga tudo.
versionVersão instalada + status de atualização.

🔎 Busca local sem chave

Hound fetches the web and brings it back to your agent

Sem chave de API, sem conta, sem serviço de terceiros. smart_search executa 10 backends sem chave em paralelo na sua máquina, mescla, deduplica e ranqueia. Retorna URLs + ranqueamento, não o conteúdo da página: o agente smart_fetch os resultados que correspondem ao que precisa (o ranqueamento é uma dica, não uma diretiva).

  • 🌐 10 backends independentes: duckduckgo, brave, mojeek, yahoo, yandex, startpage, google, qwant, além de wikipedia e grokipedia opcionais. Seis ou mais famílias de índices independentes, não o mesmo feed duas vezes.
  • 🧠 Rerank neural: um cross-encoder ONNX local (ms-marco-MiniLM-L-6-v2, Apache-2.0) rodando no onnxruntime que o Hound já inclui para OCR. Ranqueamento semântico estilo Exa, $0, na sua máquina. O modelo é baixado uma vez (~80MB, em cache, não incluído). Instalações enxutas usam consenso entre motores + ordem de posição do motor.
  • 🎯 Consenso entre backends: uma URL retornada por vários índices independentes recebe um boost de consenso: um sinal de autoridade gratuito da mesclagem, sem fetches extras. Cada resultado carrega relevance_score (0–1), fetch_relevance (alto/médio/baixo) e engines_consensus.
  • 🔍 find_similar: passe url=; o Hound busca uma página que você gosta, deriva uma consulta e reranca os candidatos contra essa página de origem. O find-similar do Exa, local.
  • 🛡️ Nunca morto: um quórum de diversidade espera pelo menos 3 backends contribuírem antes de retornar, então o viés ou rate-limit de um único backend não pode dominar. Um backend que apresenta CAPTCHA ou rate-limit é isolado por 60s e coberto pelos outros. engine_blocked na resposta informa quais esfriaram.
  • 📊 Filtros: site / exclude_sites (inclusão/exclusão de domínio), location / language / region (geo), page (0–10), freshness (dia | semana | mês | ano). Padrão de 6 resultados. Um filtro de qualidade descarta resultados de baixa relevância em vez de preencher até o máximo com lixo.
  • 📈 related_queries: consultas de acompanhamento extraídas de títulos e trechos de resultados (sem LLM). Busque uma para refinar uma consulta ampla.

A busca é 100% HTTP: nunca toca no navegador (o navegador Patchright único pertence exclusivamente ao smart_fetch).

🔧 Camada de Resiliência dos Motores de Busca

Raspar motores públicos a partir do seu IP pode sofrer rate-limit ou CAPTCHA. Nenhuma ferramenta local sem chave é à prova de balas contra bloqueio sustentado sem um proxy: o Hound é honesto sobre isso e depois torna o caso sem proxy o mais confiável possível para um único usuário:

#MecanismoO que faz
1Sessão aquecida persistente por motorUma sessão de longa duração reutilizada entre buscas: cookies + TLS se acumulam, então o motor vê um humano que retorna, não um bot novo. Também mais rápido.
2Pacing + jitter por motorDentro de uma busca, todos os motores disparam em paralelo (grátis); apenas rajadas no mesmo motor entre buscas recebem um pequeno atraso com jitter.
3Circuit breaker + cooldownUm motor bloqueado esfria automaticamente (60s) enquanto os outros continuam servindo.
4202 / 429 / 503 / 403 + Retry-AfterO rate-limit suave HTTP 202 do DDG é detectado; Retry-After é respeitado.
5Rotação de fingerprintUm pool de perfis TLS reais de Chrome / Edge / Firefox / Safari, escolhidos por requisição.
6Pool diverso + consenso10 backends em 6+ famílias de índices rodam em paralelo: nenhum motor é gargalo, e a concordância entre índices independentes é um sinal de autoridade gratuito.
7HOUND_SEARCH_PROXY + pool de rotaçãoRoteie requisições de motores por um ou mais proxies. Adicione até 20 e o Hound rotaciona a cada chamada de busca: o caminho à prova de balas para uso intenso.

Mesma postura de zona cinzenta do SearXNG / ddgs; nenhuma conformidade com termos de serviço de motores de busca é afirmada.

Rotação inteligente de proxy

A busca local sem chave raspa motores públicos a partir do seu IP. Uso sustentado pode sofrer rate-limit. A rotação de proxy do Hound permite adicionar vários proxies e alterna entre eles automaticamente: cada chamada de busca usa o próximo proxy, distribuindo o tráfego por todos os IPs. Proxies não saudáveis (erros de conexão) são esfriados automaticamente por 60s e ignorados. Se todos os proxies estiverem fora, o Hound cai para conexão direta para que a busca nunca falhe.

Configuração em 30 segundos:

# Add proxies (supports http, https, socks5, socks5h + auth)
hound proxy add "http://user:pass@31.59.20.176:6754"
hound proxy add "socks5://1.2.3.4:1080"
hound proxy add "http://1.2.3.4:8080" "socks5://5.6.7.8:1080"  # bulk add

# List configured proxies (credentials redacted)
hound proxy list

# Remove by index or clear all
hound proxy remove 0
hound proxy clear

Ou defina via variável de ambiente (separada por vírgulas):

export HOUND_SEARCH_PROXY="http://p1:8080,socks5://p2:1080,http://user:pass@p3:3128"

Máximo de 20 proxies. A configuração persiste em ~/.hound/search_proxies.json. A rotação é por chamada de busca (não por mecanismo), então todos os mecanismos em uma busca compartilham um IP, e a próxima busca rotaciona para o próximo proxy. hound doctor mostra o status do seu pool de proxies.

Fontes de proxy gratuitas testadas com o Hound:

PlataformaCadastroResultado testadoRecomendação
WebshareConta gratuita (sem cartão)10 proxies dedicados, 100% de taxa de sucesso, 6 paísesAltamente recomendado
ProxyScrapeNenhum2.000+ proxies, ~10% funcionam, atualizados a cada minutoInício rápido, sem conta

Os 10 proxies gratuitos do Webshare são dedicados (só seus, não compartilhados com outros scrapers), por isso alcançam 100% de sucesso. A lista pública do ProxyScrape é compartilhada e de curta duração, mas não exige cadastro. SOCKS5 supera HTTP para mecanismos de busca porque encapsula HTTPS de forma confiável.

# ProxyScrape: grab working SOCKS5 proxies (no signup needed)
curl -sL "https://api.proxyscrape.com/v4/free-proxy-list/get?request=display_proxies&proxy_format=protocolipport&format=text" | grep "^socks5://" | head -5

# Add them to Hound's rotation pool
# (paste each one: hound proxy add "socks5://ip:port")

🔑 Traga Sua Própria Chave (BYOK)

A busca local sem chave do Hound funciona com zero configuração e nunca desaparece. Mas alguns usuários têm chaves de API de provedores de busca, seja de planos gratuitos ou pagos. O Hound respeita isso: traga suas chaves, e o Hound as trata como cidadãos de primeira classe, com as mesmas garantias de confiabilidade de seus próprios mecanismos sem chave.

Quando chaves são configuradas, esses provedores se tornam a fonte de busca primária e os mecanismos locais sem chave do Hound são completamente desligados. Esse é o objetivo do BYOK: evitar acessar mecanismos de busca públicos a partir do seu IP. Os mecanismos locais rodam apenas como fallback de último recurso quando todas as chaves de API estão esgotadas ou limitadas por taxa, para que a busca nunca falhe.

O Hound usa um provedor por busca. Se você tem chaves para vários provedores, o Hound escolhe o primeiro disponível e só alterna para o próximo provedor quando o primeiro está esgotado. Isso significa que sua capacidade de busca escala com quantas chaves você configura para um único provedor, não com quantos provedores você empilha.

Provedores suportados

ProvedorNível gratuitoAutenticaçãoForça
Serper2.500 créditos únicosX-API-KEYSERP do Google, rápido
Tavily1.000 créditos/mêsBearerResultados ranqueados por IA
Exa1.000 buscas/mêsx-api-keyBusca neural
Firecrawl1.000 créditos/mêsBearerBusca web + crawl
TinyFish30 req/min (~43 mil/mês)X-API-KeyAlto throughput

Misture e combine. Use um provedor, use todos os cinco, alterne de provedor a qualquer momento. O Hound os trata como mecanismos paralelos no mesmo pipeline de ranqueamento.

Empilhamento de chaves

Adicione várias chaves por provedor. O Hound as empilha em um pool de rotação por provedor:

  • 🔁 Rotação automática: quando uma chave atinge o limite de taxa (HTTP 429), o Hound alterna para a próxima chave do mesmo provedor em milissegundos. A busca é concluída sem que o agente saiba que uma chave foi limitada.
  • Cooldown por chave: uma chave limitada por taxa entra em cooldown de 60 segundos. Uma chave inválida (401/403) entra em cooldown de 300 segundos. O Hound continua tentando as chaves restantes no pool.
  • 🛡️ Esgotamento gracioso: somente quando todas as chaves de todos os provedores estão esgotadas o Hound recorre aos seus mecanismos locais sem chave. A transição é perfeita: o agente recebe resultados de qualquer forma.
  • 📊 Teste de chave ao vivo: hound keys test faz uma chamada de API real por chave e informa quais são válidas, limitadas por taxa ou inválidas. Saiba antes de buscar.

Isso significa que sua capacidade de busca escala com quantas chaves você configura, não com o limite de taxa de uma única chave.

Gerenciamento de chaves via CLI

# Add a key (stack multiple keys for the same provider)
hound keys add serper YOUR_SERPER_KEY
hound keys add serper ANOTHER_SERPER_KEY   # stacked, auto-rotated
hound keys add tavily YOUR_TAVILY_KEY

# List all configured keys (redacted for safety)
hound keys list

# Test all keys (live API call per key)
hound keys test

# Test a specific provider
hound keys test serper

# Remove a specific key by index (0-based)
hound keys remove serper 0

# Remove all keys for a provider
hound keys remove serper

# Remove all keys across all providers
hound keys clear

As chaves são armazenadas em ~/.hound/search_keys.json com redação na exibição. O estado de rotação de chaves é apenas em memória (é redefinido na reinicialização).

Variáveis de ambiente

Para ambientes CI/CD, Docker ou efêmeros, defina variáveis de ambiente em vez do arquivo de configuração. Separadas por vírgula para várias chaves:

export HOUND_SEARCH_SERPER_KEYS=key1,key2,key3
export HOUND_SEARCH_TAVILY_KEYS=key1
export HOUND_SEARCH_EXA_KEYS=key1
export HOUND_SEARCH_FIRECRAWL_KEYS=key1
export HOUND_SEARCH_TINYFISH_KEYS=key1

As variáveis de ambiente substituem o arquivo de configuração para qualquer provedor que tenha variáveis de ambiente definidas. Provedores sem variáveis de ambiente recorrem ao arquivo de configuração. Misture ambos: alguns provedores no arquivo de configuração, outros via variáveis de ambiente.

Integração hound doctor

hound --doctor informa o status da sua configuração BYOK: quais provedores têm chaves, quantas chaves por provedor e se alguma está em cooldown. Um comando para ver o panorama completo.


🌐 Fetch e anti-bot

smart_fetch tenta HTTP simples primeiro (~1s). Se o site bloqueia HTTP ou serve um shell JS, ele escala automaticamente para um navegador anti-detecção Patchright com resolução de desafios Cloudflare. Dois níveis, nada para configurar.

  • 🛡️ Bypass Cloudflare integrado: um único Chrome furtivo aquece na inicialização. Ele fecha após 5 min de inatividade para liberar RAM (HOUND_BROWSER_IDLE_TIMEOUT, defina 0 para mantê-lo vivo para sempre) e reinicia em ~2s no próximo fetch. As páginas fecham após cada fetch, a memória ociosa permanece próxima da linha de base. Um navegador no total.
  • 🧬 Mecanismo stealth (v11.1+): detecção automática do Chrome do sistema (channel=chrome para impressão digital TLS real), perfis de impressão digital coerentes, patches na camada JS (correção de UA HeadlessChrome, navigator.webdriver=undefined, ruído de canvas via interceptação de getImageData+toDataURL, API de permissões), simulação de comportamento humano (curvas de mouse Bezier, rolagem natural, tempo de permanência) e um resolvedor de Cloudflare Turnstile com movimento de mouse humanizado. Veja o benchmark de stealth abaixo.
  • 🎯 Extração focada na consulta: smart_fetch(url, focus="...") retorna apenas os blocos relevantes por BM25. Reduz o contexto em 80%+ em páginas longas, sem re-fetch (executa pós-cache). Reenvie o mesmo focus ao paginar.
  • 🖱️ Interação com a página: actions=[{click:'button.load-more'},{fill:{selector:'#q',text:'x'}},{press:'Enter'},{wait:500},{scroll:3},{wait_selector:'.item'}] para carregar mais, formulários de busca, paginação, rolagem infinita. Força stealth + ignora o cache.
  • 🏷️ Metadados em cada resposta: título, descrição, nome do site, tipo, imagem, URL canônica, idioma, hora de publicação, autor (OpenGraph + JSON-LD + canônico).
  • 🔗 Links de saída: include_links=true preenche response.links classificados como citations (referências de conteúdo principal, as que valem a pena seguir) / navigation / external + uma dica de primary_source. Siga a cadeia de fontes de uma página em um único passo.
  • 🐕 Reddit, otimizado: URLs do Reddit são reescritas automaticamente para old.reddit.com (7× menor) e pulam direto para o navegador stealth. Listagens de subreddits são analisadas em posts estruturados com anúncios promovidos filtrados.
  • 💾 Cache inteligente: SQLite (modo WAL), indexado por URL + tipo de extração + css_selector + pages. Conteúdo ruim nunca é armazenado em cache; um limite de tamanho remove os mais antigos para que o cache de um agente de longa duração não cresça sem limites. cache_ttl=0 força conteúdo novo.
  • 📐 Paginação: conteúdo acima de 40KB é dividido em blocos; a resposta fornece next_offset para que o agente navegue pelas páginas com mais uma chamada (servida instantaneamente do cache).

🧬 Benchmark de stealth

Resultados do mundo real da v11.1.0, testados contra alvos anti-bot difíceis.

Sites de teste de detecção (todas as verificações passam):

SiteO que testaResultado
bot.sannysoft.comHeadlessChrome UA, webdriver, plugins, WebGL, permissions, SeleniumTUDO PASSA
CreepJSHash de canvas, impressão digital de áudio, detecção de mentiras200 OK
BrowserScanDetecção de CDP, análise de impressão digital200 OK
PixelscanDetecção de headless, consistência de impressão digital200 OK

Sites protegidos por anti-bot (conteúdo extraído):

SiteProteçãoStatusConteúdo
CanadianInsiderCloudflare Turnstile (o mais difícil no benchmark de 31 sites)20078 KB, título: "Canadian Insider"
MediumIntersticial Cloudflare20093 KB, título: "Medium"
StackOverflowCloudflare2001,1 MB, página de pergunta completa
NowSecureDesafio Cloudflare200180 KB, título: "nowsecure.nl"
GlassdoorDataDome200849 KB
RedditCloudflare lite2001 MB
Hacker NewsNenhum (linha de base)20035 KB, título: "Hacker News"
GitHubNenhum (linha de base)200523 KB

Nota: o Google Search retorna 429 (limite de taxa) pois usa sua própria detecção de bots, independente do Cloudflare. Isso é esperado.

Sinais de stealth verificados:

SinalValorStatus de detecção
navigator.webdriverundefined (corrigido de false)Não detectado
navigator.userAgentChrome/150 (HeadlessChrome removido)Não detectado
navigator.platformWin32 (Chrome real do sistema)Não detectado
navigator.plugins.length5 (Chrome real do sistema)Não detectado
window.chromeobject (presente)Não detectado
WebGL vendor/rendererGPU real (Intel UHD, Direct3D11)Não detectado
Canvas fingerprintRuído por sessão (diferente a cada sessão)Não detectado
TLS fingerprintChrome 150 JA4 real (Chrome do sistema)Não detectado

Eficiência de memória (5 fetches sequenciais):

O RSS diminuiu 3,5 MB ao longo de 5 fetches. Sem crescimento de RAM. O comando CDP Memory.simulatePressureNotification aciona o GC interno do Chrome + limpeza de cache após cada fetch (~5ms, sem interrupção).


🕷️ Crawl

smart_crawl percorre links do mesmo domínio em ordem best-first: URLs descobertas são pontuadas por relevância de foco + probabilidade de conteúdo (docs/guia/api recebem bônus, login/enviar/carrinho são penalizados) + profundidade rasa, para que páginas de conteúdo sejam rastreadas antes de lixo quando o orçamento é apertado.

  • 🎯 Extração adaptativa de conteúdo: artigo/docs → conteúdo principal via trafilatura; páginas de lista/índice (HN, agregadores, diretórios) → uma lista de links estruturada * [title](url); shells JS → detectados e relatados honestamente.
  • 🗺️ Modo sitemap: options sitemap=true mapeia o site inteiro a partir de sitemap.xml em UM fetch (lista completa de URLs + lastmod, sem BFS). sitemap='auto' o usa se o site tiver um, caso contrário recorre ao BFS. Reduz um crawl de descoberta de centenas de páginas a uma única chamada.
  • 📍 discover_only=true: apenas mapa de URLs (baseado em BFS). Para sites grandes, prefira sitemap=true.
  • 🎯 focus='query': prioriza páginas relevantes dentro do orçamento E filtra por foco o conteúdo de cada página.
  • 📋 crawl_urls=[...]: crawl seletivo de segunda fase de um subconjunto escolhido (sem redescoberta).
  • 🛡️ Dedup + escopo: URLs normalizadas para que /docs e /docs/ nunca sejam rastreadas duas vezes. Apenas mesmo domínio por padrão; path_include / path_exclude para definir o escopo.
  • ⏱️ Limites: max_pages (padrão 10), max_depth (padrão 2), max_total_chars (orçamento de tokens), deadline_ms (tempo total, padrão 120000). Cada página carrega content_ok + status + fetched_at; next_action informa se o crawl parou antes do fim.

📄 PDF + OCR de PDF escaneado

smart_fetch detecta um PDF (por content-type ou bytes mágicos %PDF) e o extrai para markdown estruturado com pdfplumber (MIT): ordem de leitura multicoluna, tabelas reais como tabelas markdown, títulos por tamanho de fonte, parágrafos sem hifenização, um cabeçalho de metadados e marcadores --- Page N ---.

  • 📑 table_of_contents: o índice do PDF como [{level, title, page, end_page}]. PDFs sem marcadores recebem um mapa de fallback baseado em títulos. Passe pages='23-31' para capturar uma seção por intervalo e economizar tokens.
  • 🔍 OCR automático para corrupção CID (o truque principal): artigos acadêmicos incorporam subconjuntos de fontes sem mapa Unicode, então extratores emitem lixo (cid:71)(cid:302)... para figuras/diagramas/matemática. Mas os glifos são renderizados corretamente. O Hound detecta páginas com lixo CID, as renderiza via pypdfium2 e aplica OCR com rapidocr, recuperando o texto real automaticamente.
  • 🖼️ PDFs escaneados / somente imagem (e páginas web somente imagem) também recebem OCR automático. Pure-pip, sem binário de sistema, com [all].
  • 📊 quality_score (0,0–1,0) + content_ok honesto: confie mais no conteúdo do PDF quanto mais próximo de 1,0 o score estiver.
  • 📎 password para PDFs criptografados; include_media=true para metadados de imagem por página; uma URL .pdf que retorna login/paywall é reportada como auth_required.

📸 Captura de tela

screenshot captura uma página como imagem. Somente para agentes multimodais: use quando o conteúdo for renderizado como imagens / canvas / imagem-de-texto ou quando você precisar do layout visual. Agentes somente de texto devem usar smart_fetch em vez disso. Uma sessão de navegador furtiva é gerenciada automaticamente.


📊 Comparação: ferramentas gratuitas

A maioria das ferramentas web gratuitas para agentes faz uma coisa e deixa o resto de fora. Hound é a única que junta tudo em um único servidor MCP local por $0, sem chaves.

HoundCrawl4AIParallel SearchJina ReaderFirecrawl (OSS/gratuito)
Preço$0 para sempre$0 (auto-hospedado)gratuito, com limite de taxagratuito, com limite de taxa$0 auto-hospedado / 1K grátis
Roda localmentesimsimnão (servidores deles)não (API deles)auto-hospedado: sim (Redis + Docker)
Busca websim (local sem chave, 10 backends)nãosim (remoto)simnão
Crawl profundosim (best-first, sitemap, orçamento)simnãonãosim (nuvem)
Anti-bot / Cloudflareembutido (Patchright)limitadosim (infra deles)nenhumnão por padrão
PDF → markdown estruturadosim (tabelas, sumário, subconjunto)parcialnãosim (nativo)sim (nuvem + OCR)
PDF escaneado / OCR de imagemsim (rapidocr, pip puro)nãonãonãosim (nuvem paga)
Interação com páginasim (actions)hooks (código)nãonãosim (nuvem)
Extração focada em consultasim (focus, BM25)sim (filtro BM25)nãonãonão
Sinais de agentesim (content_ok/next_action/summary/relevance_score)nãonãonãonão
instructions na conexãosimnãonãonãonão
Servidor MCPsim (oficial)comunidadesim (oficial)sim (oficial)construa você mesmo
Custo de tokens (tools/list)~2,7K (6 ferramentas)varian/dn/dvaria (12 ferramentas)

A versão curta: Crawl4AI rastreia bem, mas não tem busca e tropeça no Cloudflare. Parallel Search é somente busca remota, sem crawl, e roda nos servidores deles. Jina busca, mas limita a taxa e roteia pela Jina. Firecrawl mantém os recursos bons atrás da nuvem paga. Hound é a única ferramenta gratuita que combina busca local sem chave, bypass de Cloudflare embutido, crawl best-first, OCR de PDF escaneado, interação com página e extração focada em consulta em um único servidor MIT local: $0, sem contas, sem chaves.

Quando um serviço pago faz sentido

Scrapers pagos (Bright Data, ZenRows, Firecrawl pago, Spider.cloud) podem superar ferramentas gratuitas nos anti-bots mais difíceis (DataDome, Akamai, Cloudflare Turnstile) e em escala massiva, porque executam grandes redes de proxies residenciais. APIs de busca pagas (Exa, Tavily) oferecem busca neural hospedada. Elas custam de $16 a $500+/mês, exigem contas + chaves de API, e enviam suas consultas + conteúdo pelos servidores delas. Use Hound para pesquisa web local gratuita, sem contas e sem chaves; recorra a um serviço pago apenas para escala empresarial, sites que o Hound explicitamente não consegue acessar, ou busca neural hospedada em escala.


📦 Instalação

pip install hound-mcp[all]          # recommended: fetch + crawl + keyless search + PDF + OCR + neural rerank
playwright install chromium
Instalação enxuta (modo somente HTTP, sem navegador/OCR)
pip install hound-mcp               # fetch + crawl + keyless search (HTTP-only, no stealthy browser)

A instalação enxuta funciona em todas as plataformas (incluindo Termux/Android). Ela oferece busca sem chave com múltiplos mecanismos, fetch HTTP com escalonamento automático (somente camada HTTP, sem navegador furtivo), crawl e cache. Escalonamento com navegador furtivo e captura de tela exigem dependências de navegador do extra [all].

Variáveis de ambiente opcionais
VariávelFinalidade
HOUND_SEARCH_PROXYRoteie todas as requisições de mecanismos de busca pelo seu próprio proxy (http://host:port, socks5://... ou user:pass@host:port). Para uso intenso e sustentado de busca com proxy rotativo / residencial. Não é necessário para uso normal de usuário único.
HOUND_SEARCH_MIN_INTERVALSubstitua o piso de ritmo por mecanismo (segundos, float). 0 = usar os padrões embutidos (DDG 1,2s, Bing 1,5s, Wikipedia 0,3s). Ajuste para usuários avançados.
HOUND_BROWSER_IDLE_TIMEOUTSegundos de inatividade do navegador antes que o Chrome aquecido seja fechado completamente para liberar RAM (padrão 300, ou seja, 5 min). O próximo fetch o relança em ~2s. Defina como 0 para manter o Chrome vivo para sempre (comportamento antigo).

Nenhuma chave de API ou conta é necessária para nada: a busca é sem chave e local.

Atualizando, revertendo e reparando
hound -u          # update to latest (brick-proof: --no-deps, detached helper, self-heal)
hound --doctor    # health check: launcher, imports, metadata, deps, PyPI, repair script
hound --rollback  # reinstall the version from before the last update

hound -u foi projetado para nunca quebrar a instalação. Ele atualiza com --no-deps (sem extras pesados que falham no meio da instalação); no Windows ele executa pip em um helper destacado depois que o launcher sai (o Windows não consegue sobrescrever um .exe em execução), liberando o launcher via truque de renomeação. Se uma passada de pip deixar a versão inalterada, ele se auto-repara com uma passada de --force-reinstall --no-deps.

Se hound estiver quebrado (um pip manual falho enquanto um servidor segurava o launcher, uma atualização pela metade), a rede de segurança é um script independente escrito fora de site-packages a cada atualização:

python ~/.hound/repair.py   # stops hound, force-reinstalls hound-mcp from PyPI, verifies

Ele sobrevive porque não faz parte do pacote hound-mcp, então um pip uninstall falho nunca o remove. hound --doctor diagnostica a instalação e informa a correção certa.


🤖 Diga ao seu agente para instalá-lo

Cole isto no seu agente:

Install the Hound MCP server on this machine. Follow every step. Do not skip any.

1. Figure out which agent harness you are running on (OpenCode, Hermes, Pi, etc). Then find: (a) where the MCP config file lives, and (b) what format it expects for adding a local MCP server. Read the harness docs if needed. Do not guess.

2. Run: pip install hound-mcp[all]
   Then run: playwright install chromium (But only if it isnt installed already, verify first about its existence)
   If either fails, stop and tell the user.

3. Find the MCP config file from step 1 and back it up before editing. Add a new MCP server named "hound" with command "hound", no arguments, in the format your harness requires. No API keys or environment variables are needed (search is keyless and local).

4. Save the file. Tell the user to restart the agent. After restart, smart_fetch, smart_crawl, smart_search, screenshot, cache_clear and version should be available.
Para usuários do agente Pi

Instale o servidor MCP Hound e depois a extensão Pi:

pip install hound-mcp[all]
pi install npm:@houndmcp/hound-mcp-pi

Sem chaves de API, sem arquivo de configuração, sem adaptador MCP necessário. A extensão inicia hound como um subprocesso singleton e registra todas as 6 ferramentas (web_fetch, web_search, web_crawl, web_screenshot, cache_clear, hound_version) como ferramentas Pi nativas. Pré-aquecido no início da sessão. Execute /reload para ativar.

Atualizando:

hound -u                              # update the MCP server
pi update npm:@houndmcp/hound-mcp-pi  # update the extension

A extensão verifica a sincronização de versão no início da sessão e avisa se a extensão e o hound divergirem em uma versão principal.

Para usuários do Open WebUI (HTTP)

Open WebUI v0.6.31+ fala o transporte HTTP streamable nativamente. Execute o Hound em modo HTTP e aponte o Open WebUI para ele, sem proxy mcpo necessário:

hound --http --host 127.0.0.1 --port 8765

Depois, no Open WebUI, adicione um servidor MCP com a URL http://127.0.0.1:8765/mcp. Clientes Stdio (Claude Code, Cursor, OpenCode, Pi, etc.) usam apenas hound sem flag.


⚠️ Armadilhas conhecidas

Coisas que podem surpreender você se não as conhecer:

ArmadilhaO que saber
Chaves de API e credenciais de proxy são armazenadas em texto puro~/.hound/search_keys.json e ~/.hound/search_proxies.json são JSON simples. Se você estiver em uma máquina compartilhada, defina permissões de arquivo ou use variáveis de ambiente em vez dos arquivos de configuração.
robots.txt está desativado por padrãoO Hound verifica robots.txt somente quando respect_robots=True é passado para smart_fetch. Isso é intencional: muitos sites bloqueiam todos os agentes que não são Googlebot, e respeitar isso por padrão tornaria a ferramenta inútil para pesquisa. O recurso existe para usuários que querem conformidade.
O navegador Playwright não é instalado pelo pip installhound-mcp[all] instala dependências Python, mas o binário Chromium exige um python -m playwright install chromium separado. hound doctor verifica isso e informa se estiver ausente. Sem ele, o Hound volta para fetch somente HTTP (sem navegador furtivo, sem renderização JS, sem resolução de CAPTCHA).
O cache serve conteúdo por 1 hora por padrãocache_ttl tem como padrão 3600 segundos. Para conteúdo fresco, passe cache_ttl=0 para forçar um fetch ao vivo. Respostas em cache mostram duration_ms: 0 na saída.
Não foi feito para scraping em massaO Hound foi projetado para pesquisa agêntica: agentes de IA buscando páginas, procurando informações, rastreando documentação. Não é uma ferramenta de scraping em massa. Se você usá-lo para raspar milhares de páginas em escala, vai bater em limites de taxa, limites de banda e paredes anti-bot. Isso não são bugs. Use uma plataforma de scraping dedicada para isso.

⚠️ Limites honestos

Nenhuma ferramenta gratuita pode fazer tudo. O Hound é transparente sobre o que não consegue:

LimiteO que acontece em vez disso
DataDome / Akamai / Cloudflare Turnstile (interativo)Não é contornado. next_action diz ao agente para trocar de fonte em vez de tentar de novo.
Limites de taxa de busca / CAPTCHAsResolvidos por diversidade: 10 backends sem chave rodam em paralelo; um backend que limita taxa/CAPTCHA é aberto em circuito para um resfriamento para que os outros assumam. hound proxy add (v12.4.0+) adiciona até 20 proxies rotativos que alternam a cada chamada de busca, mantendo seu IP real intocado.
Busca neural / find_similarPrecisa de hound-mcp[all] (o reranker ONNX roda no mesmo onnxruntime que o OCR; o modelo é baixado uma vez). Instalações enxutas obtêm consenso entre backends + ranqueamento por posição de mecanismo.
Sites que exigem loginFora do escopo (o Hound faz interação com página, não sessões autenticadas).
Shadow-DOM profundo / SPAs difíceisactions (rolagem, clique, wait_selector) alcança a maior parte; penetração profunda em shadow-DOM ainda não está conectada.
YouTubeTexto mínimo.

Quando um fetch ou busca falha, a resposta diz exatamente o porquê e o que tentar em seguida, para que o agente não desperdice chamadas adivinhando.


🪙 Custo de tokens

A maioria dos servidores MCP custa 3–5K tokens só para existir. As 6 ferramentas do Hound custam ~2,7K tokens em tools/list (medido com cl100k_base); os instructions de conexão (~0,8K, o documento de orientação) são injetados UMA VEZ no handshake, não repetidos a cada turno. Sua janela de contexto é cara; o Hound a respeita.


Se o Hound economiza seu tempo, ⭐ o repositório: isso ajuda outros a encontrá-lo.

GitHub stars

MIT · Changelog · Issues · PyPI