Agenten stärken
Installation vom Herausgeber. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
Noch kein paketiertes Release in der Registry. Folgen Sie der README des Repositorys.
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenVom Herausgeber
CLI, MCP server, and Rust client library for managing UGREEN NAS (UGOS) devices.
UGOS ships a web UI but no CLI and no API documentation. Reaching past it with / makes UGOS lose track of its own VMs, so this project drives the same (undocumented) API the web UI uses — reverse-engineered from its bundles and verified against real hardware.
CLI, MCP server, and Rust client library for UGREEN NAS (UGOS) management
virshqemuCovers virtual machines, Docker, files, downloads, system monitoring, logs and users.
⚠️ Work in Progress — A large subset of the UGOS API, not all of it. See the implementation status for what is covered and what is deliberately left out.
# Set credentials (or use --host, --user, --password flags)
export UGOS_HOST=192.168.1.10
export UGOS_USER=admin # UGOS_USERNAME works too
export UGOS_PASSWORD=<password>
# List VMs
ugos-cli vm list
# Show VM details
ugos-cli vm show CachyOS
# Power management
ugos-cli vm start CachyOS
ugos-cli vm stop CachyOS
ugos-cli vm stop --force CachyOS
# Snapshots
ugos-cli vm snapshot list CachyOS
ugos-cli vm snapshot create CachyOS # UGOS names it after the creation time
# Create a VM
ugos-cli vm create debian --cores 4 --memory 8g --disk 50g \
--iso /volume1/iso/debian.iso
# Print the request body instead of creating anything (works offline)
ugos-cli vm create debian --cores 4 --memory 8g --disk 50g --dry-run
# Upload an ISO, from a local file or a URL
ugos-cli image upload ~/Downloads/debian.iso
ugos-cli image upload https://example.org/debian.iso --name debian-13
# Host load and all VMs in one call
ugos-cli overview
# System log, filterable — the KVM audit log is `vm log`
ugos-cli log --module login --size 10
ugos-cli vm log list
# User accounts
ugos-cli user list
ugos-cli user me
# Browse the NAS
ugos-cli fs ls /volume1/download
ugos-cli fs volumes
ugos-cli fs put ./backup.tar.gz /volume1/backups
ugos-cli fs get /volume1/backups/backup.tar.gz
# Filesystem snapshots of shares and home folders (not VM snapshots)
ugos-cli snapshot folders
ugos-cli snapshot list backup
ugos-cli snapshot create backup --desc "before the migration"
ugos-cli snapshot clone backup 3 backup-recovered
# Let the NAS fetch a file straight from the internet
ugos-cli download add https://example.org/big.iso
ugos-cli download list
# NAS hardware, firmware and live readings
ugos-cli system info
ugos-cli system stat
ugos-cli system processes --limit 10
# How much space KVM uses, per volume and per VM
ugos-cli storage df
# Docker containers
ugos-cli docker ps
ugos-cli docker show nginx
ugos-cli docker create nginx --image nginx:latest --publish 8080:80
ugos-cli docker start nginx
ugos-cli docker logs nginx
# Docker images and compose projects
ugos-cli docker images
ugos-cli docker pull redis:7
ugos-cli docker project-ls
ugos-cli docker project-create myapp --file ./compose.yaml
# Passthrough hardware
ugos-cli usb list
ugos-cli passthrough list
# Remote console
ugos-cli vnc list
ugos-cli vnc generate CachyOS
# Other resources
ugos-cli network list
ugos-cli storage list
ugos-cli image list
ugos-cli info
# JSON output, for scripting
ugos-cli -o json vm list
Every command group has more than is shown here; ugos-cli <group> --help
lists the rest.
use ugos_client::{UgosClient, Credentials};
use ugos_client::api::kvm::KvmApi;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let creds = Credentials {
username: "admin".into(),
password: "<password>".into(),
};
let client = UgosClient::connect("192.168.1.10", 9443, creds).await?;
let vms = client.vm_list().await?;
for vm in &vms {
println!("{}: {}", vm.vir_display_name, vm.status);
}
Ok(())
}
Configure in your MCP client (e.g. Kiro, Claude Desktop):
{
"mcpServers": {
"ugos": {
"command": "ugos-mcp",
"env": {
"UGOS_HOST": "192.168.1.10",
"UGOS_USER": "admin",
"UGOS_PASSWORD": "<password>"
}
}
}
}
Multiple NAS targets are supported:
{
"mcpServers": {
"ugos": {
"command": "ugos-mcp",
"env": {
"UGOS_HOST_1": "192.168.1.10",
"UGOS_USER_1": "admin",
"UGOS_PASSWORD_1": "<password>",
"UGOS_NAME_1": "nas1",
"UGOS_HOST_2": "192.168.1.11",
"UGOS_USER_2": "admin",
"UGOS_PASSWORD_2": "<password>",
"UGOS_NAME_2": "nas2"
}
}
}
}
vm create and vm update map directly onto the fields of the
CreateVirtualMachine and UpdateVirtualMachine request bodies and take the
same flags. Device flags are repeatable and take either a short form or a
key=value,... list; sizes accept k, m, g and t suffixes, and a bare
number means MiB. UGOS itself counts in KiB — the CLI converts, so --disk 40g
really is 40 GiB.
# Two disks on different buses, two NICs, two ISOs, USB passthrough
ugos-cli vm create win11 \
--os windows --os-version win11 \
--cores 8 --memory 16g \
--disk size=60g,bus=ide \
--disk size=500g,bus=sata \
--iso /volume1/iso/win11.iso \
--iso /volume1/iso/virtio-drivers.iso \
--nic name=vnet-bridge0,type=e1000e \
--nic name=vnet-nat,type=e1000e,mac=52:54:00:12:34:56 \
--usb vendor-id=0x8087,product-id=0x0033,bus-id=1,device-id=4 \
--graphics qxl --keyboard de --autostart
On create, device names (vda, sda, hda, …) are derived from the bus
type and boot order is numbered disks-first, unless dev= or order= says
otherwise. On update, a newly added disk is left unnamed on purpose, because
UGOS insists on naming it (see below). --usb and --share also accept a raw
JSON object when the generated body needs to look different.
vm update starts from the VM's current configuration, so only what a flag
names is changed and everything else is sent back verbatim. The VM has to be
shut off — UGOS answers 3002, Fail to edit virtual machine for a running one
— and its UUID is always the one of the VM named on the command line.
Besides the flags above, which replace a whole device list, update edits
lists incrementally. --set-* picks the entry to change with a match=
selector (disk by dev, ISO by dev or path, NIC by name or MAC):
# Grow a disk, keeping its backing file
ugos-cli vm update CachyOS --set-disk match=vda,size=200g
# Attach a second disk and an install ISO, drop a NIC
ugos-cli vm update CachyOS \
--add-disk 500g \
--add-iso /volume1/iso/rescue.iso \
--rm-nic vnet-nat
# Plain resource changes
ugos-cli vm update CachyOS --cores 8 --memory 32g --autostart
# Preview instead of sending
ugos-cli vm update CachyOS --set-nic match=vnet-bridge0,type=e1000 --dry-run
Edits run in the order remove, set, add, so a --rm-disk vdb --add-disk 100g
pair really does replace that disk rather than cancelling out — though for a
pure resize --set-disk is the better tool, since it keeps the existing
backing file instead of starting from an empty one. A selector that matches
nothing is an error rather than a silent no-op.
Anything the flags do not cover can come from a full JSON spec, which the flags
then override. For create, --dry-run prints the request body instead of
sending it and needs no NAS connection, so specs can be built and inspected
offline; for update it still reads the VM's current configuration first.
# Clone the configuration of an existing VM under a new name
ugos-cli -o json vm show CachyOS > spec.json
ugos-cli vm create CachyOS-2 --spec-file spec.json --memory 32g
# Import an OVA (parse, then create from the parsed spec)
ugos-cli -o json ova parse /volume1/ova/appliance.ova > spec.json
ugos-cli vm create appliance --spec-file spec.json
# Inspect what would be sent
ugos-cli vm create test --spec-file - --dry-run < spec.json
A repeatable flag replaces the corresponding list from the spec file rather
than appending to it. The UUID in a spec file is never used: create always
generates a fresh one, and update always keeps the one of the VM it was
pointed at.
create and update were verified end to end against a real NAS (UGOS app
build 656, 2026-08-18): a VM is created and starts; CPU, memory and disk size
are changed and it starts again; a second disk is added and removed; it is
renamed, force-stopped and deleted. Five findings from those runs are baked
into the client:
keyboardLanguage must be a real QEMU keymap. The web UI sends
en-us; a plain en is accepted by CreateVirtualMachine and then makes
every start fail with 3037, Failed to start.storageUUID is mandatory on CreateVirtualMachine — without it the
answer is 3000, Fail to create virtual machine. The client resolves it
from storage_name, so --storage volume1 is enough, but a --dry-run
body shows it empty because resolving needs the NAS.virtualMachineName in the
body, so vm create reports the UUID it finds in the listing afterwards.dev nor path. UGOS assigns
both and answers 3002, Fail to edit virtual machine when the body names
them itself, so vm create names its disks and vm update leaves new ones
unnamed. Growing an existing disk with --set-disk keeps its backing file.One difference to the web UI remains: it picks defaults per OS type that
this CLI does not — ide plus an e1000e NIC for Windows and other,
virtio for Linux. vm create always defaults to virtio, so a Windows
guest without virtio drivers needs
--disk size=60g,bus=ide --nic name=vnet-bridge0,type=e1000e.
Where UGOS answers with a bare code, the client asks the validators the web UI
uses and turns the answer into something readable: a taken VM or network name,
a VM asking for more memory than the host has, or a network still attached to
VMs. Note that CreateVirtualMachine does not check memory itself — such a VM
is created and only fails to start.
Still inferred. USB passthrough and shared-directory bodies have never been sent to a NAS, and a second NIC was accepted but not exercised on a running guest. Use
--dry-runto inspect a body before sending it.
brew install metaneutrons/tap/ugos-cli
Take the .deb for your architecture from the
latest release and
install it with apt, which resolves dependencies for a local file too:
sudo apt install ./ugos-cli_<version>_amd64.deb
An APT repository under deb.metaneutrons.cc is being prepared. It does not
serve yet, so do not add it as a source.
There is no AUR package yet. Use the Linux archive from the releases page.
Every release carries binaries for Linux, macOS and Windows, each on x86_64 and
aarch64, plus .deb packages for amd64 and arm64. See the
releases page.
See docs/packaging.md for how these are built and verified.
cargo install --git https://github.com/metaneutrons/ugos-cli ugos-cli
cargo install --git https://github.com/metaneutrons/ugos-cli ugos-mcp
The crates are not published on crates.io. Depend on the repository directly:
[dependencies]
ugos-client = { git = "https://github.com/metaneutrons/ugos-cli", tag = "v0.9.0" }
UGOS publishes no API documentation, so everything here was reconstructed from the web UI's JavaScript bundles and verified against real hardware. The notes are kept because the reasoning is easy to lose and expensive to redo.
Docker container create/update were reverse-engineered against the real
CreateContainer request body (live-captured 2026-08-06, see
docs/api-docker.md) — this caught two bugs that had never actually
been exercised against a live NAS: port_mapping was built with wrong field
names (hostPort/protocol instead of the real nasPort/portType), and
subnet_settings/gpu_ids were entirely missing from ContainerDetail.
Both are fixed now; the CLI's docker container create --port flag has been
tested end-to-end against a real NAS (nginx container, port mapping,
env vars).
Docker compose project management (create/list/show/stop/remove) was
reverse-engineered against the live CreateProject/GetProjectListV3/
StopProject/DownProject endpoints (live-captured 2026-08-07, see
docs/api-docker.md) and tested end-to-end on a live NAS (a two-service
nginx+redis project, created, verified running, stopped, and removed). The
start/restart endpoints (StartProject/RestartProject) are implemented
by analogy with StopProject and the container-level start/restart pattern
but have not been live-verified — confirm before relying on them for
anything critical.
UGOS uses a multi-step auth flow:
POST /verify/check returns an RSA public keyPOST /verify/login returns a session token + cookies?token= query parameterThe client handles this automatically, including transparent re-authentication when tokens expire (UGOS error code 1024).
UGOS serves a self-signed X.509 version 1 certificate, which no ordinary
certificate parser will accept. Rather than trusting whatever is presented,
the client pins the certificate on first contact and refuses anything else
afterwards, the way SSH treats host keys. Fingerprints are stored per
host:port in known_hosts.json in the user's config directory.
The first connection is only as trustworthy as the network it happens on, so the fingerprint is printed for comparison against the device. The handshake signature is verified against the pinned certificate's own key, which is what makes the pin meaningful — see docs/api-tls.md for why that needs handling by hand, and why requests are not all encrypted.
UGOS moves fields around between builds, so a mismatch is worth reporting.
virID vanished from the VM listing in one such build and broke vm list
until every field but the name was made optional.
vm, network, storage, image, usb, vnc and ova;
the Docker app for docker. The remaining groups need neither.This project is licensed under the GNU General Public License v3.0,
the ugos-client library included. A library would ordinarily be the place for
the weaker copyleft of the LGPL; here it is not, because the library serves this
project's own programs and every release so far has been GPL.
CLI, MCP server, and Rust client library for UGREEN NAS (UGOS) management
Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Ugos Cli läuft lokal über stdio.
Zuletzt geprüft: 2026-11-13. CLI, MCP server, and Rust client library for UGREEN NAS (UGOS) management
