truenas-mcp

truenas-mcp

Conectar un NAS a un asistente de IA normalmente significa registrar una herramienta MCP por operación. Si cubres TrueNAS SCALE correctamente, eso son 50-80 esquemas de herramientas — alrededor de 28,000 tokens de tu ventana de contexto gastados antes de que el modelo haya leído una sola palabra de tu pregunta, en cada solicitud, toques o no el almacenamiento.

truenas-mcp cubre 278 acciones en 18 categorías — toda la API REST de TrueNAS SCALE — detrás de una herramienta jerárquica que cuesta alrededor de 200 tokens. El modelo pregunta qué categorías existen, profundiza en la que necesita y luego ejecuta la acción. Las operaciones destructivas se niegan a ejecutarse sin confirm: true.

Instalación (60 segundos)

# No install needed
TRUENAS_URL=https://truenas.local TRUENAS_API_KEY=1-abc123 npx truenas-mcp

Claude Code:

claude mcp add truenas -- npx -y truenas-mcp   --env TRUENAS_URL=https://truenas.local   --env TRUENAS_API_KEY=1-your-api-key-here

Obtén la clave API desde la interfaz de TrueNAS: Settings > API Keys > Add.

Cómo se ve

Tú: "¿Están sanos mis pools, y puedes crear un recurso compartido NFS para el dataset de medios?"

→ truenas({ category: "storage", action: "pool_list" })
  tank — ONLINE, 68% used, 0 errors

→ truenas({ category: "sharing", action: "nfs_share_create",
            params: { path: "/mnt/tank/media", comment: "Media share" } })

El modelo descubrió nfs_share_create llamando primero a truenas({ category: "sharing" }) — nunca tuvo esas 36 acciones de uso compartido en su prompt.

Por qué una herramienta en lugar de 278

	truenas-mcp	Servidor MCP NAS típico
Acciones	278	5-80
Huella de tokens	~200 tokens (1 herramienta)	5,000-30,000 tokens (50-80 herramientas)
Descubrimiento	Jerárquico — pide lo que necesitas	Plano — todo cargado de antemano
Recursos MCP	12 paneles de solo lectura	0
Instalación	npx truenas-mcp	Compilar desde el código fuente / pip
Seguridad	Las operaciones destructivas requieren confirm: true	Varía

Configuración completa

# Using npx (no install needed)
TRUENAS_URL=https://truenas.local TRUENAS_API_KEY=1-abc123 npx truenas-mcp

# Or install globally
npm install -g truenas-mcp

Variables de entorno

Variable	Requerida	Descripción
TRUENAS_URL	Sí	URL de la instancia de TrueNAS (p. ej., https://truenas.local)
TRUENAS_API_KEY	Sí	Clave API desde la interfaz de TrueNAS: Settings > API Keys > Add
TRUENAS_VERIFY_SSL	No	Establecer a false para omitir la verificación SSL (certificados autofirmados)

Configuración de Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "truenas": {
      "command": "npx",
      "args": ["-y", "truenas-mcp"],
      "env": {
        "TRUENAS_URL": "https://truenas.local",
        "TRUENAS_API_KEY": "1-your-api-key-here",
        "TRUENAS_VERIFY_SSL": "false"
      }
    }
  }
}

Claude Code

claude mcp add truenas -- npx -y truenas-mcp \
  --env TRUENAS_URL=https://truenas.local \
  --env TRUENAS_API_KEY=1-your-api-key-here \
  --env TRUENAS_VERIFY_SSL=false

Cómo funciona — Diseño de herramienta jerárquica

En lugar de registrar 278 herramientas individuales (lo que consumiría ~30k tokens en el prompt del sistema del LLM), este servidor expone una herramienta llamada truenas con tres modos de uso:

1. Descubrir categorías

truenas()

Devuelve las 18 categorías con descripciones y conteos de acciones (~200 tokens).

2. Explorar una categoría

truenas({ category: "storage" })

Devuelve todas las acciones en esa categoría con sus parámetros requeridos/opcionales.

3. Ejecutar una acción

truenas({ category: "storage", action: "pool_list" })
truenas({ category: "storage", action: "dataset_create", params: { name: "tank/media", compression: "LZ4" } })

Esto significa que el LLM solo paga el costo de tokens por lo que realmente usa.

Categorías

