SearXNG MCP Server

Um servidor de busca web que respeita a privacidade para agentes de IA, alimentado pelo mecanismo de metabusca SearXNG.

GitHub
24
Experimente este MCPPatrocinado

Documentação

Servidor MCP SearXNG

Uma implementação MCP sse do servidor Model Context Protocol (MCP) integrado ao SearXNG para fornecer aos agentes de IA poderosos recursos de busca que respeitam a privacidade.

Visão Geral

Este projeto demonstra como construir um servidor MCP que permite que agentes de IA realizem buscas na web usando uma instância do SearXNG. Ele serve como um modelo prático para criar seus próprios servidores MCP, usando o SearXNG como backend.

A implementação segue as melhores práticas estabelecidas pela Anthropic para a construção de servidores MCP, permitindo integração perfeita com qualquer cliente compatível com MCP.

Pré-requisitos

  • Python 3.9+
  • Acesso a uma instância do SearXNG em execução (local ou remota)
  • Docker (opcional, para implantação em contêiner)
  • uv (opcional, para gerenciamento rápido de dependências Python)
  • Smithery (opcional, para gerenciamento de servidores MCP)

Servidor SearXNG (Obrigatório)

Você deve ter um servidor SearXNG em execução e acessível. A forma recomendada é via Docker:

docker run -d --name=searxng -p 32768:8080 -v "/root/searxng:/etc/searxng" \
  -e "BASE_URL=http://0.0.0.0:32768/" \
  -e "INSTANCE_NAME=home" \
  --restart always searxng/searxng
  • Isso executará o SearXNG na porta 32768 e persistirá a configuração em /root/searxng.
  • O servidor MCP espera que o SearXNG esteja disponível em http://172.17.0.1:32768 por padrão (veja .env).

Instalação

Usando uv

Instale o uv se você não o tiver:

pip install uv

Clone este repositório:

git clone https://github.com/The-AI-Workshops/searxng-mcp-server.git
cd searxng-mcp-server/dev/searXNG-mcp

Instale as dependências:

uv pip install -r requirements.txt

Crie um arquivo .env com base no exemplo fornecido:

nano .env
# Edit .env as needed

Configure suas variáveis de ambiente no arquivo .env (veja a seção Configuração).

Usando Docker (Recomendado)

Construa a imagem Docker:

docker build -t mcp/searxng-mcp .

Crie um arquivo .env e configure suas variáveis de ambiente.

Execute a imagem Docker:

docker run -d --env-file ./.env -p 32769:32769 mcp/searxng-mcp

Usando Smithery

Smithery é uma ferramenta de linha de comando para gerenciar ferramentas de agentes de IA e servidores MCP.

Instale o Smithery se você não o tiver (veja a documentação do Smithery para vários métodos de instalação, por exemplo, usando pipx):

pipx install smithery

Instale o servidor MCP SearXNG usando o Smithery:

smithery install @The-AI-Workshops/searxng-mcp-server

Isso instalará o servidor e suas dependências em um ambiente dedicado gerenciado pelo Smithery.

Após a instalação, o Smithery fornecerá o caminho para o servidor instalado. Você precisará navegar até este diretório para configurá-lo. Por exemplo, se o Smithery instala ferramentas em ~/.smithery/tools/, o caminho pode ser ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server.

Crie um arquivo .env no diretório do servidor copiando o exemplo:

# Example:
# cd ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server
cp .env.example .env
nano .env
# Edit .env as needed

Configure suas variáveis de ambiente no arquivo .env (veja a seção Configuração).

Configuração

As seguintes variáveis de ambiente podem ser configuradas no seu arquivo .env:

VariávelDescriçãoExemplo
SEARXNG_BASE_URLURL base da sua instância SearXNGhttp://172.17.0.1:32768
HOSTHost para vincular ao usar transporte SSE0.0.0.0
PORTPorta para escutar ao usar transporte SSE32769
TRANSPORTProtocolo de transporte (sse ou stdio)sse

Executando o Servidor

Usando uv

Transporte SSE

Defina TRANSPORT=sse em .env e então:

uv run dev/searXNG-mcp/server.py

Transporte Stdio

Com stdio, o próprio cliente MCP pode iniciar o servidor MCP, então não há nada para executar neste momento.

Usando Docker

Transporte SSE

docker build -t mcp/searxng-mcp .
docker run --rm -it -p 32769:32769 --env-file dev/searXNG-mcp/.env -v $(pwd)/dev/searXNG-mcp:/app mcp/searxng-mcp
  • A montagem -v $(pwd)/dev/searXNG-mcp:/app permite que você edite ao vivo o código e o arquivo .env no seu host e tenha as alterações refletidas no contêiner em execução.
  • O servidor estará disponível em http://localhost:32769/sse.

Transporte Stdio

Com stdio, o próprio cliente MCP pode iniciar o contêiner do servidor MCP, então não há nada para executar neste momento.

Executando com Smithery

Transporte SSE

Defina TRANSPORT=sse em .env no diretório do servidor instalado pelo Smithery. Então, você pode normalmente executar o servidor usando o interpretador Python do ambiente virtual que o Smithery criou para a ferramenta:

# Navigate to the server directory, e.g.,
# cd ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server
~/.smithery/venvs/The-AI-Workshops_searxng-mcp-server/bin/python server.py

Alternativamente, se o Smithery fornecer um comando de execução direta para ferramentas instaladas (verifique a documentação do Smithery):

smithery run @The-AI-Workshops/searxng-mcp-server

