truenas-mcp

truenas-mcp

Conectar um NAS a um assistente de IA geralmente significa registrar uma ferramenta MCP por operação. Para cobrir o TrueNAS SCALE adequadamente, isso resulta em 50 a 80 esquemas de ferramentas — cerca de 28.000 tokens do seu contexto gastos antes que o modelo leia uma única palavra da sua pergunta, em cada requisição, independentemente de você tocar no armazenamento ou não.

O truenas-mcp cobre 278 ações em 18 categorias — toda a API REST do TrueNAS SCALE — por trás de uma ferramenta hierárquica que custa cerca de 200 tokens. O modelo pergunta quais categorias existem, navega até a que precisa e então executa a ação. Operações destrutivas se recusam a rodar sem confirm: true.

Instalação (60 segundos)

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

Claude Code:

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

Obtenha a chave de API na interface do TrueNAS: Configurações > Chaves de API > Adicionar.

Como parece

Você: "Meus pools estão saudáveis, e você pode criar um compartilhamento NFS para o dataset de mídia?"

→ 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" } })

O modelo descobriu nfs_share_create chamando truenas({ category: "sharing" }) primeiro — ele nunca teve essas 36 ações de compartilhamento no prompt.

Por que uma ferramenta em vez de 278

	truenas-mcp	Servidor MCP NAS típico
Ações	278	5-80
Consumo de tokens	~200 tokens (1 ferramenta)	5.000-30.000 tokens (50-80 ferramentas)
Descoberta	Hierárquica — peça o que precisa	Plana — tudo carregado antecipadamente
Recursos MCP	12 painéis somente leitura	0
Instalação	npx truenas-mcp	Compilar a partir do código-fonte / pip
Segurança	Operações destrutivas exigem confirm: true	Varia

Configuração 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

Variáveis de ambiente

Variável	Obrigatória	Descrição
TRUENAS_URL	Sim	URL da instância TrueNAS (ex.: https://truenas.local)
TRUENAS_API_KEY	Sim	Chave de API da interface do TrueNAS: Configurações > Chaves de API > Adicionar
TRUENAS_VERIFY_SSL	Não	Defina como false para pular a verificação SSL (certificados autoassinados)

Configuração do Claude Desktop

Adicione ao seu 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 \
  --env TRUENAS_URL=https://truenas.local \
  --env TRUENAS_API_KEY=1-your-api-key-here \
  --env TRUENAS_VERIFY_SSL=false \
  -- npx -y truenas-mcp

Como funciona — Design de ferramenta hierárquica

Em vez de registrar 278 ferramentas individuais (o que consumiria ~30 mil tokens no prompt do sistema do LLM), este servidor expõe uma ferramenta chamada truenas com três modos de uso:

1. Descobrir categorias

truenas()

Retorna todas as 18 categorias com descrições e contagens de ações (~200 tokens).

2. Explorar uma categoria

truenas({ category: "storage" })

Retorna todas as ações dessa categoria com seus parâmetros obrigatórios/opcionais.

3. Executar uma ação

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

Isso significa que o LLM só paga o custo de tokens pelo que realmente usa.

Categorias

Categoria	Ações	Cobre
system	24	Informações do sistema, configuração, serviços, e-mail, chaves de API, NTP
storage	32	Pools, datasets, snapshots, tarefas periódicas de snapshot
sharing	36	SMB/CIFS, exportações NFS, alvos/extents/portais/iniciadores iSCSI
network	15	Interfaces, configuração global, rotas estáticas, IPMI, alterações em etapas
account	16	Usuários, grupos, privilégios/papéis
disk	7	Discos físicos, testes SMART, temperaturas
vm	16	Máquinas virtuais, dispositivos de VM (disco, NIC, display, PCI)
app	17	Aplicativos Docker, configuração do runtime de contêineres
update	14	Atualizações do sistema, ambientes de boot, pool de boot
certificate	8	Certificados TLS, ACME/Let's Encrypt, autenticadores DNS
alert	10	Alertas, serviços de notificação (Slack, e-mail, PagerDuty)
data_protection	49	Replicação, sincronização em nuvem, backup em nuvem, cron, rsync, scripts de inicialização, chaves SSH
filesystem	7	stat, listdir, mkdir, permissões, ACLs, chown
reporting	3	Configuração de métricas, gráficos, dados de séries temporais
directory	8	Active Directory, LDAP, Kerberos
service_config	12	SSH, FTP, SNMP, UPS, ajustes do sistema
audit	3	Logs de auditoria, configuração de auditoria
api	1	Saída de escape da API bruta para qualquer endpoint

Recursos MCP (12)

Recursos somente leitura para painéis — sem necessidade de chamada de ferramenta:

Recurso	URI	Descrição
Informações do sistema	truenas://system/info	Versão, hostname, tempo de atividade, hardware
Pools	truenas://storage/pools	Todos os pools com capacidade e saúde
Datasets	truenas://storage/datasets	Todos os datasets com propriedades
Serviços	truenas://services	Visão geral do status dos serviços
Alertas	truenas://alerts	Alertas atuais do sistema
Rede	truenas://network/summary	Interfaces, IPs, DNS, gateway
Compartilhamentos	truenas://sharing	Todos os compartilhamentos SMB, NFS e iSCSI
VMs	truenas://vms	Máquinas virtuais com status
Aplicativos	truenas://apps	Aplicativos instalados
Discos	truenas://disks	Informações dos discos físicos
Ambientes de boot	truenas://boot/environments	Ambientes de boot
Atualização	truenas://system/update	Configuração de atualização

Exemplos de conversas

"Quais pools eu tenho e eles estão saudáveis?"

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

"Crie um compartilhamento NFS para /mnt/tank/media"

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

"Verifique se há atualizações do sistema"

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

"Quais testes SMART foram executados em sda?"

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

Segurança

Todas as operações destrutivas exigem confirm: true nos parâmetros:

• Criar/exportar pool, substituir disco
• Excluir dataset/snapshot, reverter snapshot
• Excluir VM, excluir/reverter aplicativo
• Reiniciar/desligar sistema, aplicar atualização
• Apagar disco, anexar/desanexar disco de boot
• Excluir certificado, excluir ambiente de boot
• Sair de serviços de diretório, definir ACL

Sem confirm: true, essas ações retornam uma mensagem de erro explicando o que aconteceria.

Compatibilidade de API

Construído para a API REST v2.0 do TrueNAS SCALE. Compatível com TrueNAS SCALE 22.x até 25.x.

Desenvolvimento

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

Projetos relacionados

Outros servidores MCP e infraestrutura de agentes construídos pelo mesmo autor:

• mcpier — plano de controle MCP auto-hospedado para o seu homelab; mantém as chaves de API fora dos seus clientes.
• saga-mcp — rastreador de projetos com suporte a SQLite para que o agente não perca o plano entre sessões.
• yantrikdb-mcp — memória cognitiva persistente para Claude Code, Cursor e Windsurf.
• swarmcode — canal em tempo real entre instâncias do Claude Code em máquinas diferentes.
• brainstorm-mcp — debate multimodelo como ferramenta MCP.

Licença

MIT