MCP-WebSearch-SearXNG

WebSearch SearXNG + Servidor MCP

Un metabuscador SearXNG autoalojado emparejado con el servidor MCP mcp-searxng, diseñado para LLMs, agentes y aplicaciones que usan herramientas. Permite que tu modelo (o agente autónomo) navegue por la web, ejecute búsquedas en muchos motores a la vez y muestre imágenes directamente en tu interfaz. Se ejecuta enteramente en tu propia máquina mediante Docker, se accede desde tu navegador y habla MCP sobre transporte HTTP Streamable, por lo que se conecta a cualquier cliente compatible con MCP (Claude Desktop, Cline, Open WebUI, LM Studio, marcos de agentes personalizados, etc.). Mejorado con búsqueda de imágenes/vídeos/categorías, paginación por desplazamiento y redimensionado inteligente de imágenes en base64 para modelos con capacidad de visión. Ambos servicios permanecen en tu red local, así que nada sale de tu equipo salvo que tú lo pidas. Sin anuncios, sin telemetría, sin rastreadores de terceros, sin cuentas — la interfaz de SearXNG es privada por diseño y los parches MCP no añaden ninguna comunicación de retorno propia.

Interfaz SearXNG — la interfaz de metabúsqueda que respeta la privacidad en localhost:8888. El mismo backend que el servidor MCP consulta internamente.

Cadena de herramientas autónoma — el modelo lanza varias llamadas searxng_web_search en paralelo y luego encadena con web_url_read para extraer el texto completo del artículo.

Extracción de texto limpio — el contenido de artículos extensos se obtiene con web_url_read, se elimina el material redundante y queda listo para que el modelo lo resuma.

Imagen integrada en el resumen de noticias — la imagen se obtiene y redimensiona mediante el pipeline sharp de web_url_read. Sin CDN externo, se sirve como bloque de imagen MCP en base64.

Búsqueda paralela con múltiples consultas — las consultas separadas por | lanzan varias llamadas searxng_web_search a la vez, aterrizando en el meme "It's Gonna Be May".

Bloques de imagen nativos — varias imágenes se devuelven integradas. El parámetro detail (low/medium/high) controla la calidad del redimensionado frente al coste en tokens.

Instalación

Nota rápida sobre privacidad antes de empezar. Esta pila se ejecuta enteramente en tu máquina y respeta la privacidad por diseño (sin telemetría, sin cuentas, sin rastreadores de terceros), pero los valores predeterminados están ajustados para "que funcione sin más", no para la máxima privacidad. Antes de exponerla más allá de tu propio ordenador, a tu LAN, a internet o a cualquier otra persona, lee ADVANCED.md

Requisitos previos

• Docker y Docker Compose deben estar instalados
• Node.js >= 20 debe estar instalado

Paso 1: Clonar el repositorio

git clone https://github.com/hypersniper05/MCP-WebSearch-SearXNG.git
cd MCP-WebSearch-SearXNG

Esto te da el docker-compose.yml, el settings.yml de SearXNG, los parches MCP y el Dockerfile personalizado ya dispuestos — así que el siguiente paso es ir directo a la configuración.

¿Prefieres configurarlo todo a mano en lugar de clonar? Consulta Construcción desde cero (sin clonar) en ADVANCED.md.

Paso 2: Configurar los ajustes de SearXNG

El searxng/config/settings.yml incluido ya está preconfigurado para esta pila — salida JSON habilitada, limitador de velocidad desactivado, reintentos rápidos de motores y un conjunto seleccionado de motores que funcionan (Bing, Mojeek, Yahoo, Startpage, etc.). Lo único que necesitas tocar aquí es el secret_key.

¿Quieres cambiar qué motores están habilitados, el tiempo de espera de las solicitudes o cualquier otro valor predeterminado de SearXNG? Consulta Modificación de los ajustes predeterminados en ADVANCED.md.

Establecer el secret_key (o usar la variable de entorno)

El settings.yml incluido tiene un marcador de posición secret_key: "CHANGE_ME_BEFORE_RUNNING". SearXNG se iniciará con el marcador de posición, así que para una instancia personal solo localhost puedes dejarlo y volver a esto más tarde. Pero si alguna vez te vinculas a 0.0.0.0, lo expones a tu LAN o lo compartes con alguien, genera uno real — de lo contrario, un atacante puede falsificar tokens de proxy de imágenes y CSRF contra tu instancia.

Dos formas de configurarlo (elige una):

Opción A — variable de entorno (recomendada):

Crea un archivo .env junto a docker-compose.yml:

SEARXNG_SECRET=<paste your generated 64-char hex string here>

La variable de entorno anula lo que haya en settings.yml, así que el marcador de posición puede permanecer en el archivo rastreado para siempre.

Opción B — editar settings.yml directamente:

Reemplaza el marcador de posición con tu clave generada. Si haces esto, asegúrate de no filtrar tu settings.yml.