O servidor estará disponível com base nas suas configurações de HOST e PORT em .env (por exemplo, http://localhost:32769/sse).

Transporte Stdio

Com stdio, o próprio cliente MCP iniciará o servidor. A configuração do cliente precisará apontar para o script server.py dentro do diretório gerenciado pelo Smithery, potencialmente usando smithery exec ou o caminho direto para o interpretador Python no ambiente virtual da ferramenta. Veja a seção "Integração com Clientes MCP" para exemplos.

Integração com Clientes MCP

Configuração SSE

Uma vez que o servidor esteja em execução com transporte SSE, você pode se conectar a ele usando esta configuração:

{
  "mcpServers": {
    "searxng": {
      "transport": "sse",
      "url": "http://localhost:32769/sse"
    }
  }
}

Nota para usuários do Windsurf: Use serverUrl em vez de url na sua configuração:

{
  "mcpServers": {
    "searxng": {
      "transport": "sse",
      "serverUrl": "http://localhost:32769/sse"
    }
  }
}

Nota para usuários do n8n: Use host.docker.internal em vez de localhost já que o n8n precisa alcançar fora do seu próprio contêiner até a máquina host:

Então a URL completa no nó MCP seria: http://host.docker.internal:32769/sse

Certifique-se de atualizar a porta se estiver usando um valor diferente do padrão 32769.

Python com Configuração Stdio

Adicione este servidor à sua configuração MCP para Claude Desktop, Windsurf ou qualquer outro cliente MCP:

{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["dev/searXNG-mcp/server.py"],
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://localhost:32768",
        "HOST": "0.0.0.0",
        "PORT": "32769"
      }
    }
  }
}

Docker com Configuração Stdio

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "TRANSPORT",
               "-e", "SEARXNG_BASE_URL",
               "-e", "HOST",
               "-e", "PORT",
               "mcp/searxng-mcp"],
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://localhost:32768",
        "HOST": "0.0.0.0",
        "PORT": "32769"
      }
    }
  }
}

Smithery com Configuração Stdio

Se você instalou o servidor usando o Smithery, pode configurar seu cliente MCP para executá-lo via stdio. O Smithery fornece um comando exec para executar executáveis de dentro do ambiente da ferramenta.

{
  "mcpServers": {
    "searxng": {
      "command": "smithery",
      "args": ["exec", "@The-AI-Workshops/searxng-mcp-server", "--", "python", "server.py"],
      // "cwd" (current working directory) might be automatically handled by Smithery.
      // If server.py is in a subdirectory, adjust the python script path e.g., "python", "path/to/server.py"
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://localhost:32768", // Adjust as needed
        "HOST": "0.0.0.0", // Typically not used by stdio server itself but good to set
        "PORT": "32769"  // Typically not used by stdio server itself
      }
    }
  }
}

Alternativamente, você pode encontrar o caminho para o interpretador Python no ambiente virtual criado pelo Smithery (por exemplo, ~/.smithery/venvs/The-AI-Workshops_searxng-mcp-server/bin/python) e o caminho para server.py (por exemplo, ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server/server.py) e usá-los diretamente:

{
  "mcpServers": {
    "searxng": {
      "command": "~/.smithery/venvs/The-AI-Workshops_searxng-mcp-server/bin/python",
      "args": ["~/.smithery/tools/The-AI-Workshops/searxng-mcp-server/server.py"],
      // "cwd" should be the directory containing server.py if not using absolute paths for args,
      // or if server.py relies on relative paths for other files (like .env).
      // Example: "cwd": "~/.smithery/tools/The-AI-Workshops/searxng-mcp-server",
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://localhost:32768"
        // Other necessary env vars from .env can be duplicated here
      }
    }
  }
}

Certifique-se de que os caminhos estejam corretos para sua instalação do Smithery e que o arquivo .env seja detectável por server.py (geralmente definindo cwd para o diretório raiz do servidor ou garantindo que server.py o carregue de um caminho absoluto se o Smithery definir um).

Construindo Seu Próprio Servidor

Este modelo fornece uma base para construir servidores MCP mais complexos. Para construir o seu próprio:

  • Adicione suas próprias ferramentas criando métodos com o decorador @mcp.tool()
  • Crie sua própria função de ciclo de vida para adicionar suas próprias dependências (clientes, conexões de banco de dados, etc.)
  • Adicione também prompts e recursos com @mcp.resource() e @mcp.prompt()

Parâmetros da Ferramenta de Busca SearXNG

A ferramenta search suporta os seguintes parâmetros (todos opcionais, exceto q):

  • q (obrigatório): A string de consulta de busca.
  • categories: Lista separada por vírgulas de categorias de busca ativas.
  • engines: Lista separada por vírgulas de mecanismos de busca ativos.
  • language: Código do idioma.
  • page: Número da página de busca (padrão: 1).
  • time_range: [dia, mês, ano]
  • format: [json, csv, rss] (padrão: json)
  • results_on_new_tab: [0, 1]
  • image_proxy: [true, false]
  • autocomplete: [google, dbpedia, duckduckgo, mwmbl, startpage, wikipedia, stract, swisscows, qwant]
  • safesearch: [0, 1, 2]
  • theme: [simple]
  • enabled_plugins: Lista de plugins habilitados.
  • disabled_plugins: Lista de plugins desabilitados.
  • enabled_engines: Lista de mecanismos habilitados.
  • disabled_engines: Lista de mecanismos desabilitados.

Veja a documentação do SearXNG para mais detalhes.

Licença

Licença MIT