MCP-WebSearch-SearXNG

WebSearch SearXNG + Servidor MCP

Um mecanismo de busca metasearch SearXNG auto-hospedado emparelhado com o servidor MCP mcp-searxng, construído para LLMs, agentes e aplicações que usam ferramentas. Permite que seu modelo (ou agente autônomo) navegue na web, execute buscas em vários mecanismos ao mesmo tempo e exiba imagens diretamente no seu front-end. Tudo roda inteiramente na sua própria máquina via Docker, acessado pelo seu navegador, e fala MCP sobre transporte HTTP Streamable, então se conecta a qualquer cliente compatível com MCP (Claude Desktop, Cline, Open WebUI, LM Studio, frameworks de agentes personalizados, etc.). Aprimorado com busca de imagens/vídeos/categorias, paginação por deslocamento e redimensionamento inteligente de imagens base64 para modelos com capacidade de visão. Ambos os serviços permanecem na sua rede local, então nada sai da sua máquina a menos que você peça. Sem anúncios, sem telemetria, sem rastreadores de terceiros, sem contas — o front-end SearXNG é privado por design e os patches MCP não adicionam nenhum phone-home próprio.

Front-end SearXNG — a interface de metasearch que respeita a privacidade em localhost:8888. O mesmo backend que o servidor MCP consulta internamente.

Cadeia de ferramentas autônoma — o modelo dispara várias chamadas searxng_web_search em paralelo e depois encadeia em web_url_read para extrair o texto completo do artigo.

Extração de texto limpa — conteúdo de artigos longos extraído por web_url_read, elementos desnecessários removidos, pronto para o modelo resumir.

Imagem inline em briefing de notícias — imagem buscada e redimensionada pelo pipeline sharp do web_url_read. Sem CDN externo, servida como bloco de imagem MCP base64.

Busca paralela multi-consulta — consultas separadas por | distribuem várias chamadas searxng_web_search de uma vez, chegando ao meme "It's Gonna Be May".

Blocos de imagem nativos — múltiplas imagens retornadas inline. O parâmetro detail (low/medium/high) controla a qualidade do redimensionamento versus o custo de tokens.

Instalação

Nota rápida sobre privacidade antes de começar. Esta pilha roda inteiramente na sua máquina e é privada por design (sem telemetria, sem contas, sem rastreadores de terceiros), mas os padrões são ajustados para "simplesmente funcionar", não para máxima privacidade. Antes de expor além do seu próprio computador, para sua LAN, internet ou qualquer outra pessoa, leia ADVANCED.md

Pré-requisitos

• Docker e Docker Compose devem estar instalados
• Node.js >= 20 deve estar instalado

Passo 1: Clone o Repositório

git clone https://github.com/hypersniper05/MCP-WebSearch-SearXNG.git
cd MCP-WebSearch-SearXNG

Isso fornece o docker-compose.yml, o settings.yml do SearXNG, os patches MCP e o Dockerfile personalizado já organizados — então o próximo passo é direto para a configuração.

Prefere configurar tudo manualmente em vez de clonar? Veja Construindo do zero (sem clonar) em ADVANCED.md.

Passo 2: Configure as Configurações do SearXNG

O searxng/config/settings.yml incluído já está pré-configurado para esta pilha — saída JSON habilitada, limitador de taxa desativado, novas tentativas rápidas de mecanismos, um conjunto selecionado de mecanismos funcionais (Bing, Mojeek, Yahoo, Startpage, etc.). A única coisa que você precisa ajustar aqui é o secret_key.

Quer mudar quais mecanismos estão habilitados, o tempo limite de solicitação ou qualquer outro padrão do SearXNG? Veja Modificando as configurações padrão em ADVANCED.md.

Defina o secret_key (ou use a variável de ambiente)

O settings.yml incluído tem um espaço reservado secret_key: "CHANGE_ME_BEFORE_RUNNING". O SearXNG iniciará com o espaço reservado, então para uma instância pessoal apenas em localhost você pode deixá-lo e voltar a isso mais tarde. Mas se você vincular a 0.0.0.0, expor isso à sua LAN ou compartilhar com qualquer pessoa, gere um real — caso contrário, um atacante pode forjar tokens de proxy de imagem e CSRF contra sua instância.

Duas maneiras de definir (escolha uma):

Opção A — variável de ambiente (recomendada):

Crie um arquivo .env ao lado de docker-compose.yml:

SEARXNG_SECRET=<paste your generated 64-char hex string here>

A variável de ambiente substitui o que está em settings.yml, então o espaço reservado pode permanecer no arquivo rastreado para sempre.

Opção B — edite settings.yml diretamente:

Substitua o espaço reservado pela sua chave gerada. Se fizer isso, certifique-se de não vazar seu settings.yml.

Gere uma chave com qualquer ferramenta que você tiver instalada:

