MCP-SearXNG-Enhanced Web Search

Un servidor MCP mejorado para la búsqueda web de SearXNG, que utiliza una búsqueda web consciente de categorías, extracción de contenido web e incluye una herramienta de recuperación de fecha/hora.

GitHub

Prueba este MCPPatrocinado

Documentación

MCP SearXNG Enhanced Server

Un servidor de Model Context Protocol (MCP) para búsqueda web por categorías, extracción de contenido de sitios web y herramientas de fecha/hora. Diseñado para una integración perfecta con SearXNG y clientes MCP modernos.

Características

🔍 Búsqueda web impulsada por SearXNG con soporte de categorías (general, imágenes, videos, archivos, mapas, redes sociales)
📄 Extracción de contenido de sitios web con metadatos de citas y conversión automática de URL de Reddit
📜 Soporte inicial de lectura de PDF con conversión a Markdown usando PyMuPDF/PyMuPDF4LLM
💾 Caché en memoria con validación automática de frescura
🚦 Limitación de velocidad basada en dominio para prevenir el abuso del servicio
🕒 Herramienta de fecha/hora con conocimiento de zona horaria
⚠️ Manejo robusto de errores con tipos de excepción personalizados
🐳 Dockerizado y configurable mediante variables de entorno
⚙️ Persistencia de configuración entre reinicios del contenedor

Inicio Rápido

Requisitos Previos

Docker instalado en tu sistema
Una instancia de SearXNG en ejecución (autohospedada o un endpoint accesible)

Instalación y Uso

Construir la imagen de Docker:

docker build -t overtlids/mcp-searxng-enhanced:latest .

Ejecutar con tu instancia de SearXNG (Ejecución manual de Docker):

docker run -i --rm --network=host \
  -e SEARXNG_ENGINE_API_BASE_URL="http://127.0.0.1:8080/search" \
  -e DESIRED_TIMEZONE="America/New_York" \
  overtlids/mcp-searxng-enhanced:latest

En este ejemplo, SEARXNG_ENGINE_API_BASE_URL se establece explícitamente. DESIRED_TIMEZONE también se establece explícitamente a America/New_York, que coincide con su valor predeterminado. Si una variable de entorno no se proporciona mediante una bandera -e durante el comando docker run, el servidor utilizará automáticamente el valor predeterminado definido en su Dockerfile (consulta la tabla de Variables de Entorno a continuación). Por lo tanto, si tienes la intención de usar el valor predeterminado para DESIRED_TIMEZONE, podrías omitir la bandera -e DESIRED_TIMEZONE="America/New_York". Sin embargo, SEARXNG_ENGINE_API_BASE_URL es crítico y generalmente debe configurarse para que coincida con la dirección de tu instancia específica de SearXNG si el valor predeterminado del Dockerfile (http://host.docker.internal:8080/search) no es apropiado.

Nota sobre la Ejecución Manual de Docker: Este comando ejecuta el contenedor de Docker de forma independiente. Si estás usando un cliente MCP (como Cline en VS Code) para gestionar este servidor, el cliente iniciará su propia instancia del contenedor usando la configuración definida en su propia configuración. Para que el cliente MCP use variables de entorno específicas, deben configurarse dentro de la configuración del cliente para este servidor (ver más abajo).

Configura tu cliente MCP (por ejemplo, Cline en VS Code):

Para que tu cliente MCP gestione y ejecute correctamente este servidor, debes definir todas las variables de entorno necesarias dentro de la configuración del cliente para el servidor overtlids/mcp-searxng-enhanced. El cliente MCP usará esta configuración para construir el comando docker run.

La siguiente es la configuración predeterminada recomendada para este servidor dentro de la configuración JSON de tu cliente MCP (por ejemplo, cline_mcp_settings.json). Este ejemplo enumera explícitamente todas las variables de entorno configuradas con sus valores predeterminados según lo definido en el Dockerfile. Puedes copiar y pegar esto directamente y luego personalizar cualquier valor según sea necesario.

{
  "mcpServers": {
    "overtlids/mcp-searxng-enhanced": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network=host",
        "-e", "SEARXNG_ENGINE_API_BASE_URL=http://host.docker.internal:8080/search",
        "-e", "DESIRED_TIMEZONE=America/New_York",
        "-e", "ODS_CONFIG_PATH=/config/ods_config.json",
        "-e", "RETURNED_SCRAPPED_PAGES_NO=3",
        "-e", "SCRAPPED_PAGES_NO=5",
        "-e", "PAGE_CONTENT_WORDS_LIMIT=5000",
        "-e", "CITATION_LINKS=True",
        "-e", "MAX_IMAGE_RESULTS=10",
        "-e", "MAX_VIDEO_RESULTS=10",
        "-e", "MAX_FILE_RESULTS=5",
        "-e", "MAX_MAP_RESULTS=5",
        "-e", "MAX_SOCIAL_RESULTS=5",
        "-e", "TRAFILATURA_TIMEOUT=15",
        "-e", "SCRAPING_TIMEOUT=20",
        "-e", "CACHE_MAXSIZE=100",
        "-e", "CACHE_TTL_MINUTES=5",
        "-e", "CACHE_MAX_AGE_MINUTES=30",
        "-e", "RATE_LIMIT_REQUESTS_PER_MINUTE=10",
        "-e", "RATE_LIMIT_TIMEOUT_SECONDS=60",
        "-e", "IGNORED_WEBSITES=",
        "overtlids/mcp-searxng-enhanced:latest"
      ],
      "timeout": 60
    }
  }
}