Categoría	Acciones	Cubre
system	24	Información del sistema, configuración, servicios, correo, claves API, NTP
storage	32	Pools, datasets, instantáneas, tareas periódicas de instantáneas
sharing	36	SMB/CIFS, exportaciones NFS, objetivos/extensiones/portales/iniciadores iSCSI
network	15	Interfaces, configuración global, rutas estáticas, IPMI, cambios por etapas
account	16	Usuarios, grupos, privilegios/roles
disk	7	Discos físicos, pruebas SMART, temperaturas
vm	16	Máquinas virtuales, dispositivos de VM (disco, NIC, pantalla, PCI)
app	17	Aplicaciones Docker, configuración del runtime de contenedores
update	14	Actualizaciones del sistema, entornos de arranque, pool de arranque
certificate	8	Certificados TLS, ACME/Let's Encrypt, autenticadores DNS
alert	10	Alertas, servicios de notificación (Slack, correo, PagerDuty)
data_protection	49	Replicación, sincronización en la nube, copia de seguridad en la nube, cron, rsync, scripts de inicio, claves SSH
filesystem	7	stat, listdir, mkdir, permisos, ACLs, chown
reporting	3	Configuración de métricas, gráficos, datos de series temporales
directory	8	Active Directory, LDAP, Kerberos
service_config	12	SSH, FTP, SNMP, UPS, ajustes del sistema
audit	3	Registros de auditoría, configuración de auditoría
api	1	Vía de escape de API cruda para cualquier endpoint

Recursos MCP (12)

Recursos de solo lectura para paneles — sin necesidad de llamada de herramienta:

Recurso	URI	Descripción
Información del sistema	truenas://system/info	Versión, nombre de host, tiempo de actividad, hardware
Pools	truenas://storage/pools	Todos los pools con capacidad y salud
Datasets	truenas://storage/datasets	Todos los datasets con propiedades
Servicios	truenas://services	Resumen del estado de los servicios
Alertas	truenas://alerts	Alertas actuales del sistema
Red	truenas://network/summary	Interfaces, IPs, DNS, puerta de enlace
Recursos compartidos	truenas://sharing	Todos los recursos compartidos SMB, NFS e iSCSI
VMs	truenas://vms	Máquinas virtuales con estado
Aplicaciones	truenas://apps	Aplicaciones instaladas
Discos	truenas://disks	Información de discos físicos
Entornos de arranque	truenas://boot/environments	Entornos de arranque
Actualización	truenas://system/update	Configuración de actualización

Conversaciones de ejemplo

"¿Qué pools tengo y están sanos?"

→ truenas({ category: "storage", action: "pool_list" })

"Crea un recurso compartido NFS para /mnt/tank/media"

→ truenas({ category: "sharing", action: "nfs_share_create", params: { path: "/mnt/tank/media", comment: "Media share" } })

"Comprueba si hay actualizaciones del sistema"

→ truenas({ category: "update", action: "update_check" })

"¿Qué pruebas SMART se han ejecutado en sda?"

→ truenas({ category: "disk", action: "disk_smart_test_list", params: { disk: "sda" } })

Seguridad

Todas las operaciones destructivas requieren confirm: true en los parámetros:

• Creación/exportación de pool, reemplazo de disco
• Eliminación de dataset/instantánea, reversión de instantánea
• Eliminación de VM, eliminación/reversión de aplicación
• Reinicio/apagado del sistema, aplicación de actualización
• Borrado de disco, conexión/desconexión de disco de arranque
• Eliminación de certificado, eliminación de entorno de arranque
• Salida de servicios de directorio, configuración de ACL

Sin confirm: true, estas acciones devuelven un mensaje de error explicando qué sucedería.

Compatibilidad de API

Construido para la API REST v2.0 de TrueNAS SCALE. Compatible con TrueNAS SCALE 22.x hasta 25.x.

Desarrollo

git clone https://github.com/spranab/truenas-mcp
cd truenas-mcp
npm install
npm run build
npm run dev  # watch mode

Proyectos relacionados

Otros servidores MCP e infraestructura de agentes construidos por el mismo autor:

• mcpier — plano de control MCP autoalojado para tu homelab; mantiene las claves API fuera de tus clientes.
• saga-mcp — rastreador de proyectos respaldado por SQLite para que el agente no pierda el plan entre sesiones.
• yantrikdb-mcp — memoria cognitiva persistente para Claude Code, Cursor y Windsurf.
• swarmcode — canal en tiempo real entre instancias de Claude Code en diferentes máquinas.
• brainstorm-mcp — debate multimodelo como herramienta MCP.

Licencia

MIT