SearXNG

Inicio rápido

Necesitas una instancia de SearXNG existente con búsqueda JSON habilitada. Este proyecto conecta un cliente MCP a SearXNG; no instala SearXNG. Usa una instancia que operes o en la que confíes. Comienza con la guía de autoalojamiento o de instancia pública si es necesario.

Elige cómo conectarte:

Para clientes que usan JSON de mcpServers (como Claude Desktop), agrega:

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

Reemplaza la URL de ejemplo con la URL base de tu SearXNG. Otros clientes usan diferentes formas de configuración: elige la receta de tu cliente. Deja MCP_HTTP_PORT sin configurar para STDIO local. Docker también necesita reenvío de variables de entorno hacia el contenedor.

Recarga el cliente, inspecciona su inventario de herramientas MCP y luego pídele que busque documentación de SearXNG. Una llamada de herramienta simple es searxng_web_search con {"query":"SearXNG"}. El descubrimiento por sí solo no prueba la conectividad con SearXNG. Si la llamada falla, comienza con solución de problemas.

Características

• Búsqueda con paginación, filtros, respuestas directas y salida de texto/JSON completa o compacta.
• Lectura de HTML, texto estructurado y texto PDF acotado; inspección de encabezados o secciones seleccionadas.
• Descubrimiento de capacidades de la instancia y obtención de sugerencias de consulta.
• Conmutación por error/fan-out de réplicas opcional, respaldo HTML, caché, proxies y solucionadores de navegador.
• STDIO local o HTTP Streamable, con portador estático y protección OAuth opcional.

Consulta la guía de herramientas para capacidades y límites, la referencia de configuración para ajustes, y las mediciones históricas de despliegue para evidencia acotada de planificación de recursos.

¿Por qué mcp-searxng?

La privacidad depende del despliegue de SearXNG. Una instancia controlada por el operador puede evitar confiar en un operador de búsqueda de terceros, mientras que una instancia pública recibe la consulta y puede registrarla. SearXNG y esta integración MCP no proporcionan anonimato por sí mismos.

Cómo funciona

MCP client → mcp-searxng → SearXNG → search engines

El cliente inicia su propio proceso STDIO o se conecta a un servicio HTTP. SEARXNG_URL identifica el servicio SearXNG, no el endpoint MCP. La lectura de URL obtiene el sitio web seleccionado directamente. Se admite una lista de réplicas separada por puntos y comas para despliegues intercambiables de SearXNG; consulta configuración de réplicas.

STDIO es el valor predeterminado. Las sesiones HTTP Streamable heredadas son con estado por defecto: los clientes deben enviar DELETE /mcp al terminar y luego reinicializar si una solicitud posterior recibe HTTP 404 para la sesión terminada. Las solicitudes HTTP modernas y el modo heredado MCP_HTTP_STATELESS=true no tienen sesión; consulta configuración del transporte HTTP.

Herramientas

La guía de herramientas contiene ejemplos y la referencia completa de parámetros. El flujo de trabajo de investigación opcional explica cómo inspeccionar fuentes y citar evidencia.

Instalación

Para instalaciones NPX y npm, se requiere Node.js 22 o posterior. La imagen Docker incluye su propio runtime de 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

Ejecuta HTTP de forma independiente y luego conecta el cliente. Consulta la guía del servidor HTTP para verificaciones locales, autenticación de portador estática, requisitos de OAuth y verificación de despliegue.

Configuración

Para la configuración local predeterminada, SEARXNG_URL es el ajuste requerido. Los modos opcionales como HTTP reforzado y OAuth tienen requisitos complementarios. Usa la referencia de configuración para variables de entorno, valores predeterminados, caché, tiempos de espera, proxies, TLS y límites.

OAuth MCP opcional

Un despliegue HTTP puede usar OAuth con un proveedor de autorización externo. Consulta opciones de autenticación. La autenticación de portador estática y la autenticación básica de SearXNG protegen conexiones diferentes.

Solución de problemas

403 Prohibido de SearXNG

La salida JSON puede estar deshabilitada, o una capa de control de acceso puede haber denegado la solicitud. Sigue las verificaciones directas antes de cambiar la configuración. Una página de navegador funcional no prueba que la API JSON funcione.

¿No puedes habilitar JSON? (respaldo HTML)

SEARXNG_HTML_FALLBACK=true puede reintentar respuestas de búsqueda 403/404/no JSON como HTML. El análisis es de mejor esfuerzo y los metadatos son limitados; la salida compacta omite los marcadores de respaldo. Lee la guía de instancia pública antes de habilitarlo en un servicio que no controlas.

Para un informe de error, recopila una reproducción mínima y los errores relevantes.

Documentación

Configura la búsqueda para una cobertura útil con ajustes ascendentes probados, rutas de motores especializados y controles de salida MCP. La receta de despliegue incluye una pila Compose privada y proveedores de navegador opcionales, con resultados fechados y fallos conocidos.

Encuentra una guía por tarea. Estos enlaces abren la documentación actual de la rama principal. El comportamiento no publicado está etiquetado; consulta la etiqueta Git correspondiente al investigar una versión anterior.

Contribuciones

Consulta CONTRIBUTING.md.

Licencia

MIT — consulta LICENSE para detalles.