Puntos Clave para la Configuración del Cliente MCP:

El ejemplo anterior proporciona un conjunto completo de argumentos para ejecutar el contenedor de Docker con todas las variables de entorno configuradas con sus valores predeterminados.
Para personalizar cualquier ajuste, simplemente modifica el valor de la línea -e "VARIABLE_NAME=value" correspondiente dentro del array args en la configuración de tu cliente MCP. Por ejemplo, para cambiar SEARXNG_ENGINE_API_BASE_URL y DESIRED_TIMEZONE, ajustarías sus respectivas líneas.
Consulta la tabla de "Variables de Entorno" a continuación para obtener una descripción detallada de cada variable y su valor predeterminado.
El comportamiento del servidor está controlado principalmente por estas variables de entorno. Si bien un archivo ods_config.json también puede influir en la configuración (ver Gestión de Configuración), las variables de entorno proporcionadas por el cliente MCP tienen prioridad.

Modo Servidor HTTP (FastMCP)

Además del transporte stdio predeterminado, el servidor puede exponer un endpoint MCP sobre HTTP usando FastMCP. Esto es útil para clientes que se conectan vía HTTP en lugar de iniciar un subproceso.

Iniciar el Servidor HTTP

python mcp_server.py --http

El servidor se iniciará en 0.0.0.0:8000 por defecto y aceptará solicitudes MCP en:

http://<host>:<port>/mcp

Todos los orígenes están permitidos (CORS está completamente abierto), por lo que el endpoint es accesible desde cualquier cliente o herramienta basada en navegador.

Variables de Entorno del Servidor HTTP

Variable	Descripción	Predeterminado
`MCP_HTTP_HOST`	Dirección de host a la que vincularse	`0.0.0.0`
`MCP_HTTP_PORT`	Puerto en el que escuchar	`8000`

Ejemplo — host y puerto personalizados:

MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=9000 python mcp_server.py --http

Windows (Símbolo del sistema):

set MCP_HTTP_HOST=127.0.0.1
set MCP_HTTP_PORT=9000
python mcp_server.py --http

Windows (PowerShell):

$env:MCP_HTTP_HOST="127.0.0.1"
$env:MCP_HTTP_PORT="9000"
python mcp_server.py --http

Conectar un Cliente MCP vía HTTP

Apunta tu cliente MCP al endpoint /mcp:

