Servidor MCP de SearxNG

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona capacidades de búsqueda web mediante SearxNG, lo que permite a los asistentes de IA como Claude buscar en la web.

Creado por IA con supervisión humana, ¡porque a veces incluso la inteligencia artificial necesita que alguien le diga cuándo tomar un café! 🤖☕

Descripción general

Este proyecto implementa un servidor MCP que se conecta a SearxNG, un metabuscador que respeta la privacidad. El servidor proporciona una forma sencilla y eficiente para que los Modelos de Lenguaje Grandes (MLM) busquen en la web sin rastrear a los usuarios.

El servidor está diseñado específicamente para LLM e incluye únicamente las funciones esenciales para minimizar el uso de la ventana de contexto. Este enfoque optimizado garantiza una comunicación eficiente entre los LLM y el motor de búsqueda, preservando así un valioso espacio de contexto para información más importante.

Características

• Búsqueda web centrada en la privacidad a través de SearxNG

• API sencilla para la integración de LLM

• Compatible con Claude Desktop y otros clientes compatibles con MCP

• Parámetros de búsqueda configurables

• Resultados de búsqueda limpios y formateados, optimizados para LLM

Integración con aplicaciones compatibles con MCP

Ejemplos de integración

Usando pipx run (Recomendado, no requiere instalación)

Crea un archivo .clauderc en tu directorio de inicio:

Usando uvx run (No requiere instalación)

Usando Python con pip (requiere instalación)

Uso con Docker (no requiere instalación)

Nota: Al utilizar Docker con servidores MCP:

1. Las variables de entorno deben pasarse directamente utilizando el indicador -e en la matriz args , ya que el objeto env no se pasa correctamente al contenedor Docker.

2. Si necesita acceder a una instancia de SearxNG que se ejecuta en localhost (p. ej., http://localhost:8080 ), debe usar el indicador --network=host para permitir que el contenedor acceda a la red del host. De lo contrario, "localhost" dentro del contenedor se referirá al contenedor en sí, no a su máquina host.

3. Al usar --network=host , las asignaciones de puertos ( -p ) no son necesarias y se ignorarán, ya que el contenedor comparte la pila de red del host directamente.

Configuración

Configurar el servidor usando variables de entorno:

Nota: Establecer niveles de registro superiores a ERROR (como DEBUG o INFO) puede interrumpir la integración con algunas aplicaciones debido a una salida excesiva en el canal de comunicación.

Puede encontrar una lista de instancias públicas de SearxNG en https://searx.space si no desea alojar la suya propia.

Instalación y uso

Prerrequisitos

• Python 3.10 o superior

• Una instancia de SearxNG (pública o autoalojada)

Opción 1: Ejecutar sin instalación (recomendado)

La forma más sencilla de utilizar este servidor es con pipx o uvx, lo que le permite ejecutar el paquete sin instalarlo permanentemente:

Puede pasar opciones de configuración directamente:

Opción 2: Instalar desde PyPI o la fuente

Para una instalación más permanente:

Después de la instalación, puede ejecutar el servidor con:

Opción 3: Docker

Si prefieres usar Docker:

Para obtener información completa sobre el uso de Docker, consulte la sección Configuración de Docker a continuación.

Protocolos de transporte

El servidor MCP admite dos protocolos de transporte:

• STDIO (predeterminado): para aplicaciones CLI e integración directa

  • Se utiliza de forma predeterminada en todos los ejemplos.

  • Adecuado para la integración con Claude Desktop y otros clientes compatibles con MCP

  • No se ha iniciado ningún servidor HTTP

• SSE (Eventos enviados por el servidor): para clientes basados en web e integraciones basadas en HTTP

  • Inicia un servidor HTTP al que los clientes pueden conectarse

  • Útil para aplicaciones web y servicios que necesitan actualizaciones en tiempo real.

  • Requiere mapeo de puertos al usar Docker

Uso del transporte SSE

Para utilizar el protocolo de transporte SSE:

1. Con ejecución directa :

   # Set the transport protocol to SSE TRANSPORT_PROTOCOL=sse python -m searxng_simple_mcp.server # Or with FastMCP fastmcp run src/searxng_simple_mcp/server.py --transport sse

2. Con Docker :

   # Run with SSE transport protocol docker run -p 8000:8000 -e TRANSPORT_PROTOCOL=sse -e SEARXNG_MCP_SEARXNG_URL=https://your-instance.example.com ghcr.io/sacode/searxng-simple-mcp:latest

3. Con Docker Compose (desde el docker-compose.yml incluido):

   environment: - SEARXNG_MCP_SEARXNG_URL=https://searx.info - SEARXNG_MCP_TIMEOUT=10 - SEARXNG_MCP_MAX_RESULTS=20 - SEARXNG_MCP_LANGUAGE=all - TRANSPORT_PROTOCOL=sse # Transport protocol: stdio or sse

Al utilizar SSE, el servidor será accesible a través de HTTP en http://localhost:8000 de manera predeterminada.

Para conectarse al servidor SSE desde un cliente MCP, utilice una configuración como:

Nota: No todas las aplicaciones admiten el protocolo de transporte SSE. Asegúrese de que su cliente MCP sea compatible con SSE antes de usar este método de transporte.

Desarrollo

Para desarrollo y pruebas:

Publicación en PyPI

Para los mantenedores que necesitan publicar nuevas versiones del paquete en PyPI:

Estos comandos harán lo siguiente:

1. Actualice la versión tanto en package.json como en pyproject.toml

2. Limpia el directorio dist para eliminar compilaciones antiguas

3. Construir el paquete (crear rueda y distribución de origen)

4. Comprueba si el paquete tiene errores

5. Subir el paquete a PyPI

Necesitará tener una cuenta de PyPI y estar autenticado con Twine. Puede configurar la autenticación mediante:

• Creando un archivo .pypirc en su directorio de inicio

• Uso de variables de entorno ( TWINE_USERNAME y TWINE_PASSWORD )

• Uso de tokens de API de PyPI (recomendado)

Configuración de Docker

Al utilizar Docker con servidores MCP, tenga en cuenta estos puntos:

1. Integración con clientes MCP : utilice la configuración que se muestra en la sección Uso con Docker para la integración con Claude Desktop u otros clientes compatibles con MCP.

2. Protocolos de transporte :

   • De forma predeterminada, el contenedor Docker utiliza el protocolo de transporte stdio

   • Para el transporte SSE, consulte la sección Uso del transporte SSE

3. Opciones de configuración :

   • Utilice un archivo de entorno (.env) para configurar el servidor: docker run --env-file .env ...

   • Pase variables de entorno individuales con el indicador -e : docker run -e SEARXNG_MCP_SEARXNG_URL=https://example.com ...

   • Consulte la sección Configuración para conocer las variables de entorno disponibles

4. Redes :

   • Utilice --network=host cuando necesite acceder a servicios en su máquina host

   • Utilice -p 8000:8000 al exponer el servidor SSE a su red

Estructura del paquete

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.