# PowerShell (Windows — built in)
[System.BitConverter]::ToString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).Replace('-','').ToLower()

# Node.js (already installed for the MCP server)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Docker (works anywhere this stack does)
docker run --rm alpine sh -c "apk add --no-cache openssl > /dev/null && openssl rand -hex 32"

# Git Bash / Linux / macOS
openssl rand -hex 32

# Python
python -c "import secrets; print(secrets.token_hex(32))"

Para o restante das compensações de privacidade/endurecimento (exposição LAN, autenticação MCP, roteamento Tor), veja ADVANCED.md.

Passo 3: Construa e Inicie Tudo

docker compose build
docker compose up -d

Passo 4: Verifique os Serviços

Verificação de saúde:

curl -s http://localhost:3001/health

Esperado: {"status":"healthy","server":"ihor-sokoliuk/mcp-searxng","version":"0.9.2-enhanced","transport":"http"}

Busca de teste:

curl -s "http://localhost:8888/search?q=test&format=json" | head -c 200

Passo 5 (apenas se acessar de outra máquina): Abra os vínculos para sua LAN / Tailscale

Por padrão, o docker-compose.yml incluído vincula os serviços a 127.0.0.1 — acessível apenas pela máquina que executa o Docker. Se você quiser que outro dispositivo na sua LAN, sua tailnet Tailscale ou qualquer outro lugar fora do host alcance a interface SearXNG ou o endpoint MCP, você precisa mudar os vínculos para 0.0.0.0.

Diagnóstico rápido para identificar isso:

docker compose ps

Olhe a coluna PORTS. Se você vir:

O que você vê	O que significa
0.0.0.0:8888->8080/tcp	Acessível de qualquer lugar na rede ✓
127.0.0.1:8888->8080/tcp	Apenas localhost — o exato sintoma que faz o acesso externo "expirar"

Se ambas as linhas mostrarem 127.0.0.1: (ou uma mostrar e outra não, como SearXNG bloqueado enquanto MCP está aberto), edite docker-compose.yml e mude o(s) vínculo(s):

services:
  searxng:
    ports:
      - "0.0.0.0:8888:8080"   # was 127.0.0.1:8888:8080

  mcp-searxng:
    ports:
      - "0.0.0.0:3001:3001"   # was 127.0.0.1:3001:3001

Então um down + up completo é necessário (mudanças de porta não se aplicam em um simples restart):

docker compose down
docker compose up -d
docker compose ps

Ambas as linhas devem agora mostrar 0.0.0.0:....

Se docker compose ps já mostra 0.0.0.0 e o acesso externo ainda falha, é o firewall do sistema operacional. No Windows, permita as portas de um PowerShell administrativo:

New-NetFirewallRule -DisplayName "MCP SearXNG (8888)" -Direction Inbound -Protocol TCP -LocalPort 8888 -Action Allow
New-NetFirewallRule -DisplayName "MCP Server (3001)"   -Direction Inbound -Protocol TCP -LocalPort 3001 -Action Allow

Nota de segurança: mudar para 0.0.0.0 expõe os serviços a qualquer pessoa que possa alcançar sua máquina nessas portas. O servidor MCP não tem autenticação. Se você for além de uma rede doméstica/Tailscale confiável, leia ADVANCED.md → Tier 2 para adicionar um proxy reverso com autenticação.

Resumo dos Endpoints

Serviço	URL	Propósito
Interface SearXNG	http://localhost:8888	Interface de busca web
API SearXNG	http://localhost:8888/search	API de busca JSON
Servidor MCP	http://localhost:3001/mcp	MCP Streamable HTTP
Saúde MCP	http://localhost:3001/health	Endpoint de verificação de saúde

