Unraid MCP

Un servidor local de Model Context Protocol que permite a los clientes de IA inspeccionar y gestionar un servidor Unraid a través de la API GraphQL oficial de Unraid.

Divulgación de desarrollo asistido por IA: Este proyecto fue diseñado, investigado, implementado, documentado y probado con una asistencia sustancial de agentes de codificación de IA. No es un proyecto oficial de Unraid. Revisa el código fuente, los permisos y la configuración de seguridad por ti mismo antes de concederle acceso a un servidor Unraid, especialmente antes de habilitar las herramientas de mutación.

El MCP es de solo lectura por defecto. Las herramientas de mutación se omiten por completo hasta que se habilitan explícitamente mediante variables de entorno, y las acciones permanentes o de alto riesgo utilizan una segunda barrera.

Requisitos

• Node.js 22 o posterior

• pnpm 11

• Unraid 7.2 o posterior, donde la API está integrada en el sistema operativo

• Una clave de API de Unraid

Unraid 7.0-7.1 puede exponer la API v4 a través del plugin Unraid Connect, pero Unraid documenta esa combinación como soporte limitado. Los documentos GraphQL de este proyecto están dirigidos a la API v4.35.1, incluida con Unraid 7.3.2. Las versiones anteriores de la API pueden rechazar consultas más recientes, como las de métricas, registros o campos UPS.

Related MCP server: GraphQL MCP Toolkit

Configuración de Unraid

1. Abre Settings > Management Access > API Keys en la WebGUI de Unraid.

2. Crea una clave para este MCP.

3. Empieza con el rol VIEWER para acceso de solo lectura.

4. Guarda la clave generada en UNRAID_API_KEY; nunca la pongas en el control de versiones ni en argumentos de línea de comandos.

El comando equivalente de terminal de Unraid es:

unraid-api apikey --create --name "Unraid MCP read only" --roles VIEWER --json

Para acceso de mutación, prefiere permisos detallados a ADMIN. Selecciona solo los recursos utilizados por las herramientas que planeas habilitar, como ARRAY, DOCKER, VMS y NOTIFICATIONS, con READ_ANY, UPDATE_ANY y, solo donde sea necesario, DELETE_ANY.

El Sandbox de GraphQL no es necesario para este MCP. Déjalo deshabilitado fuera del desarrollo porque habilitarlo también activa la introspección de esquema.

Instalación

pnpm install --frozen-lockfile
pnpm build

Las dependencias están fijadas a versiones exactas y las instalaciones se realizan con el lockfile congelado. pnpm también rechaza versiones publicadas hace menos de siete días (incluidos los paquetes con tiempos de publicación ausentes), verifica la integridad del paquete o almacén, bloquea scripts de ciclo de vida no declarados y rechaza reducciones de confianza del paquete. La excepción de confianza específica de versión para undici-types@6.21.0 es requerida por @types/node fijado; los controles de antigüedad, integridad y lockfile también se aplican a ella. Para actualizar intencionalmente una dependencia después de revisarla y esperar el período de cuarentena, usa una versión exacta y permite explícitamente el cambio del lockfile:

pnpm update --exact --no-frozen-lockfile package-name@x.y.z
pnpm verify
pnpm audit

Revisa tanto package.json como pnpm-lock.yaml antes de aceptar la actualización. No añadas trabajos automatizados de actualización de dependencias sin preservar estos controles.

Establece la configuración en el entorno que lanza el MCP:

export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-api-key"
node /absolute/path/to/unraid-mcp/dist/index.js

UNRAID_URL puede ser el origen de la WebGUI, en cuyo caso se añade /graphql, o el endpoint exacto de GraphQL. Configura la URL HTTPS final directamente; se rechazan las redirecciones para que la clave de API no pueda reenviarse a otro origen.

Imagen de contenedor

Las imágenes de lanzamiento con versión se publican en Docker Hub para linux/amd64 y linux/arm64. Fija una versión o un digest de imagen para los despliegues en lugar de depender de la etiqueta mutable latest:

docker pull lemanjo/unraid-mcp:0.1.1

La imagen final utiliza un runtime de Node.js de Distroless fijado por digest. Se ejecuta sin shell, gestor de paquetes, npm ni otras herramientas de compilación, y como un usuario no root numérico. Las compilaciones de contenedores se escanean con Trivy y fallan antes del inicio de sesión en el registro cuando existe una vulnerabilidad crítica o alta corregible.

Construye la imagen de producción en tu servidor Unraid u otro host Docker:

docker build --tag unraid-mcp:0.1.1 .

Contenedor stdio local

El transporte predeterminado es stdio. --env NAME reenvía valores desde el entorno de lanzamiento sin poner secretos en la imagen o en los argumentos de comando:

export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-api-key"

docker run --rm -i \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  unraid-mcp:0.1.1

