MCP-SearXNG-Enhanced Web Search

Um servidor MCP aprimorado para pesquisa web SearXNG, utilizando uma pesquisa web com reconhecimento de categoria, raspagem web e incluindo uma ferramenta de recuperação de data/hora.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP SearXNG Enhanced

Um servidor Model Context Protocol (MCP) para busca web com consciência de categoria, raspagem de sites e ferramentas de data/hora. Projetado para integração perfeita com SearXNG e clientes MCP modernos.

Recursos

🔍 Busca web com tecnologia SearXNG e suporte a categorias (geral, imagens, vídeos, arquivos, mapas, mídias sociais)
📄 Raspagem de conteúdo de sites com metadados de citação e conversão automática de URLs do Reddit
📜 Suporte inicial à leitura de PDF com conversão para Markdown usando PyMuPDF/PyMuPDF4LLM
💾 Cache em memória com validação automática de frescor
🚦 Limitação de taxa baseada em domínio para evitar abuso do serviço
🕒 Ferramenta de data/hora com reconhecimento de fuso horário
⚠️ Tratamento robusto de erros com tipos de exceção personalizados
🐳 Dockerizado e configurável via variáveis de ambiente
⚙️ Persistência de configuração entre reinicializações do contêiner

Início Rápido

Pré-requisitos

Docker instalado no seu sistema
Uma instância SearXNG em execução (auto-hospedada ou endpoint acessível)

Instalação e Uso

Construir a imagem Docker:

docker build -t overtlids/mcp-searxng-enhanced:latest .

Executar com sua instância SearXNG (Execução Manual do Docker):

docker run -i --rm --network=host \
  -e SEARXNG_ENGINE_API_BASE_URL="http://127.0.0.1:8080/search" \
  -e DESIRED_TIMEZONE="America/New_York" \
  overtlids/mcp-searxng-enhanced:latest

Neste exemplo, SEARXNG_ENGINE_API_BASE_URL está definido explicitamente. DESIRED_TIMEZONE também está definido explicitamente como America/New_York, que corresponde ao seu valor padrão. Se uma variável de ambiente não for fornecida usando um sinalizador -e durante o comando docker run, o servidor usará automaticamente o valor padrão definido em seu Dockerfile (consulte a tabela de Variáveis de Ambiente abaixo). Assim, se você pretende usar o padrão para DESIRED_TIMEZONE, pode omitir o sinalizador -e DESIRED_TIMEZONE="America/New_York". No entanto, SEARXNG_ENGINE_API_BASE_URL é crítico e geralmente precisa ser definido para corresponder ao endereço da sua instância SearXNG específica se o padrão do Dockerfile (http://host.docker.internal:8080/search) não for apropriado.

Nota sobre Execução Manual do Docker: Este comando executa o contêiner Docker de forma independente. Se você estiver usando um cliente MCP (como Cline no VS Code) para gerenciar este servidor, o cliente iniciará sua própria instância do contêiner usando as configurações definidas em sua própria configuração. Para que o cliente MCP use variáveis de ambiente específicas, elas devem ser configuradas nas configurações do cliente para este servidor (veja abaixo).

Configurar seu cliente MCP (ex.: Cline no VS Code):

Para que seu cliente MCP gerencie e execute este servidor corretamente, você deve definir todas as variáveis de ambiente necessárias nas configurações do cliente para o servidor overtlids/mcp-searxng-enhanced. O cliente MCP usará essas configurações para construir o comando docker run.

A seguir está a configuração padrão recomendada para este servidor nas configurações JSON do seu cliente MCP (ex.: cline_mcp_settings.json). Este exemplo lista explicitamente todas as variáveis de ambiente definidas com seus valores padrão conforme definido no Dockerfile. Você pode copiar e colar diretamente e personalizar quaisquer valores conforme necessário.

{
  "mcpServers": {
    "overtlids/mcp-searxng-enhanced": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network=host",
        "-e", "SEARXNG_ENGINE_API_BASE_URL=http://host.docker.internal:8080/search",
        "-e", "DESIRED_TIMEZONE=America/New_York",
        "-e", "ODS_CONFIG_PATH=/config/ods_config.json",
        "-e", "RETURNED_SCRAPPED_PAGES_NO=3",
        "-e", "SCRAPPED_PAGES_NO=5",
        "-e", "PAGE_CONTENT_WORDS_LIMIT=5000",
        "-e", "CITATION_LINKS=True",
        "-e", "MAX_IMAGE_RESULTS=10",
        "-e", "MAX_VIDEO_RESULTS=10",
        "-e", "MAX_FILE_RESULTS=5",
        "-e", "MAX_MAP_RESULTS=5",
        "-e", "MAX_SOCIAL_RESULTS=5",
        "-e", "TRAFILATURA_TIMEOUT=15",
        "-e", "SCRAPING_TIMEOUT=20",
        "-e", "CACHE_MAXSIZE=100",
        "-e", "CACHE_TTL_MINUTES=5",
        "-e", "CACHE_MAX_AGE_MINUTES=30",
        "-e", "RATE_LIMIT_REQUESTS_PER_MINUTE=10",
        "-e", "RATE_LIMIT_TIMEOUT_SECONDS=60",
        "-e", "IGNORED_WEBSITES=",
        "overtlids/mcp-searxng-enhanced:latest"
      ],
      "timeout": 60
    }
  }
}