Genera una clave con la herramienta que tengas instalada:

# PowerShell (Windows — built in)
[System.BitConverter]::ToString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).Replace('-','').ToLower()

# Node.js (already installed for the MCP server)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Docker (works anywhere this stack does)
docker run --rm alpine sh -c "apk add --no-cache openssl > /dev/null && openssl rand -hex 32"

# Git Bash / Linux / macOS
openssl rand -hex 32

# Python
python -c "import secrets; print(secrets.token_hex(32))"

Para el resto de las compensaciones de privacidad/endurecimiento (exposición a LAN, autenticación MCP, enrutamiento Tor), consulta ADVANCED.md.

Paso 3: Construir e iniciar todo

docker compose build
docker compose up -d

Paso 4: Verificar los servicios

Comprobación de estado:

curl -s http://localhost:3001/health

Esperado: {"status":"healthy","server":"ihor-sokoliuk/mcp-searxng","version":"0.9.2-enhanced","transport":"http"}

Búsqueda de prueba:

curl -s "http://localhost:8888/search?q=test&format=json" | head -c 200

Paso 5 (solo si accedes desde otra máquina): Abrir los enlaces a tu LAN / Tailscale

Por defecto, el docker-compose.yml incluido vincula los servicios a 127.0.0.1 — accesible solo desde la máquina que ejecuta Docker. Si quieres que otro dispositivo de tu LAN, tu tailnet de Tailscale o cualquier otro lugar fuera del host acceda a la interfaz de SearXNG o al endpoint MCP, tienes que cambiar los enlaces a 0.0.0.0.

Diagnóstico rápido para detectar esto:

docker compose ps

Mira la columna PUERTOS. Si ves:

Lo que ves	Lo que significa
0.0.0.0:8888->8080/tcp	Accesible desde cualquier lugar de la red ✓
127.0.0.1:8888->8080/tcp	Solo localhost — el síntoma exacto que hace que el acceso externo "se agote el tiempo"

Si ambas filas muestran 127.0.0.1: (o una sí y otra no, como SearXNG bloqueado mientras MCP está abierto), edita docker-compose.yml y cambia los enlaces:

services:
  searxng:
    ports:
      - "0.0.0.0:8888:8080"   # was 127.0.0.1:8888:8080

  mcp-searxng:
    ports:
      - "0.0.0.0:3001:3001"   # was 127.0.0.1:3001:3001

Luego se requiere un down + up completo (los cambios de puerto no se aplican con un simple restart):

docker compose down
docker compose up -d
docker compose ps

Ambas filas deberían mostrar ahora 0.0.0.0:....

Si docker compose ps ya muestra 0.0.0.0 y el acceso externo aún falla, es el cortafuegos del sistema operativo. En Windows, permite los puertos desde un PowerShell de administrador:

New-NetFirewallRule -DisplayName "MCP SearXNG (8888)" -Direction Inbound -Protocol TCP -LocalPort 8888 -Action Allow
New-NetFirewallRule -DisplayName "MCP Server (3001)"   -Direction Inbound -Protocol TCP -LocalPort 3001 -Action Allow

Nota de seguridad: cambiar a 0.0.0.0 expone los servicios a cualquiera que pueda alcanzar tu máquina en esos puertos. El servidor MCP no tiene autenticación. Si vas más allá de una red doméstica/Tailscale de confianza, lee ADVANCED.md → Nivel 2 para añadir un proxy inverso con autenticación.

Resumen de endpoints

Servicio	URL	Propósito
Interfaz SearXNG	http://localhost:8888	Interfaz de búsqueda web
API SearXNG	http://localhost:8888/search	API de búsqueda JSON
Servidor MCP	http://localhost:3001/mcp	HTTP Streamable MCP
Estado MCP	http://localhost:3001/health	Endpoint de comprobación de estado

