truenas-mcp

Conectar un NAS a un asistente de IA normalmente implica registrar una herramienta MCP por operación. Si cubres TrueNAS SCALE correctamente, eso son 50-80 esquemas de herramientas — unos 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 petición, 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 unos 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.

Related MCP server: Proxmox MCP Server

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

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

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 recuentos de acciones (~200 tokens).

2. Explorar una categoría

truenas({ category: "storage" })

Devuelve todas las acciones de esa categoría con sus parámetros obligatorios/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 coste de tokens por lo que realmente utiliza.

Categorías

Recursos MCP (12)

Recursos de solo lectura para paneles — no se necesita ninguna llamada de herramienta:

Ejemplos de conversaciones

"¿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:

• Crear/exportar pool, reemplazar disco

• Eliminar dataset/instantánea, revertir instantánea

• Eliminar VM, eliminar/revertir aplicación

• Reiniciar/apagar el sistema, aplicar actualización

• Borrado de disco, conectar/desconectar disco de arranque

• Eliminar certificado, eliminar entorno de arranque

• Abandonar servicios de directorio, establecer ACL

Sin confirm: true, estas acciones devuelven un mensaje de error que explica lo que ocurriría.

Compatibilidad de API

Diseñado para la API REST de TrueNAS SCALE v2.0. 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 creados 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