unas-mcp

MCP server for managing a Ubiquiti UNAS Pro 8 NAS (6×26 TB RAID-6, ~104 TB usable) — health monitoring, storage/disk inventory, NFS export visibility, read-only file inspection, and gated lifecycle operations. 20 tools, deployed as a container on VM 102 (http://10.0.40.25:8490/mcp).

What it is

The UNAS Pro 8 exposes two independent surfaces, and this server is a thin, safety-gated layer over both:

• SSH (root@<host>, key-only, src/unas_mcp/ssh.py) — /proc/mdstat, smartctl, df, rpcinfo, exportfs, uptime/last, uname, and a handful of read-only filesystem commands (ls, du). This is the same transport docs/reference/unas-pro-8-capabilities.md (in the homelab repo) documents as voiding Ubiquiti's warranty — used here only where the UI and the Drive API cannot answer the question.

• UniFi Drive API (src/unas_mcp/api.py, unofficial/undocumented — findings in docs/drive-api-findings.md) — physical bay mapping (slotId), vendor healthScore/riskReasons, and per-RAID-group currentProtection vs expectedProtection. SSH's /proc/mdstat and smartctl are enough for pass/fail health, but they don't carry which physical bay to pull at the rack or the vendor's own risk scoring — that's the entire reason the Drive API transport exists in this server.

Every parser in this project is "tolerant but honest": a field genuinely absent from a live reply is surfaced as None (or raises, for the small set of fields health decisions are gated on), and is never silently defaulted to a value that reads as healthy (0, "ok", False, or a label count standing in for a verdict actually read). See api.py, parsers/smart.py, and tools/storage.py's module docstrings for the specific traps this pattern was built to close.

Related MCP server: unifi-mcp

Tool inventory (20 tools, 5 groups)

Tiers: read = no gate. direct = additive/trivially reversible, no gate. confirm = requires confirm="yes" (safety.requires_confirmation) — anything else raises PermissionError and issues no remote command.

Deliberate exclusions

Two categories of tool are absent by design, not merely unimplemented — their absence is the actual protection, not a confirmation prompt sitting in front of them:

• No write file operations. Not move, delete, copy, upload, or mkdir. The same bytes are already reachable through nine NFS client mounts with ordinary tools (mv, rm, cp, rsync, ...) — a second write path to the same ~75 TB of data only doubles the ways to corrupt it. See tools/files.py's module docstring. (unas_fix_permissions is the one narrow exception: a chown, not a data-touching write, and the only survivor of an investigated-and-cut NFS-allow-list write path — see tools/nfs.py's module docstring for why that one was rejected.)

• No pool or disk lifecycle tools at all — no create/destroy/format/ reshape/expand for pools, RAID groups, or disks. safety.py calls this the absent tier: "a confirmation prompt is a speed bump; absence is a wall." is_forbidden_tool_name() in safety.py is defence in depth on top of that absence (it blocks an obviously-named destructive tool from being registered by accident), but the real guarantee is the exact-match allowlist test (tests/test_health_tools.py:: test_registers_exactly_the_twenty_expected_tool_names) — any new tool, named anything, fails it until a human deliberately updates the expected set.

Environment contract

Development

python3.12 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest -v

Docker

docker build -t unas-mcp .

The image includes an openssh-client for the SSH transport.

Deployed

Live on VM 102 (10.0.40.25:8490), registered for Claude Code:

claude mcp add unas --transport http http://10.0.40.25:8490/mcp --scope user