Reenvía cualquier configuración opcional de la misma manera, por ejemplo --env UNRAID_ALLOW_MUTATIONS. Para un archivo CA personalizado, móntalo como de solo lectura y configura su ruta en el contenedor:

docker run --rm -i \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  --env UNRAID_CA_CERT_PATH=/certs/unraid-ca.pem \
  --volume /host/path/unraid-ca.pem:/certs/unraid-ca.pem:ro \
  unraid-mcp:0.1.1

En modo stdio, la imagen no escucha en un puerto. El host de IA lo lanza con docker run --rm -i y es responsable de su ciclo de vida.

Contenedor HTTP remoto siempre activo

Usa HTTP Streamable autenticado cuando el contenedor se ejecute en una máquina diferente a la del cliente de IA. Genera un token MCP persistente en una máquina de confianza:

export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-unraid-api-key"
export MCP_ALLOWED_HOSTS="mcp-server.example,192.168.1.20"

Inicia el contenedor remoto:

docker network create unraid-mcp-backend

docker run -d \
  --name unraid-mcp \
  --restart unless-stopped \
  --network unraid-mcp-backend \
  --env MCP_TRANSPORT=http \
  --env MCP_HOST=0.0.0.0 \
  --env MCP_PORT=3000 \
  --env MCP_ALLOWED_HOSTS \
  --env MCP_AUTH_TOKEN \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  unraid-mcp:0.1.1

MCP_ALLOWED_HOSTS es obligatorio al vincular una dirección comodín IPv4 o IPv6. Enumera cada nombre de host o dirección IP que los clientes o un proxy inverso colocarán en la cabecera HTTP Host. Las entradas no incluyen puertos, y las entradas IPv6 usan corchetes. Los valores de localhost siempre se incluyen para las comprobaciones de salud.

Si se omite MCP_AUTH_TOKEN, el servidor genera un token aleatorio criptográficamente de 256 bits y lo imprime una vez durante el inicio:

docker logs unraid-mcp

Busca Generated MCP auth token:. Cualquiera que pueda leer ese registro puede acceder al MCP, y se genera un nuevo token después de cada reinicio del proceso si la variable sigue sin establecerse. Establece MCP_AUTH_TOKEN explícitamente para despliegues de producción estables. El token MCP es independiente de UNRAID_API_KEY; los clientes de IA remotos solo necesitan el token MCP.

El listener HTTP es intencionalmente HTTP plano. El ejemplo no publica su puerto; une un contenedor Caddy, Nginx o Traefik a unraid-mcp-backend y haz de proxy a http://unraid-mcp:3000. Para un proxy instalado en el host, Docker 28 o posterior puede publicar 127.0.0.1:3000:3000; las versiones anteriores de Docker, incluidas algunas versiones de Unraid, pueden exponer los puertos publicados en localhost a la misma red de capa 2, así que usa la red privada o una regla de cortafuegos explícita en su lugar. No expongas el puerto 3000 directamente a Internet. La comprobación de salud del contenedor llama a GET /health; el tráfico MCP usa /mcp.

La limitación de autenticación integrada identifica al par TCP inmediato. Detrás de un proxy inverso, configura también la limitación de velocidad de autenticación en el proxy, porque todos los clientes proxyficados pueden compartir una única dirección de par. No reenvíes un valor Host no confiable; conserva el nombre de host externo e inclúyelo en MCP_ALLOWED_HOSTS, o reescríbelo a un nombre de host fijo en la lista de permitidos.

Configuración del cliente Docker local

Una configuración de OpenCode que lanza la imagen a través de un daemon Docker es:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "--rm",
        "-i",
        "--env",
        "UNRAID_URL",
        "--env",
        "UNRAID_API_KEY",
        "unraid-mcp:0.1.1"
      ],
      "enabled": true,
      "environment": {
        "UNRAID_URL": "{env:UNRAID_URL}",
        "UNRAID_API_KEY": "{env:UNRAID_API_KEY}"
      }
    }
  }
}

El daemon Docker utilizado por el host de IA debe tener acceso a la imagen. Reinicia OpenCode después de cambiar su configuración.

Configuración

Usa UNRAID_CA_CERT o UNRAID_CA_CERT_PATH, no ambos. Prefiere confiar en el certificado de Unraid o en la CA local. UNRAID_TLS_SKIP_VERIFY=true es un último recurso explícito e imprime una advertencia; no cambia el comportamiento TLS globalmente para otras conexiones Node.js.

Se admite HTTP plano para redes heredadas aisladas, pero imprime una advertencia porque la clave de API y todos los datos del servidor viajan sin cifrado.

Configuración del cliente de IA

OpenCode

