Servidor MCP de Unraid

Un servidor MCP (Protocolo de contexto de modelo) basado en Python que permite a los asistentes de IA interactuar con un servidor Unraid a través de la API GraphQL oficial de Unraid.

Descargo de responsabilidad

ÚSELO BAJO SU PROPIA RESPONSABILIDAD : Este software proporciona acceso a su servidor Unraid mediante asistentes de IA. Si bien esta implementación está configurada como de solo lectura para mayor seguridad, debe tener cuidado al usarla.

• Esta es una herramienta no oficial y no está afiliada ni respaldada por Unraid, Inc.
• Todas las operaciones están limitadas a acciones de solo lectura para evitar modificaciones del sistema.
• Mantenga siempre copias de seguridad adecuadas de sus datos
• Revise toda la información y sugerencias proporcionadas por los asistentes de IA antes de tomar medidas.
• Los desarrolladores no son responsables de ningún problema que pueda surgir del uso de este software.

Incluso con acceso de solo lectura, las herramientas de monitoreo pueden exponer información confidencial del sistema. Al usar este software, usted reconoce y acepta estas limitaciones y riesgos.

Características

• Información del sistema : obtén información detallada sobre tu servidor Unraid
• Gestión de matrices : supervisar el estado de las matrices
• Administración de Docker : lista de contenedores y redes de Docker
• Administración de máquinas virtuales : lista de máquinas virtuales
• Información del disco : obtenga información detallada sobre los discos y dispositivos no asignados
• Gestión de notificaciones : ver y administrar las notificaciones del sistema
• Administración de recursos compartidos : ver y administrar recursos compartidos de red
• Gestión de usuarios : Lista de usuarios
• Gestión de claves API : lista de claves API
• Historial de paridad : ver el historial de verificación de paridad
• Recursos compartidos : Explorar recursos compartidos de usuarios en el servidor Unraid
• Complementos : ver los complementos instalados y su estado
• Manejo de errores : Manejo integral de errores con información de diagnóstico
• Registro : registro detallado para la resolución de problemas
• Recursos con plantillas : acceda a contenedores y máquinas virtuales específicos por nombre

Prerrequisitos

• Python 3.10 o posterior
• Un servidor Unraid con la API habilitada
• Clave API con permisos adecuados

Instalación

Instalación mediante herrería

Para instalar Unraid MCP Server para Claude Desktop automáticamente a través de Smithery :

Instalación manual

1. Clonar el repositorio:
   git clone https://github.com/jmagar/unraid-mcp.git cd unraid-mcp
2. Crear y activar un entorno virtual:
   python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
3. Instalar dependencias:
   pip install -r requirements.txt
4. Crea un archivo .env con tus credenciales de API de Unraid:
   cp .env.template .env # Edit .env with your actual API URL and key

Configuración de la API de Unraid

Para utilizar este servidor MCP, debe configurar la API de Unraid en su servidor Unraid:

1. Habilite el modo de desarrollador y el entorno sandbox de GraphQL mediante la CLI:
   unraid-api developer
   Siga las instrucciones para habilitar la zona protegida.
2. Cree una clave API con los permisos necesarios:
   unraid-api apikey --create
   Siga las instrucciones para configurar el nombre, la descripción, los roles y los permisos.
3. Configure su archivo .env con:
   • UNRAID_API_URL : La URL de GraphQL (por ejemplo, http://your-unraid-server-ip/graphql )
   • UNRAID_API_KEY : La clave API que usted creó
4. Pruebe la API utilizando el entorno sandbox GraphQL en http://your-unraid-server-ip/graphql

Nota : La API de Unraid utiliza el encabezado x-api-key para la autenticación, no tokens de portador.

Solución de problemas

• Si recibe errores CORS, asegúrese de que su cliente incluya el encabezado Origin correcto que coincida con la URL del servidor.
• Asegúrese de que su clave API tenga los roles y permisos necesarios para las consultas que intenta ejecutar.
• Verifique que el entorno sandbox de GraphQL esté habilitado y accesible.

Uso

Ejecución del servidor MCP

Ejecute el servidor en modo stdio para la integración con asistentes de IA:

El modo stdio es útil para:

• Integración directa con asistentes de IA que admiten el protocolo MCP
• Pruebas con el SDK de Python antrópico
• Integración con Claude en Cursor

Al ejecutarse en modo stdio, el servidor lee desde la entrada estándar y escribe en la salida estándar, siguiendo el formato del protocolo MCP. Esto permite la comunicación directa con los asistentes de IA sin necesidad de transporte HTTP.

Arquitectura del servidor

El servidor está construido utilizando el marco FastMCP y consta de:

1. Cliente API de Unraid ( unraid_client.py ):
   • Maneja la comunicación GraphQL con el servidor Unraid
   • Gestiona la autenticación y el manejo de errores.
   • Proporciona informes de errores consistentes
2. Servidor MCP ( server.py ):
   • Define recursos y herramientas según la especificación MCP
   • Expone la funcionalidad de Unraid a los asistentes de IA
   • Maneja la validación de solicitudes y el diagnóstico de errores.

Recursos disponibles

Herramientas disponibles

Gestión del sistema

Gestión de matrices

Administración de Docker

Administración de máquinas virtuales

Gestión de notificaciones

Gestión de acciones

Administración de discos

Gestión de usuarios

Gestión de claves API

Integración con Claude

Para utilizar el servidor MCP con Claude API u otros asistentes de IA que admitan el modo stdio:

1. Cree un archivo de configuración (por ejemplo, unraid_mcp_config.json ):
   { "mcpServers": { "unraid": { "command": "/path/to/python", "args": ["/path/to/unraid-mcp/run_server.py"], "env": { "UNRAID_API_URL": "http://your-unraid-server:port/graphql", "UNRAID_API_KEY": "your-api-key", "LOG_LEVEL": "INFO", "CLAUDE_MCP_SERVER": "true" }, "disabled": false, "autoApprove": [] } } }

Nota : Para los usuarios de Windows, asegúrese de utilizar barras invertidas dobles en las rutas (por ejemplo, C:\\Users\\username\\unraid-mcp\\run_server.py )

Consultas de ejemplo

• "¿Cuál es el uso actual de la CPU en mi servidor Unraid?"
• "Enumerar todos mis contenedores Docker"
• "Cuéntame sobre mi contenedor Plex" (usa el recurso container_details)
• "Iniciar el contenedor Plex"
• "¿Cuál es el estado de mi matriz?"
• "¿Cuánto espacio libre tengo en mi servidor Unraid?"
• "Muéstrame detalles sobre mi máquina virtual Windows" (usa el recurso vm_details)
• ¿Qué complementos tengo instalados?

Solución de problemas

Consulte el archivo de registro ( unraid_mcp.log ) para obtener información detallada del error.

Problemas comunes:

• URL de API o clave incorrecta en el archivo .env
• Problemas de conectividad de red con el servidor Unraid
• Permisos insuficientes para la clave API
• El modo de desarrollador no está habilitado en el servidor Unraid
• La clave API no tiene los roles necesarios

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.

Referencias

• Protocolo de contexto modelo
• SDK de Python para MCP
• Documentación de la API de Unraid