¿Necesitas TLS para un cliente solo HTTPS? El camino más limpio es Tailscale Serve si ambos extremos están en un tailnet (certificado real de confianza de Let's Encrypt, cero configuración por cliente), o un proxy inverso como Caddy / nginx con tu propio certificado en caso contrario. Cualquiera de los dos se añade delante del endpoint MCP HTTP existente sin ningún cambio en esta pila.

Herramientas MCP

1. searxng_web_search

Búsqueda web con soporte de categoría, paginación y filtrado.

Parámetro	Tipo	Descripción
query	string	Consulta de búsqueda (obligatorio)
categories	string	general, images, videos, news, music, files, it, science, social media, map
max_results	number	Resultados por lote (predeterminado: 20 generales, 10 imágenes/vídeos)
offset	number	Omitir N resultados para paginación (p. ej., 10 para resultados 11-20)
pageno	number	Número de página de SearXNG
time_range	string	day, month, year
language	string	Código de idioma (p. ej., en, fr)
safesearch	number	0 (ninguno), 1 (moderado), 2 (estricto)

2. web_url_read

Obtiene y lee URLs. Detecta automáticamente URLs de imágenes y devuelve bloques de imagen en base64 redimensionados.

Parámetro	Tipo	Descripción
url	string	URL a leer (obligatorio)
detail	string	Nivel de redimensionado de imagen: low (448px, ~256 tokens), medium (768px, ~756 tokens, predeterminado), high (1280px, ~2048 tokens)
startChar	number	Desplazamiento de caracteres para paginación de texto
maxLength	number	Máximo de caracteres a devolver
section	string	Extraer contenido bajo un encabezado
paragraphRange	string	Rango de párrafos (p. ej., 1-5)
readHeadings	boolean	Devolver solo encabezados

Flujo de búsqueda de imágenes

1. searxng_web_search({query: "sunset", categories: "images"}) → devuelve URLs de imágenes + metadatos
2. Elige una imagen → web_url_read({url: "https://example.com/sunset.jpg", detail: "medium"}) → devuelve imagen en base64 redimensionada
3. Para ver más resultados → searxng_web_search({query: "sunset", categories: "images", offset: 10}) → resultados 11-20

Archivos de parche personalizados

Todos los parches están en mcp-searxng-patches/ y se montan de solo lectura en el contenedor:

Archivo	Propósito
Dockerfile	Extiende la imagen base con sharp para redimensionado de imágenes
types.js	Esquemas de herramientas con parámetros categories, offset, max_results, detail
search.js	Formato de búsqueda consciente de categorías, paginación por desplazamiento, campos de resultados de imágenes/vídeos
url-reader.js	fetchImage() con redimensionado sharp (3 ajustes de detalle), bloques de imagen MCP en base64
index.js	Cableado de manejadores de herramientas, detección de URLs de imágenes, paso de detalle

Actualizar SearXNG

SearXNG está fijado a :latest en docker-compose.yml, así que las actualizaciones son tirar y reiniciar. La configuración en searxng/config/settings.yml está montada por volumen y sobrevive a la actualización.

Actualización manual (recomendada)

cd MCP-WebSearch-SearXNG
docker compose pull searxng        # grab newest :latest image
docker compose up -d searxng       # recreate container with new image
docker compose logs searxng --tail 100   # check for config-schema warnings
docker image prune -f              # remove the old image

Las versiones principales ocasionalmente renombran claves en settings.yml o añaden campos obligatorios. Consulta la página de versiones de SearXNG para ver cambios importantes antes de actualizar.

Fijar a una versión específica (más seguro / reproducible)

Reemplace :latest en docker-compose.yml con una versión etiquetada por fecha, p. ej.:

image: docker.io/searxng/searxng:2026.4.15-abc1234

Las actualizaciones se convierten entonces en una edición explícita: revise las notas de la versión, actualice la etiqueta, docker compose up -d.

Actualizaciones automáticas

Opción	Ventajas	Desventajas
Contenedor Watchtower	Configurar y olvidar	Ruptura silenciosa ante cambios en el esquema de configuración
docker compose pull && up -d programado (Programador de tareas o agente /schedule)	Usted controla la cadencia	Mismo riesgo de ruptura de esquema
Notificaciones de versiones de GitHub + actualización manual	Más seguro	Más lento

Un punto intermedio razonable: programar un trabajo semanal que ejecute docker compose pull e informe si hay una nueva imagen disponible, pero que no la aplique automáticamente.

Actualización del servidor MCP

mcp-searxng se compila localmente desde mcp-searxng-patches/Dockerfile (base: isokoliuk/mcp-searxng:latest) con parches JS personalizados montados encima. Para incorporar cambios MCP ascendentes:

1. docker compose build --pull mcp-searxng — reconstruye desde una imagen base recién extraída
2. docker compose up -d mcp-searxng — recrea el contenedor
3. Verifique que los parches en mcp-searxng-patches/*.js sigan aplicándose limpiamente ante cualquier cambio de API ascendente (consulte docker compose logs mcp-searxng para ver errores)

Si el proyecto ascendente renombra módulos internos o cambia las firmas de las funciones, los parches JS montados por volumen pueden necesitar una re-base manual.

Probado con

• Qwen3.6 35B A3B — ejecuta de forma fiable tanto searxng_web_search (incluidos filtros de múltiples consultas y categorías) como web_url_read (modos de texto e imagen). La selección de herramientas, la inferencia de parámetros y la interpretación de resultados funcionan bien con este modelo.

Notas

• El servidor MCP utiliza transporte HTTP Streamable (no solo stdio o SSE)
• SearXNG se conecta internamente mediante el nombre de host de Docker searxng:8080
• Todos los datos permanecen locales: no se necesitan claves de API externas
• Los parches personalizados tienen licencia MIT, están auditados, sin acceso a sistema de archivos/shell, sin telemetría
• Motores de búsqueda: Bing, Startpage, Mojeek, Yahoo activos; Google con interfaz móvil (puede bloquear intermitentemente)