SearXNG

Início Rápido

Você precisa de uma instância SearXNG existente com busca JSON habilitada. Este projeto conecta um cliente MCP ao SearXNG; ele não instala o SearXNG. Use uma instância que você opera ou confia. Comece com o guia de auto-hospedagem ou de instância pública, se necessário.

Escolha como conectar:

Para clientes que usam JSON mcpServers (como Claude Desktop), adicione:

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": { "SEARXNG_URL": "https://search.example.com" }
    }
  }
}

Substitua a URL de exemplo pela URL base do seu SearXNG. Outros clientes usam formatos de configuração diferentes: escolha a receita do seu cliente. Deixe MCP_HTTP_PORT não definido para STDIO local. O Docker também precisa de encaminhamento de variáveis de ambiente para o contêiner.

Recarregue o cliente, inspecione o inventário de ferramentas MCP e peça para buscar a documentação do SearXNG. Uma chamada de ferramenta simples é searxng_web_search com {"query":"SearXNG"}. A descoberta sozinha não testa a conectividade com o SearXNG. Se a chamada falhar, comece com solução de problemas.

Recursos

• Busca com paginação, filtros, respostas diretas e saída de texto/JSON completa ou compacta.
• Leia HTML, texto estruturado e texto PDF limitado; inspecione cabeçalhos ou seções selecionadas.
• Descubra as capacidades da instância e obtenha sugestões de consulta.
• Failover/fan-out de réplica opcional, fallback de HTML, cache, proxies e solucionadores de navegador.
• STDIO local ou HTTP Streamable, com bearer estático e proteção OAuth opcional.

Consulte o guia de ferramentas para capacidades e limites, a referência de configuração para configurações e as medições históricas de implantação para evidências limitadas de planejamento de recursos.

Por que mcp-searxng?

A privacidade depende da implantação do SearXNG. Uma instância controlada pelo operador pode evitar confiar em um operador de busca terceirizado, enquanto uma instância pública recebe a consulta e pode registrá-la. O SearXNG e esta integração MCP não fornecem anonimato por si só.

Como Funciona

MCP client → mcp-searxng → SearXNG → search engines

O cliente inicia seu próprio processo STDIO ou se conecta a um serviço HTTP. SEARXNG_URL identifica o serviço SearXNG, não o endpoint MCP. A leitura de URL busca o site selecionado diretamente. Uma lista de réplicas separada por ponto e vírgula é suportada para implantações SearXNG intercambiáveis; consulte a configuração de réplicas.

STDIO é o padrão. As sessões HTTP Streamable legadas são stateful por padrão: os clientes devem enviar DELETE /mcp quando terminarem e reinicializar se uma solicitação posterior receber HTTP 404 para a sessão encerrada. Solicitações HTTP modernas e o modo legado MCP_HTTP_STATELESS=true são sem sessão; consulte a configuração de transporte HTTP.

Ferramentas

O guia de ferramentas contém exemplos e a referência completa de parâmetros. O fluxo de trabalho de pesquisa opcional explica como inspecionar fontes e citar evidências.

Instalação

Para instalações NPX e npm, o Node.js 22 ou posterior é necessário. A imagem Docker inclui seu runtime Node.js.

npm install -g mcp-searxng

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

docker pull isokoliuk/mcp-searxng:latest

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARXNG_URL",
        "isokoliuk/mcp-searxng:latest"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

docker build -t mcp-searxng:latest -f Dockerfile .

services:
  mcp-searxng:
    image: isokoliuk/mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=${SEARXNG_URL:?Set SEARXNG_URL in the environment}
      # Add optional variables as needed — see CONFIGURATION.md

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/absolute/path/to/docker-compose.yml",
        "run", "--rm", "-T", "mcp-searxng"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

services:
  mcp-searxng:
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - MCP_HTTP_PORT=8080
      - MCP_HTTP_HOST=0.0.0.0

Transporte HTTP

Execute HTTP independentemente e conecte o cliente. Consulte o guia do servidor HTTP para verificações locais, autenticação bearer estática, requisitos de OAuth e verificação de implantação.

Configuração

Para a configuração local padrão, SEARXNG_URL é a configuração necessária. Modos opcionais, como HTTP endurecido e OAuth, têm requisitos complementares. Use a referência de configuração para variáveis de ambiente, padrões, cache, tempos limite, proxies, TLS e limites.

OAuth MCP opcional

Uma implantação HTTP pode usar OAuth com um provedor de autorização externo. Consulte opções de autenticação. A autenticação bearer estática e a Autenticação Básica do SearXNG protegem conexões diferentes.

Solução de Problemas

403 Proibido do SearXNG

A saída JSON pode estar desabilitada, ou uma camada de controle de acesso pode ter negado a solicitação. Siga as verificações diretas antes de alterar as configurações. Uma página de navegador funcional não prova que a API JSON funciona.

Não consegue habilitar JSON? (fallback de HTML)

SEARXNG_HTML_FALLBACK=true pode tentar novamente respostas de busca 403/404/não-JSON como HTML. A análise é de melhor esforço e os metadados são limitados; a saída compacta omite marcadores de fallback. Leia as orientações de instância pública antes de habilitá-lo em um serviço que você não controla.

Para um relatório de bug, colete uma reprodução mínima e erros relevantes.

Documentação

Configure a busca para cobertura útil com configurações upstream testadas, rotas de mecanismos especializados e controles de saída MCP. A receita de implantação inclui uma pilha Compose privada e provedores de navegador opcionais, com resultados datados e falhas conhecidas.

Encontre um guia por tarefa. Esses links abrem a documentação atual do branch principal. Comportamento não lançado é rotulado; consulte a tag Git correspondente ao investigar uma versão mais antiga.

Contribuindo

Consulte CONTRIBUTING.md.

Licença

MIT — consulte LICENSE para detalhes.