Pontos-chave para Configuração do Cliente MCP:

O exemplo acima fornece um conjunto completo de argumentos para executar o contêiner Docker com todas as variáveis de ambiente definidas com seus valores padrão.
Para personalizar qualquer configuração, basta modificar o valor da linha -e "VARIABLE_NAME=value" correspondente dentro do array args na configuração do seu cliente MCP. Por exemplo, para alterar SEARXNG_ENGINE_API_BASE_URL e DESIRED_TIMEZONE, você ajustaria suas respectivas linhas.
Consulte a tabela "Variáveis de Ambiente" abaixo para uma descrição detalhada de cada variável e seu padrão.
O comportamento do servidor é controlado principalmente por essas variáveis de ambiente. Embora um arquivo ods_config.json também possa influenciar as configurações (veja Gerenciamento de Configuração), as variáveis de ambiente passadas pelo cliente MCP têm precedência.

Modo Servidor HTTP (FastMCP)

Além do transporte stdio padrão, o servidor pode expor um endpoint MCP sobre HTTP usando FastMCP. Isso é útil para clientes que se conectam via HTTP em vez de iniciar um subprocesso.

Iniciando o Servidor HTTP

python mcp_server.py --http

O servidor iniciará em 0.0.0.0:8000 por padrão e aceitará solicitações MCP em:

http://<host>:<port>/mcp

Todas as origens são permitidas (CORS totalmente aberto), então o endpoint é acessível de qualquer cliente ou ferramenta baseada em navegador.

Variáveis de Ambiente do Servidor HTTP

Variável	Descrição	Padrão
`MCP_HTTP_HOST`	Endereço do host para vincular	`0.0.0.0`
`MCP_HTTP_PORT`	Porta para escutar	`8000`

Exemplo — host e porta personalizados:

MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=9000 python mcp_server.py --http

Windows (Prompt de Comando):

set MCP_HTTP_HOST=127.0.0.1
set MCP_HTTP_PORT=9000
python mcp_server.py --http

Windows (PowerShell):

$env:MCP_HTTP_HOST="127.0.0.1"
$env:MCP_HTTP_PORT="9000"
python mcp_server.py --http

Conectando um Cliente MCP via HTTP

Aponte seu cliente MCP para o endpoint /mcp:

{
  "mcpServers": {
    "mcp-searxng-enhanced-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Nota: Todas as variáveis de configuração do servidor (SEARXNG_ENGINE_API_BASE_URL, DESIRED_TIMEZONE, etc.) se aplicam no modo HTTP exatamente como no modo stdio. O arquivo ods_config.json é gravado na inicialização antes que o servidor comece a aceitar conexões.

Executando Nativamente (Sem Docker)

Se você preferir executar o servidor diretamente usando Python sem Docker, siga estes passos:

1. Instalação do Python:

Este servidor requer Python 3.9 ou mais recente. Python 3.11 (como usado na imagem Docker) é recomendado.
Você pode baixar o Python em python.org.

2. Clonar o Repositório:

Obtenha o código do GitHub:

git clone https://github.com/OvertliDS/mcp-searxng-enhanced.git
cd mcp-searxng-enhanced

3. Criar e Ativar um Ambiente Virtual (Recomendado):

Usar um ambiente virtual ajuda a gerenciar dependências e evitar conflitos com outros projetos Python.

# For Linux/macOS
python3 -m venv .venv
source .venv/bin/activate

# For Windows (Command Prompt)
python -m venv .venv
.\.venv\Scripts\activate.bat

# For Windows (PowerShell)
python -m venv .venv
.\.venv\Scripts\Activate.ps1

4. Instalar Dependências:

Instale os pacotes Python necessários:
```
pip install -r requirements.txt
```
As principais dependências incluem httpx, BeautifulSoup4, pydantic, trafilatura, python-dateutil, cachetools, zoneinfo, filetype, pymupdf, pymupdf4llm e fastmcp.

5. Garantir que o SearXNG Esteja Acessível:

Você ainda precisa de uma instância SearXNG em execução. Certifique-se de ter a URL base da API (ex.: http://127.0.0.1:8080/search).

6. Definir Variáveis de Ambiente:

O servidor é configurado via variáveis de ambiente. No mínimo, você provavelmente precisará definir SEARXNG_ENGINE_API_BASE_URL.

Linux/macOS (bash/zsh):

export SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
export DESIRED_TIMEZONE="America/Los_Angeles"

Windows (Prompt de Comando):

set SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
set DESIRED_TIMEZONE="America/Los_Angeles"

Windows (PowerShell):

$env:SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
$env:DESIRED_TIMEZONE="America/Los_Angeles"

Consulte a tabela "Variáveis de Ambiente" abaixo para todas as opções disponíveis. Se não forem definidas, os padrões do script ou um arquivo ods_config.json (se presente no diretório raiz ou em ODS_CONFIG_PATH) serão usados.

7. Executar o Servidor:

Modo stdio (padrão — para clientes MCP que iniciam um subprocesso):
```
python mcp_server.py
```
O servidor escuta conexões de clientes MCP via stdin/stdout.
Modo HTTP (para clientes MCP que se conectam via HTTP):
```
python mcp_server.py --http
```
O servidor inicia um endpoint HTTP FastMCP em http://0.0.0.0:8000/mcp. Consulte Modo Servidor HTTP para opções de configuração.

8. Arquivo de Configuração (ods_config.json):

Alternativamente, ou em combinação com variáveis de ambiente, você pode criar um arquivo ods_config.json no diretório raiz do projeto (ou no caminho especificado pela variável de ambiente ODS_CONFIG_PATH). As variáveis de ambiente sempre terão precedência sobre os valores neste arquivo. Exemplo: json { "searxng_engine_api_base_url": "http://127.0.0.1:8080/search", "desired_timezone": "America/New_York" }

Variáveis de Ambiente

As seguintes variáveis de ambiente controlam o comportamento do servidor. Você pode defini-las na configuração do seu cliente MCP (recomendado para servidores gerenciados pelo cliente) ou ao executar o Docker manualmente.

Variável	Descrição	Padrão (do Dockerfile)	Observações
`SEARXNG_ENGINE_API_BASE_URL`	Endpoint de busca do SearXNG	`http://host.docker.internal:8080/search`	Crucial para a operação do servidor
`MCP_HTTP_HOST`	Endereço de bind para o modo servidor HTTP	`0.0.0.0`	Usado apenas ao iniciar com `--http`
`MCP_HTTP_PORT`	Porta para o modo servidor HTTP	`8000`	Usado apenas ao iniciar com `--http`
`DESIRED_TIMEZONE`	Fuso horário para a ferramenta de data/hora	`America/New_York`	Ex.: `America/Los_Angeles`. Lista de fusos horários do banco de dados tz: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
`ODS_CONFIG_PATH`	Caminho para o arquivo de configuração persistente	`/config/ods_config.json`	Normalmente mantido como padrão dentro do contêiner.
`RETURNED_SCRAPPED_PAGES_NO`	Máximo de páginas a retornar por busca	`3`
`SCRAPPED_PAGES_NO`	Máximo de páginas para tentar extrair	`5`
`PAGE_CONTENT_WORDS_LIMIT`	Máximo de palavras por página extraída	`5000`
`CITATION_LINKS`	Habilitar/desabilitar eventos de citação	`True`	`True` ou `False`
`MAX_IMAGE_RESULTS`	Máximo de resultados de imagens a retornar	`10`
`MAX_VIDEO_RESULTS`	Máximo de resultados de vídeos a retornar	`10`
`MAX_FILE_RESULTS`	Máximo de resultados de arquivos a retornar	`5`
`MAX_MAP_RESULTS`	Máximo de resultados de mapas a retornar	`5`
`MAX_SOCIAL_RESULTS`	Máximo de resultados de mídias sociais a retornar	`5`
`TRAFILATURA_TIMEOUT`	Tempo limite de extração de conteúdo (segundos)	`15`
`SCRAPING_TIMEOUT`	Tempo limite de requisição HTTP (segundos)	`20`
`CACHE_MAXSIZE`	Número máximo de sites em cache	`100`
`CACHE_TTL_MINUTES`	Tempo de vida do cache (minutos)	`5`
`CACHE_MAX_AGE_MINUTES`	Idade máxima para conteúdo em cache (minutos)	`30`
`RATE_LIMIT_REQUESTS_PER_MINUTE`	Máximo de requisições por domínio por minuto	`10`
`RATE_LIMIT_TIMEOUT_SECONDS`	Janela de rastreamento do limite de taxa (segundos)	`60`
`IGNORED_WEBSITES`	Lista separada por vírgulas de sites a ignorar	`""` (vazio)	Ex.: `"example.com,another.org"`

Gerenciamento de Configuração

O servidor utiliza uma abordagem de configuração em três camadas:

Padrões do script (codificados em Python)
Arquivo de configuração (carregado de ODS_CONFIG_PATH, padrão /config/ods_config.json)
Variáveis de ambiente (maior precedência)

O arquivo de configuração só é atualizado quando:

O arquivo ainda não existe (inicialização na primeira execução)
Variáveis de ambiente são fornecidas explicitamente para a execução atual

Isso garante que as configurações do usuário sejam preservadas entre reinicializações do contêiner quando nenhuma nova variável de ambiente for definida.

Ferramentas e Aliases

Nome da Ferramenta	Finalidade	Aliases
`search_web`	Busca na web via SearXNG	`search`, `web_search`, `find`, `lookup_web`, `search_online`, `access_internet`, `lookup`*
`get_website`	Extrair conteúdo de sites	`fetch_url`, `scrape_page`, `get`, `load_website`, `lookup`*
`get_current_datetime`	Data/hora atual	`current_time`, `get_time`, `current_date`

*lookup é sensível ao contexto:

Se chamado com um argumento url, ele mapeia para get_website
Caso contrário, ele mapeia para search_web

Exemplo: Chamando Ferramentas

Busca na Web

{ "name": "search_web", "arguments": { "query": "open source ai" } }

ou usando um alias:

{ "name": "search", "arguments": { "query": "open source ai" } }

Busca por Categoria Específica

{ "name": "search_web", "arguments": { "query": "landscapes", "category": "images" } }

Extração de Sites

{ "name": "get_website", "arguments": { "url": "example.com" } }

ou usando um alias:

{ "name": "lookup", "arguments": { "url": "example.com" } }

Data/Hora Atual

{ "name": "get_current_datetime", "arguments": {} }

ou:

{ "name": "current_time", "arguments": {} }

Recursos Avançados

Busca por Categoria Específica

A ferramenta search_web suporta diferentes categorias com saídas personalizadas:

images: Retorna URLs de imagens, títulos e páginas de origem com incorporação opcional em Markdown
videos: Retorna informações de vídeos, incluindo títulos, origem e URLs de incorporação
files: Retorna informações de arquivos para download, incluindo formato e tamanho
map: Retorna dados de localização, incluindo coordenadas e endereços
social media: Retorna postagens e perfis de plataformas sociais
general: Categoria padrão que extrai e retorna o conteúdo completo da página web

Conversão de URL do Reddit

Ao extrair conteúdo do Reddit, as URLs são convertidas automaticamente para usar o domínio old.reddit.com para melhor extração de conteúdo.

Limite de Taxa

O limite de taxa baseado em domínio evita requisições excessivas ao mesmo domínio dentro de uma janela de tempo. Isso evita sobrecarregar os sites de destino e possíveis bloqueios de IP.

Validação de Cache

O conteúdo de sites em cache é validado automaticamente quanto à atualidade com base na idade. Conteúdo desatualizado é atualizado automaticamente, enquanto conteúdo em cache válido é servido rapidamente.

Tratamento de Erros

O servidor implementa um sistema robusto de tratamento de erros com estes tipos de exceção:

MCPServerError: Classe de exceção base para todos os erros do servidor
ConfigurationError: Lançada quando valores de configuração são inválidos
SearXNGConnectionError: Lançada quando a conexão com o SearXNG falha
WebScrapingError: Lançada quando a extração da web falha
RateLimitExceededError: Lançada quando o limite de taxa para um domínio é excedido

Os erros são propagados adequadamente ao cliente com mensagens informativas.

Solução de Problemas

Não é possível conectar ao SearXNG: Certifique-se de que sua instância do SearXNG está em execução e que a variável de ambiente SEARXNG_ENGINE_API_BASE_URL aponta para o endpoint correto.
Erros de limite de taxa: Ajuste RATE_LIMIT_REQUESTS_PER_MINUTE se você estiver enfrentando muitos erros de limite de taxa.
Extração de conteúdo lenta: Aumente TRAFILATURA_TIMEOUT para permitir mais tempo para o processamento de conteúdo em páginas complexas.
Problemas de rede no Docker: Se estiver usando o Docker Desktop no Windows/Mac, host.docker.internal deve resolver para a máquina host. No Linux, talvez seja necessário usar o endereço IP do host.
Modo HTTP inacessível: Certifique-se de que nenhum firewall esteja bloqueando MCP_HTTP_PORT (padrão 8000). Defina MCP_HTTP_HOST=0.0.0.0 para vincular em todas as interfaces, ou 127.0.0.1 para restringir apenas ao localhost.
Erro de ID de sessão no modo HTTP: O servidor executa em modo HTTP sem estado — cada POST para /mcp é autocontido. Se o seu cliente exigir transporte baseado em sessão, alterne para o modo stdio.

Agradecimentos

Inspirado por:

SearXNG - Mecanismo de metabusca que respeita a privacidade
Trafilatura - Ferramenta de extração de texto da web
ihor-sokoliuk/mcp-searxng - Servidor MCP original para SearXNG
nnaoycurt (Better Web Search Tool)
@bwoodruff2021 (GetTimeDate Tool)