ugnas-mcp

npx -y ugnas-mcp

A generic MCP (Model Context Protocol) server for UGREEN NAS devices running UGOS, talking to the NAS over SSH (with SFTP for file transfers).

Unlike most existing UGREEN NAS integrations, nothing here is hard-coded — no fixed IPs, subnets, usernames, or share names. Every target-specific value comes from your config, so the same server works for anyone's NAS.

What it does

Organized the way a NAS owner actually thinks about daily operations:

39 tools total. system.pools reports mdadm array + degradation state, LVM volume/logical/physical volumes, btrfs devices, block devices, and filesystems.

files.find searches a directory tree by name glob and/or extension (returns path, size, modified time). files.thumbnail renders a preview of an image or a video frame with ffmpeg on the NAS and downloads it locally — read-only with respect to your NAS data (only a /tmp scratch file is written and removed), but writing the thumbnail to the local machine is gated: the first call returns a dry-run plan, and you confirm with the token to write the local file. Requires ffmpeg on the NAS (present on UGOS by default).

files.list and files.find prefer GNU coreutils flags (ls --time-style=long-iso, find -printf); when those are unavailable (BusyBox), they fall back to ls -1p and find -exec stat so they keep working — with size/mtime zeroed out for plain ls where BusyBox can't report them.

files.sync and the rsync fallback

files.sync uses rsync for fast, resumable NAS↔NAS copies, with --delete mirroring and an rsync --dry-run pre-flight. rsync is not installed on UGOS by default, so:

• Default (fallback: "refuse") — if rsync is missing, the dry-run plan still shows the rsync command but adds a note telling you how to install rsync (Entware: opkg install rsync) or how to turn on the fallback. Nothing runs until you confirm.
• Opt in (fallback: "cp") — the tool instead falls back to a built-in cp -a copy. The plan's note explains this, and warnings call out what the fallback can't do: no --delete mirroring, no rsync --dry-run, and extraArgs are ignored.

So you opt in per call by passing fallback: "cp". Nothing changes unless you ask for it.

Safety model — dry-run first, then confirm

Every mutating tool has two phases:

1. Call without a token → returns a dry-run plan: the exact shell commands it would run, a human summary, any warnings, and a short-lived confirmationToken.
2. Call again with confirmToken → the token is validated (action-bound, single-use, expires in 10 minutes) and the exact commands captured at plan time are executed.

Read-only tools never need a token. This makes "copy my data", "pull this image", or "restart that container" reviewable before anything changes.

All user-supplied values (paths, container names, image tags) are POSIX-shell-quoted before being interpolated into a remote command, so they cannot break out into arbitrary command execution.

At confirm time, the arguments of the confirming call are cross-checked against the plan-time arguments captured in the token: if they differ, the tool refuses and asks you to re-run for a fresh plan (so a stale token can never execute a differently-argued action).

Configuration

The server reads a JSON config from ~/.ugnas-mcp/config.json (override with the UGNAS_MCP_CONFIG environment variable). See config.example.json.

{
  "name": "home-nas",
  "host": "192.168.1.50",
  "port": 22,
  "username": "admin",
  "auth": { "type": "key", "privateKeyPath": "~/.ssh/id_ed25519" },
  "defaultShare": "/volume1",
  "commandTimeoutMs": 60000
}

Environment-variable overrides

Useful for CI or secret injection. Env values win over the file:

UGNAS_HOST=192.168.1.50
UGNAS_PORT=22
UGNAS_USER=admin
UGNAS_KEY_PATH=~/.ssh/id_ed25519      # or UGNAS_AUTH_TYPE=password + UGNAS_PASSWORD
UGNAS_DEFAULT_SHARE=/volume1
UGNAS_HOST_KEY_SHA256=SHA256:...

Relative vs absolute paths

File/backup tools accept either. An absolute path is used as-is; a relative path is joined onto defaultShare:

files.list("media")  ->  /volume1/media
files.list("/mnt/x")  ->  /mnt/x

Install & run

Published on npm as ugnas-mcp. Run it directly — no clone, no build:

npx ugnas-mcp
# or install it once:
npm install -g ugnas-mcp
ugnas-mcp

That starts the stdio MCP server. It reads its config from ~/.ugnas-mcp/config.json (or UGNAS_MCP_CONFIG / UGNAS_* env vars — see Configuration).

Wiring it into an MCP client

Point your client at the official package (stdio):

{
  "mcpServers": {
    "ugnas": {
      "command": "npx",
      "args": ["-y", "ugnas-mcp"],
      "env": { "UGNAS_MCP_CONFIG": "/absolute/path/to/config.json" }
    }
  }
}

Or, if you installed it globally, "command": "ugnas-mcp" with no args.

Optional HTTP transport

The server is stdio by default. Set UGNAS_HTTP_PORT to also expose a streamable HTTP transport (both run side by side):

UGNAS_HTTP_HOST=127.0.0.1 UGNAS_HTTP_PORT=4110 ugnas-mcp

• POST http://127.0.0.1:4110/mcp — JSON-RPC (stateless; a fresh session per request, max 1 MiB body).
• GET http://127.0.0.1:4110/health — liveness + target host.

It binds to loopback by default. UGNAS_HTTP_HOST=0.0.0.0 (or any non-loopback address) is refused unless UGNAS_HTTP_ALLOW_REMOTE=1 is also set — the /mcp endpoint has no authentication, and confirmation tokens are process-wide, so only opt in if the port is secured by something else (reverse proxy with auth, VPN, etc.).

Prerequisites on the NAS

• SSH enabled (UGOS: Control Panel → Terminal & SNMP).
• The SSH user can run docker (be in the docker group) and, for scheduled backups, use crontab.
• tar, df, du, ip, ss are present on UGOS — these are standard.
• backup.schedule job names must be plain words ([A-Za-z0-9._-]) — they are embedded in a generated shell script and a crontab line, so anything else is rejected up front.
• rsync is optional, used only by files.sync. If it's missing you get a note explaining how to install it or how to enable the built-in cp fallback (files.sync { fallback: "cp" }); every other file tool works without rsync.

License

MIT — see LICENSE. Contributing, architecture, and the dev/release toolchain live in DEVELOPMENT.md.