Exporta las variables de entorno antes de iniciar OpenCode y luego añade este MCP local a opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "local",
      "command": ["node", "/absolute/path/to/unraid-mcp/dist/index.js"],
      "enabled": true,
      "environment": {
        "UNRAID_URL": "{env:UNRAID_URL}",
        "UNRAID_API_KEY": "{env:UNRAID_API_KEY}",
        "UNRAID_CA_CERT_PATH": "{env:UNRAID_CA_CERT_PATH}",
        "UNRAID_ALLOW_MUTATIONS": "{env:UNRAID_ALLOW_MUTATIONS}",
        "UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS": "{env:UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS}"
      }
    }
  }
}

Elimina las entradas de entorno opcionales que no estén establecidas. Reinicia OpenCode después de cambiar su configuración.

Para conectarte a un contenedor HTTP siempre activo, exporta su token MCP en la máquina de OpenCode y configura un servidor remoto:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "remote",
      "url": "https://mcp-server.example/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MCP_AUTH_TOKEN}"
      }
    }
  }
}

Usa la URL HTTPS del proxy inverso, no la URL GraphQL de Unraid. OpenCode envía MCP_AUTH_TOKEN al MCP; solo el contenedor MCP envía UNRAID_API_KEY a Unraid.

Claude Code

Exporta UNRAID_URL y UNRAID_API_KEY antes de iniciar Claude Code. Para el ámbito del proyecto, crea .mcp.json en el proyecto donde uses Claude Code:

{
  "mcpServers": {
    "unraid": {
      "command": "node",
      "args": ["/absolute/path/to/unraid-mcp/dist/index.js"],
      "env": {
        "UNRAID_URL": "${UNRAID_URL}",
        "UNRAID_API_KEY": "${UNRAID_API_KEY}"
      }
    }
  }
}

Claude Code expande las referencias ${VAR} desde su entorno. Por lo tanto, la configuración puede compartirse sin almacenar la clave de API. Añade variables opcionales a env solo cuando estén establecidas, por ejemplo "UNRAID_ALLOW_MUTATIONS": "${UNRAID_ALLOW_MUTATIONS}".

Para lanzar la imagen de contenedor en su lugar, usa:

{
  "mcpServers": {
    "unraid": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env",
        "UNRAID_URL",
        "--env",
        "UNRAID_API_KEY",
        "unraid-mcp:0.1.1"
      ],
      "env": {
        "UNRAID_URL": "${UNRAID_URL}",
        "UNRAID_API_KEY": "${UNRAID_API_KEY}"
      }
    }
  }
}

Ejecuta claude mcp list para verificar el servidor y luego usa /mcp dentro de Claude Code para inspeccionar su estado y herramientas. Claude Code solicita aprobación antes de usar un servidor .mcp.json de ámbito de proyecto. Usa --scope user con los comandos MCP de Claude Code si prefieres una configuración privada entre proyectos en ~/.claude.json.

Para un contenedor HTTP siempre activo, usa esta entrada .mcp.json en su lugar:

{
  "mcpServers": {
    "unraid": {
      "type": "http",
      "url": "https://mcp-server.example/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      }
    }
  }
}

Exporta MCP_AUTH_TOKEN antes de iniciar Claude Code. La referencia ${MCP_AUTH_TOKEN} se expande sin almacenar su valor en la configuración del proyecto.

Codex CLI e IDE

Codex CLI, la extensión Codex IDE y la aplicación de escritorio ChatGPT comparten la configuración MCP. Exporta las variables requeridas y luego añade esta entrada a ~/.codex/config.toml, o a .codex/config.toml en un proyecto de confianza:

[mcp_servers.unraid]
command = "node"
args = ["/absolute/path/to/unraid-mcp/dist/index.js"]
env_vars = ["UNRAID_URL", "UNRAID_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

env_vars reenvía valores desde el entorno de Codex sin escribirlos en config.toml. Añade cualquier configuración opcional habilitada a esa lista, como UNRAID_CA_CERT_PATH o UNRAID_ALLOW_MUTATIONS.

Para lanzar la imagen de contenedor en su lugar, usa:

[mcp_servers.unraid]
command = "docker"
args = [
  "run",
  "--rm",
  "-i",
  "--env",
  "UNRAID_URL",
  "--env",
  "UNRAID_API_KEY",
  "unraid-mcp:0.1.1",
]
env_vars = ["UNRAID_URL", "UNRAID_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

El modo de aprobación writes solicita confirmación para herramientas que no están marcadas como de solo lectura. Ejecuta codex mcp list para verificar el servidor, y usa /mcp en la interfaz de Codex TUI para inspeccionar las herramientas conectadas. Reinicia la extensión del IDE o la aplicación de escritorio de ChatGPT después de editar la configuración compartida.

Para un contenedor HTTP siempre activo, usa esta entrada en su lugar:

[mcp_servers.unraid]
url = "https://mcp-server.example/mcp"
bearer_token_env_var = "MCP_AUTH_TOKEN"
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

Codex lee el token portador desde su entorno local y no almacena el valor en config.toml.

Claude Desktop y otros hosts stdio

Configura el host para que lance:

node /absolute/path/to/unraid-mcp/dist/index.js

Haz que el proceso hijo herede las variables de entorno necesarias desde el sistema operativo, un gestor de servicios o un gestor de secretos. No coloques la clave de API en el arreglo args. Si un host admite valores de entorno por servidor pero no referencias a secretos, ten en cuenta que esos valores se almacenan en el archivo de configuración de ese host.

Inspector MCP

Con las variables exportadas, inspecciona y llama a las herramientas de forma interactiva:

pnpm dlx @modelcontextprotocol/inspector node dist/index.js

El Inspector no es una dependencia del proyecto; usa la versión aprobada para tu entorno.

Herramientas

Las siguientes herramientas de solo lectura están siempre registradas:

UNRAID_ALLOW_MUTATIONS=true agrega:

UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS=true agrega adicionalmente:

También permite que unraid_control_parity_check se inicie con correct=true.

Las anotaciones de MCP son sugerencias para los clientes, no controles de acceso. Las variables de entorno y los permisos de la clave de API de Unraid son los controles reales.

Limitaciones de la API

El esquema oficial actual no cubre todas las acciones de la interfaz web. En particular:

• Los recursos compartidos son de solo lectura; no se admite crear ni editar recursos compartidos.

• Los contenedores Docker se pueden controlar, actualizar y eliminar, pero no crear ni editar.

• Las máquinas virtuales se pueden controlar, pero no crear, editar, clonar, crear instantáneas ni eliminar.

• No se publican mutaciones de apagado/reinicio del host.

• No se publican informes SMART completos ni controles de autoprueba SMART.

• restart de Docker se agregó después de la API v4.35.1 y no se usa intencionalmente en este objetivo de compatibilidad.

• Los tipos de respuesta de mutación de paridad están marcados como trabajo en progreso por Unraid.

Consulta docs/api-capabilities.md para ver las referencias oficiales y los detalles de compatibilidad.

Desarrollo

pnpm typecheck
pnpm test
pnpm build
# Or run all three:
pnpm verify

Las pruebas usan servidores HTTP locales simulados junto con clientes MCP en memoria y Streamable HTTP. No requieren Docker ni un servidor Unraid en vivo.

Lanzamientos de contenedores

GitHub Actions compila y analiza el contenedor en busca de vulnerabilidades para solicitudes de extracción y cambios en main, sin usar credenciales del registro. La publicación ocurre solo cuando se publica una versión semántica como v0.1.1. El flujo de trabajo de publicación analiza la imagen compilada antes de acceder al entorno protegido de dockerhub con DOCKERHUB_TOKEN, y luego publica las etiquetas de versión, commit y (para versiones estables) latest con atestaciones de SBOM y procedencia.

Notas de seguridad

• Stdio sigue siendo el valor predeterminado y no abre un puerto de red en escucha.

• El modo HTTP requiere autenticación de portador. Los tokens faltantes se generan con 256 bits de aleatoriedad criptográfica y se escriben deliberadamente en los registros de inicio.

• Los tokens generados son secretos operativos: restringe el acceso a los registros y configura MCP_AUTH_TOKEN para un despliegue estable.

• El modo HTTP valida los encabezados Host y Origin, limita los intentos de autenticación fallidos, limita el tamaño de los cuerpos de solicitud y usa por defecto la vinculación a loopback.

• El listener HTTP integrado no proporciona TLS. Usa un proxy inverso HTTPS y no lo expongas directamente a internet.

• Nunca escribe registros de aplicación en la salida estándar, que está reservada para MCP JSON-RPC.

• No acepta documentos GraphQL arbitrarios del modelo.

• No sigue redirecciones y limita el tamaño de la respuesta, el número de líneas de registro y la duración de las solicitudes.

• La cancelación del cliente aborta la solicitud HTTP local; las mutaciones ya aceptadas por Unraid no se pueden revertir.

• Los errores de GraphQL se redactan si contienen la clave de API configurada.

• Los números de serie de los discos, los registros, las direcciones de red y otros datos del servidor son visibles para el cliente de IA conectado. Revisa la política de manejo de datos de ese cliente.

Referencias oficiales

• Descripción general de la API de Unraid

• Cómo usar la API de Unraid

• Gestión programática de claves de API

• Hoja de ruta de la API de Unraid y soporte de versiones

• Esquema GraphQL generado de la API v4.35.1

• Guía de seguridad de conexión de Unraid

• Guía de stdio del SDK de MCP TypeScript

• Guía de HTTP Streamable del SDK de MCP TypeScript

• Configuración de MCP en Claude Code

• Configuración de MCP en Codex

Licencia

Este proyecto está bajo la Licencia MIT.