Precisa de TLS para um cliente somente HTTPS? O caminho mais limpo é Tailscale Serve se ambas as extremidades estiverem em uma tailnet (certificado real confiável pela Let's Encrypt, zero configuração por cliente), ou um proxy reverso como Caddy / nginx com seu próprio certificado caso contrário. Qualquer um é adicionado na frente do endpoint HTTP MCP existente sem nenhuma mudança nesta pilha.

Ferramentas MCP

1. searxng_web_search

Busca web com suporte a categoria, paginação e filtragem.

Parâmetro	Tipo	Descrição
query	string	Consulta de busca (obrigatório)
categories	string	general, images, videos, news, music, files, it, science, social media, map
max_results	number	Resultados por lote (padrão: 20 gerais, 10 imagens/vídeos)
offset	number	Pular N resultados para paginação (ex.: 10 para resultados 11-20)
pageno	number	Número da página SearXNG
time_range	string	day, month, year
language	string	Código de idioma (ex.: en, fr)
safesearch	number	0 (nenhum), 1 (moderado), 2 (estrito)

2. web_url_read

Busca e lê URLs. Detecta automaticamente URLs de imagem e retorna blocos de imagem base64 redimensionados.

Parâmetro	Tipo	Descrição
url	string	URL para ler (obrigatório)
detail	string	Nível de redimensionamento de imagem: low (448px, ~256 tokens), medium (768px, ~756 tokens, padrão), high (1280px, ~2048 tokens)
startChar	number	Deslocamento de caracteres para paginação de texto
maxLength	number	Máximo de caracteres para retornar
section	string	Extrair conteúdo sob um título
paragraphRange	string	Intervalo de parágrafos (ex.: 1-5)
readHeadings	boolean	Retornar apenas títulos

Fluxo de Busca de Imagens

1. searxng_web_search({query: "sunset", categories: "images"}) → retorna URLs de imagem + metadados
2. Escolha uma imagem → web_url_read({url: "https://example.com/sunset.jpg", detail: "medium"}) → retorna imagem base64 redimensionada
3. Para ver mais resultados → searxng_web_search({query: "sunset", categories: "images", offset: 10}) → resultados 11-20

Arquivos de Patch Personalizados

Todos os patches estão em mcp-searxng-patches/ e montados somente leitura no contêiner:

Arquivo	Propósito
Dockerfile	Estende a imagem base com sharp para redimensionamento de imagem
types.js	Esquemas de ferramentas com parâmetros categories, offset, max_results, detail
search.js	Formatação de busca ciente de categoria, paginação por deslocamento, campos de resultado de imagem/vídeo
url-reader.js	fetchImage() com redimensionamento sharp (3 predefinições de detalhe), blocos de imagem MCP base64
index.js	Conexão de manipuladores de ferramentas, detecção de URL de imagem, passagem de detalhe

Atualizando o SearXNG

O SearXNG está fixado em :latest em docker-compose.yml, então atualizações são puxar e reiniciar. A configuração em searxng/config/settings.yml é montada por volume e sobrevive à atualização.

Atualização manual (recomendada)

cd MCP-WebSearch-SearXNG
docker compose pull searxng        # grab newest :latest image
docker compose up -d searxng       # recreate container with new image
docker compose logs searxng --tail 100   # check for config-schema warnings
docker image prune -f              # remove the old image

Lançamentos principais ocasionalmente renomeiam chaves em settings.yml ou adicionam campos obrigatórios. Verifique a página de lançamentos do SearXNG para mudanças que quebram compatibilidade antes de atualizar.

Fixar em uma versão específica (mais seguro / reproduzível)

Substitua :latest em docker-compose.yml por um lançamento com data, por exemplo:

image: docker.io/searxng/searxng:2026.4.15-abc1234

As atualizações tornam-se então uma edição explícita — revise as notas de lançamento, atualize a tag, docker compose up -d.

Atualizações automáticas

Opção	Prós	Contras
Contêiner Watchtower	Configure e esqueça	Quebra silenciosa em mudanças de esquema de configuração
docker compose pull && up -d agendado (Agendador de Tarefas ou agente /schedule)	Você controla a cadência	Mesmo risco de quebra de esquema
Notificações de lançamento do GitHub + atualização manual	Mais seguro	Mais lento

Um meio-termo razoável: agende um trabalho semanal que execute docker compose pull e relate se uma nova imagem está disponível, mas não a aplique automaticamente.

Atualizando o servidor MCP

mcp-searxng é construído localmente a partir de mcp-searxng-patches/Dockerfile (base: isokoliuk/mcp-searxng:latest) com patches JS personalizados montados por cima. Para puxar mudanças upstream do MCP:

1. docker compose build --pull mcp-searxng — reconstrói a partir de uma imagem base recém-puxada
2. docker compose up -d mcp-searxng — recria o contêiner
3. Verifique se os patches em mcp-searxng-patches/*.js ainda se aplicam corretamente contra quaisquer mudanças na API upstream (verifique docker compose logs mcp-searxng para erros)

Se o upstream renomear módulos internos ou alterar assinaturas de funções, os patches JS montados por volume podem precisar ser rebaseados manualmente.

Testado com

• Qwen3.6 35B A3B — executa tanto searxng_web_search (incluindo consultas múltiplas e filtros de categoria) quanto web_url_read (modos texto + imagem) de forma confiável. Seleção de ferramentas, inferência de parâmetros e interpretação de resultados funcionam bem com este modelo.

Notas

• O servidor MCP usa transporte HTTP Streamable (não stdio ou apenas SSE)
• SearXNG conecta-se internamente via hostname Docker searxng:8080
• Todos os dados permanecem locais — nenhuma chave de API externa necessária
• Patches personalizados são licenciados sob MIT, auditados, sem acesso a sistema de arquivos/shell, sem telemetria
• Mecanismos de busca: Bing, Startpage, Mojeek, Yahoo ativos; Google com UI móvel (pode bloquear intermitentemente)