{
  "mcpServers": {
    "mcp-searxng-enhanced-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Nota: Todas las variables de configuración del servidor (SEARXNG_ENGINE_API_BASE_URL, DESIRED_TIMEZONE, etc.) se aplican en modo HTTP exactamente igual que en modo stdio. El archivo ods_config.json se escribe al inicio antes de que el servidor comience a aceptar conexiones.

Ejecución Nativa (Sin Docker)

Si prefieres ejecutar el servidor directamente usando Python sin Docker, sigue estos pasos:

1. Instalación de Python:

Este servidor requiere Python 3.9 o superior. Se recomienda Python 3.11 (como se usa en la imagen de Docker).
Puedes descargar Python desde python.org.

2. Clonar el Repositorio:

Obtén el código desde GitHub:

git clone https://github.com/OvertliDS/mcp-searxng-enhanced.git
cd mcp-searxng-enhanced

3. Crear y Activar un Entorno Virtual (Recomendado):

Usar un entorno virtual ayuda a gestionar las dependencias y evitar conflictos con otros proyectos de Python.

# For Linux/macOS
python3 -m venv .venv
source .venv/bin/activate

# For Windows (Command Prompt)
python -m venv .venv
.\.venv\Scripts\activate.bat

# For Windows (PowerShell)
python -m venv .venv
.\.venv\Scripts\Activate.ps1

4. Instalar Dependencias:

Instala los paquetes de Python requeridos:
```
pip install -r requirements.txt
```
Las dependencias clave incluyen httpx, BeautifulSoup4, pydantic, trafilatura, python-dateutil, cachetools, zoneinfo, filetype, pymupdf, pymupdf4llm y fastmcp.

5. Asegúrate de que SearXNG sea Accesible:

Aún necesitas una instancia de SearXNG en ejecución. Asegúrate de tener su URL base de API (por ejemplo, http://127.0.0.1:8080/search).

6. Configurar Variables de Entorno:

El servidor se configura mediante variables de entorno. Como mínimo, probablemente necesitarás configurar SEARXNG_ENGINE_API_BASE_URL.

Linux/macOS (bash/zsh):

export SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
export DESIRED_TIMEZONE="America/Los_Angeles"

Windows (Símbolo del sistema):

set SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
set DESIRED_TIMEZONE="America/Los_Angeles"

Windows (PowerShell):

$env:SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
$env:DESIRED_TIMEZONE="America/Los_Angeles"

Consulta la tabla de "Variables de Entorno" a continuación para ver todas las opciones disponibles. Si no se configuran, se usarán los valores predeterminados del script o de un archivo ods_config.json (si está presente en el directorio raíz o en ODS_CONFIG_PATH).

7. Ejecutar el Servidor:

Modo stdio (predeterminado — para clientes MCP que inician un subproceso):
```
python mcp_server.py
```
El servidor escucha conexiones de clientes MCP a través de stdin/stdout.
Modo HTTP (para clientes MCP que se conectan vía HTTP):
```
python mcp_server.py --http
```
El servidor inicia un endpoint HTTP de FastMCP en http://0.0.0.0:8000/mcp. Consulta Modo Servidor HTTP para ver las opciones de configuración.

8. Archivo de Configuración (ods_config.json):

Alternativamente, o en combinación con variables de entorno, puedes crear un archivo ods_config.json en el directorio raíz del proyecto (o en la ruta especificada por la variable de entorno ODS_CONFIG_PATH). Las variables de entorno siempre tendrán prioridad sobre los valores de este archivo. Ejemplo: json { "searxng_engine_api_base_url": "http://127.0.0.1:8080/search", "desired_timezone": "America/New_York" }

Variables de Entorno

Las siguientes variables de entorno controlan el comportamiento del servidor. Puedes configurarlas en la configuración de tu cliente MCP (recomendado para servidores gestionados por el cliente) o al ejecutar Docker manualmente.

Gestión de Configuración

El servidor utiliza un enfoque de configuración de tres niveles:

Valores predeterminados del script (codificados en Python)
Archivo de configuración (cargado desde ODS_CONFIG_PATH, por defecto /config/ods_config.json)
Variables de entorno (mayor precedencia)

El archivo de configuración solo se actualiza cuando:

El archivo aún no existe (inicialización por primera vez)
Se proporcionan variables de entorno explícitamente para la ejecución actual

Esto garantiza que las configuraciones del usuario se conserven entre reinicios del contenedor cuando no se establecen nuevas variables de entorno.

Configuración de Variables de Entorno

Variable	Descripción	Predeterminado (del Dockerfile)	Notas
`SEARXNG_ENGINE_API_BASE_URL`	Endpoint de búsqueda de SearXNG	`http://host.docker.internal:8080/search`	Crucial para el funcionamiento del servidor
`MCP_HTTP_HOST`	Dirección de enlace para el modo servidor HTTP	`0.0.0.0`	Solo se usa al iniciar con `--http`
`MCP_HTTP_PORT`	Puerto para el modo servidor HTTP	`8000`	Solo se usa al iniciar con `--http`
`DESIRED_TIMEZONE`	Zona horaria para la herramienta de fecha/hora	`America/New_York`	P. ej., `America/Los_Angeles`. Lista de zonas horarias de la base de datos tz: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
`ODS_CONFIG_PATH`	Ruta al archivo de configuración persistente	`/config/ods_config.json`	Normalmente se deja el valor predeterminado dentro del contenedor.
`RETURNED_SCRAPPED_PAGES_NO`	Máximo de páginas a devolver por búsqueda	`3`
`SCRAPPED_PAGES_NO`	Máximo de páginas para intentar extraer contenido	`5`
`PAGE_CONTENT_WORDS_LIMIT`	Máximo de palabras por página extraída	`5000`
`CITATION_LINKS`	Habilitar/deshabilitar eventos de citación	`True`	`True` o `False`
`MAX_IMAGE_RESULTS`	Máximo de resultados de imágenes a devolver	`10`
`MAX_VIDEO_RESULTS`	Máximo de resultados de videos a devolver	`10`
`MAX_FILE_RESULTS`	Máximo de resultados de archivos a devolver	`5`
`MAX_MAP_RESULTS`	Máximo de resultados de mapas a devolver	`5`
`MAX_SOCIAL_RESULTS`	Máximo de resultados de redes sociales a devolver	`5`
`TRAFILATURA_TIMEOUT`	Tiempo de espera de extracción de contenido (segundos)	`15`
`SCRAPING_TIMEOUT`	Tiempo de espera de solicitudes HTTP (segundos)	`20`
`CACHE_MAXSIZE`	Número máximo de sitios web en caché	`100`
`CACHE_TTL_MINUTES`	Tiempo de vida de la caché (minutos)	`5`
`CACHE_MAX_AGE_MINUTES`	Edad máxima para contenido en caché (minutos)	`30`
`RATE_LIMIT_REQUESTS_PER_MINUTE`	Máximo de solicitudes por dominio por minuto	`10`
`RATE_LIMIT_TIMEOUT_SECONDS`	Ventana de seguimiento del límite de velocidad (segundos)	`60`
`IGNORED_WEBSITES`	Lista separada por comas de sitios a ignorar	`""` (vacío)	P. ej., `"example.com,another.org"`

Herramientas y Alias

Nombre de la Herramienta	Propósito	Alias
`search_web`	Búsqueda web a través de SearXNG	`search`, `web_search`, `find`, `lookup_web`, `search_online`, `access_internet`, `lookup`*
`get_website`	Extraer contenido de sitios web	`fetch_url`, `scrape_page`, `get`, `load_website`, `lookup`*
`get_current_datetime`	Fecha/hora actual	`current_time`, `get_time`, `current_date`

*lookup es sensible al contexto:

Si se llama con un argumento url, se asigna a get_website
De lo contrario, se asigna a search_web

Ejemplo: Llamar a las Herramientas

Búsqueda Web

{ "name": "search_web", "arguments": { "query": "open source ai" } }

o usando un alias:

{ "name": "search", "arguments": { "query": "open source ai" } }

Búsqueda Específica por Categoría

{ "name": "search_web", "arguments": { "query": "landscapes", "category": "images" } }

Extracción de Sitios Web

{ "name": "get_website", "arguments": { "url": "example.com" } }

o usando un alias:

{ "name": "lookup", "arguments": { "url": "example.com" } }

Fecha/Hora Actual

{ "name": "get_current_datetime", "arguments": {} }

{ "name": "current_time", "arguments": {} }

Funciones Avanzadas

Búsqueda Específica por Categoría

La herramienta search_web admite diferentes categorías con resultados adaptados:

images: Devuelve URL de imágenes, títulos y páginas de origen con opción de inserción en Markdown
videos: Devuelve información de videos, incluidos títulos, origen y URL de inserción
files: Devuelve información de archivos descargables, incluidos formato y tamaño
map: Devuelve datos de ubicación, incluidas coordenadas y direcciones
social media: Devuelve publicaciones y perfiles de plataformas sociales
general: Categoría predeterminada que extrae y devuelve el contenido completo de la página web

Conversión de URL de Reddit

Al extraer contenido de Reddit, las URL se convierten automáticamente para usar el dominio old.reddit.com para una mejor extracción del contenido.

Limitación de Velocidad

La limitación de velocidad basada en dominios evita solicitudes excesivas al mismo dominio dentro de una ventana de tiempo. Esto evita abrumar los sitios web de destino y posibles bloqueos de IP.

Validación de Caché

El contenido web en caché se valida automáticamente para verificar su frescura según la antigüedad. El contenido obsoleto se actualiza automáticamente, mientras que el contenido en caché válido se sirve rápidamente.

Manejo de Errores

El servidor implementa un sistema robusto de manejo de errores con estos tipos de excepción:

MCPServerError: Clase de excepción base para todos los errores del servidor
ConfigurationError: Se genera cuando los valores de configuración son inválidos
SearXNGConnectionError: Se genera cuando falla la conexión a SearXNG
WebScrapingError: Se genera cuando falla el raspado web
RateLimitExceededError: Se genera cuando se excede el límite de velocidad para un dominio

Los errores se propagan correctamente al cliente con mensajes informativos.

Solución de Problemas

No se puede conectar a SearXNG: Asegúrate de que tu instancia de SearXNG esté en ejecución y que la variable de entorno SEARXNG_ENGINE_API_BASE_URL apunte al endpoint correcto.
Errores de límite de velocidad: Ajusta RATE_LIMIT_REQUESTS_PER_MINUTE si experimentas demasiados errores de límite de velocidad.
Extracción de contenido lenta: Aumenta TRAFILATURA_TIMEOUT para permitir más tiempo para el procesamiento de contenido en páginas complejas.
Problemas de red en Docker: Si usas Docker Desktop en Windows/Mac, host.docker.internal debería resolverse a la máquina host. En Linux, puede que necesites usar la dirección IP del host en su lugar.
Modo HTTP no accesible: Asegúrate de que ningún firewall esté bloqueando MCP_HTTP_PORT (por defecto 8000). Establece MCP_HTTP_HOST=0.0.0.0 para enlazar en todas las interfaces, o 127.0.0.1 para restringir solo a localhost.
Error de ID de sesión en modo HTTP: El servidor se ejecuta en modo HTTP sin estado: cada POST a /mcp es autónomo. Si tu cliente requiere transporte basado en sesiones, cambia al modo stdio.

Agradecimientos

Inspirado en:

SearXNG - Motor de metabúsqueda que respeta la privacidad
Trafilatura - Herramienta de raspado web para extracción de texto
ihor-sokoliuk/mcp-searxng - Servidor MCP original para SearXNG
nnaoycurt (Mejor herramienta de búsqueda web)
@bwoodruff2021 (Herramienta GetTimeDate)