Servidor MCP de SearXNG

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona capacidades de búsqueda web mediante la integración con una instancia de SearXNG.

Características

• Búsqueda web: Realiza potentes búsquedas agregadas a través de múltiples motores.

• Descubrimiento: Recupera mediante programación las categorías y motores disponibles.

• HTTP sin estado: Compatible con cualquier cliente JSON-RPC estándar.

• Configuración flexible: Admite variables de entorno y argumentos de línea de comandos.

Ejemplo de compose.yml para ejecutar SearXNG con el servidor MCP

services:
  searxng:
    image: searxng/searxng:latest
    ports:
      - 8080:8080
    volumes:
      - ./searxng/etc/:/etc/searxng/
      - ./searxng/data/:/var/cache/searxng/
    restart: always

  searxng-mcp:
    image: ghcr.io/aicrafted/searxng-mcp:latest
    restart: unless-stopped
    depends_on:
      # Ensure SearXNG starts before the MCP server
      - searxng
    environment:
      SEARXNG_URL: http://searxng:8080
      MCP_HOST: 0.0.0.0
      MCP_PORT: 32123
      MCP_TRANSPORT: "http"
    ports:
      - "32123:32123"

Configuración del cliente MCP

Transporte HTTP (recomendado)

{
  "mcpServers": {
    "searxng": {
      "type": "http",
      "url": "http://localhost:32123/mcp"
    }
  }
}

Transporte SSE

{
  "mcpServers": {
    "searxng": {
      "type": "sse",
      "url": "http://localhost:32123/sse"
    }
  }
}

Nota: El transporte SSE utiliza el endpoint /sse, no /mcp. El transporte HTTP utiliza /mcp.

Requisitos previos para ejecutar desde el código fuente

• Python 3.10+

• Una instancia de SearXNG en ejecución.

Instalación

1. Clona el repositorio y navega al directorio.

2. Instala las dependencias:

   pip install -r requirements.txt

3. Configura tu archivo .env (opcional):

   SEARXNG_URL=http://your-searxng-instance:8080
   MCP_PORT=32123
   MCP_HOST=127.0.0.1

Uso

Ejecuta el servidor usando uv o python estándar:

python searxng_mcp.py --transport http --port 32123 --searxng http://searx.lan

Ejecutar con Docker

1. Construye la imagen:

   docker build -t searxng-mcp .

2. Ejecuta el contenedor:

   docker run -d \
     -p 32123:32123 \
     -e SEARXNG_URL=http://your-searxng-instance:8080 \
     --name searxng-mcp \
     searxng-mcp

Opciones de transporte

• stdio: Entrada/salida estándar (predeterminado para algunos clientes MCP).

• http: HTTP sin estado (streamable-http).

• sse: Eventos enviados por el servidor (Server-Sent Events).

Guía de capacidades de búsqueda

SearXNG agrega resultados de diversas fuentes. Esta guía describe las capacidades disponibles a través de la herramienta web_search.

Categorías de búsqueda

Las categorías ayudan a refinar tu búsqueda por tipo de contenido. Úsalas en el parámetro categories (separadas por comas).

Motores compatibles

SearXNG puede consultar más de 130 motores. Los motores configurados suelen incluir:

• Web: Google, Brave, DuckDuckGo, Qwant, Startpage

• Conocimiento: Wikipedia, Wikidata

• Desarrollo: GitHub, StackOverflow, PyPI

• Social: Reddit, Twitter/X

Parámetros de búsqueda avanzada

• categories: Filtrar por tipos específicos (ej. news,it).

• engines: Forzar motores específicos (ej. google,wikipedia).

• language: Especificar el idioma de búsqueda (ej. en, es, fr).

• pageno: Navegar a través de múltiples páginas de resultados.

• time_range: Filtrar por fecha (day, month, year).

• safesearch: Controlar el filtrado de contenido (0=Ninguno, 1=Moderado, 2=Estricto).

Descubrimiento programático

Usa la herramienta web_search_info para recuperar dinámicamente la lista de categorías y motores habilitados desde tu instancia.

Solución de problemas en Windows

localhost no es accesible mientras el contenedor Docker está en ejecución

Síntoma: http://localhost:<port>/ devuelve conexión rechazada o llega al servicio incorrecto, pero curl desde dentro del contenedor funciona correctamente.

Causa raíz: Fantasma de retransmisión de puertos de WSL2

WSL2 reenvía automáticamente los puertos de la máquina virtual Linux al host de Windows usando wslrelay.exe. Cuando un proceso dentro de WSL escucha en un puerto, WSL crea un relé vinculado a [::1]:<port> (bucle invertido IPv6) en el lado de Windows.

Cuando ese proceso de WSL se detiene, wslrelay.exe a menudo no libera el puerto. La entrada del relé permanece activa como un oyente zombi en [::1]:<port>.

Más tarde, cuando Docker asigna un contenedor al mismo puerto del host, se vincula correctamente a 0.0.0.0:<port> — pero [::1]:<port> ya está ocupado por el relé obsoleto.

En Windows, localhost se resuelve primero a ::1 (IPv6). Por lo tanto, las solicitudes del navegador y curl a localhost:<port> llegan a la entrada wslrelay.exe muerta en lugar del contenedor Docker, lo que resulta en un error de conexión o una respuesta inesperada.

Conectarse a través de la dirección IPv4 explícita 127.0.0.1:<port> evita el relé y llega a Docker correctamente.

Cómo diagnosticar:

# Check what is listening on the port
netstat -ano | findstr :<port>

# Identify the processes
Get-Process -Id <pid1>,<pid2> | Select-Object Id,Name

Si ves dos entradas para el mismo puerto — una propiedad de com.docker.backend y otra de wslrelay — este es el problema.

Soluciones alternativas:

Solución permanente:

Después de wsl --shutdown, reinicia el contenedor Docker. El relé ya no existirá y localhost:<port> funcionará normalmente hasta que el mismo puerto se vuelva a usar dentro de WSL.

Prevención:

Si ejecutas servicios regularmente en el mismo puerto tanto en WSL como en Docker, prefiere una de estas opciones:

• Usa siempre Docker para ese servicio, nunca WSL directamente

• Usa puertos diferentes para instancias de desarrollo en WSL y producción en Docker

• Agrega una vinculación explícita 127.0.0.1:<port>:<port> en docker-compose.yml para forzar IPv4

Relacionado

• Documentación de redes de WSL2

• Rastreador de problemas de WSL en GitHub: busca wslrelay port leak