omv-mcp
Provides safety-first administration of OpenMediaVault 8 over SSH or HTTP, including read-only inspection of system health, disks, filesystems, shares, users and groups, services, logs, plugins, network, firewall, certificates, and guarded plan/confirm tools for configuration changes.
Provides plugin-aware tools for inspecting WireGuard configuration and status on OpenMediaVault when the WireGuard plugin is installed, with dangerous WireGuard write operations not exposed.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
omv-mcp
A safety-first MCP server for administering OpenMediaVault 8 over SSH or HTTP.
Read-only by default. The server starts in the
readonlytier.Plan before write. Mutating tools return a diff and a single-use confirm token.
No implicit apply. OMV config changes stay dirty until you call
config_applywith an explicit module list.Audited and redacted. JSONL audit log, recursive secret redaction, protected users/groups, mutation rate limit.
Plugin-aware. Mergerfs, SnapRAID, compose, WireGuard, writecache and omv-extras tools are registered only when the plugin is installed.
Tested against a real OMV VM. Unit tests run offline; integration tests use a disposable OMV 8 VM in Docker with a hardcoded loopback guard.
Requirements
Python 3.12 or 3.13 and uv
OpenMediaVault 8.x (developed against 8.6.1)
SSH backend: root SSH access and a pinned
known_hostsentryHTTP backend: an OMV admin account without MFA enabled
The SSH backend is preferred: no OMV password is stored, and it does not hit MFA or web-session expiry.
Related MCP server: omv-mcp
Install
Run from a checkout:
git clone https://github.com/alex-rs/omv-mcp.git
cd omv-mcp
uv sync --extra dev
uv run omv-mcp --helpOr install the command from Git:
uv tool install git+https://github.com/alex-rs/omv-mcp
omv-mcp --helpThis project is not on PyPI. The omv-mcp package on PyPI is unrelated; do not use
uvx omv-mcp or pip install omv-mcp.
Configure
Configuration is environment variables or CLI flags; flags win. There is no config file. For a real NAS, start read-only:
export OMV_MCP_MODE=readonly
export OMV_MCP_BACKEND=ssh
export OMV_MCP_SSH_HOST=nas.example.lan
export OMV_MCP_SSH_PORT=22
export OMV_MCP_SSH_USER=root # v1 requires root
export OMV_MCP_SSH_KEY=~/.ssh/id_ed25519
export OMV_MCP_SSH_KNOWN_HOSTS=~/.ssh/known_hostsThe SSH backend validates the host key against OpenSSH's known_hosts; a missing or
untrusted entry fails closed. Add the NAS key with ssh-keyscan only after verifying
the fingerprint out of band.
Equivalent flags:
omv-mcp --backend ssh --host nas.example.lan --port 22 \
--ssh-key ~/.ssh/id_ed25519 --ssh-known-hosts ~/.ssh/known_hosts \
--mode readonlyHTTP backend
Use HTTPS outside the disposable test VM; a plain http:// URL sends the admin
password in clear text.
export OMV_MCP_BACKEND=http
export OMV_MCP_HTTP_URL=https://nas.example.lan
export OMV_MCP_HTTP_USERNAME=admin
export OMV_MCP_HTTP_PASSWORD=...
# export OMV_MCP_TLS_CA=/path/to/ca.pem # optional private CAIf OMV returns challengeRequired, MFA is enabled for that account. Use a dedicated
non-MFA admin or the SSH backend.
MCP client
Claude Code, using the installed command:
claude mcp add omv -- omv-mcp \
--backend ssh --host nas.example.lan --mode readonlyGeneric MCP client configuration:
{
"mcpServers": {
"omv": {
"command": "omv-mcp",
"args": [
"--backend", "ssh",
"--host", "nas.example.lan",
"--ssh-key", "~/.ssh/id_ed25519",
"--ssh-known-hosts", "~/.ssh/known_hosts",
"--mode", "readonly"
]
}
}
}To serve MCP itself over HTTP, set OMV_MCP_TRANSPORT=http and
OMV_MCP_HTTP_TOKEN (required). The default bind is 127.0.0.1:8000; non-loopback
binds without a token are refused. Put TLS in front of any remote deployment.
Modes
Mode | Adds |
| All read tools, including read-only |
| Share/user/group/cron/rsync edits, SMART and SnapRAID jobs, writecache flush, config apply/revert |
| Deletes, package/plugin installs, arbitrary non-read-only RPCs, and power (only with |
Dangerous methods (disk wipe, filesystem create/umount, network/firewall/SSH/WireGuard
writes, cterm, engine attach, and similar) are never exposed, even in admin.
Safety model
OMV set* RPCs only update config.xml and mark modules dirty; nothing is live until
Config.applyChanges. This server makes that explicit:
Inspect with
config_pendingand the relevant read tools.A write tool returns a plan: RPCs, before/after, side effects and dirty modules.
Re-call with
confirm_token. The token is HMAC-signed, bound to the tool and canonical arguments, expires in 5 minutes and is single-use.Execution re-checks the target and dirty-module set.
apply=trueis refused when unrelated modules were already dirty.Call
config_applywith the exact modules to deploy. It never applies everything.
Writes are audited to ~/.local/state/omv-mcp/audit.jsonl, redacted, and rate-limited.
Shared folders referenced by SMB/NFS/rsync/compose cannot be deleted. Protected users
and groups are configurable via OMV_MCP_PROTECT.
See SECURITY.md for the threat model and exclusions.
Settings
Variable | Default | Notes |
|
|
|
|
|
|
|
|
|
| — | Required for SSH |
|
| |
|
| Must be |
| OpenSSH default | Path; |
| OpenSSH default | Usually |
|
| User passed to |
| — | Required for HTTP backend |
|
| |
| — | Required for HTTP backend |
|
| Do not disable against a real NAS |
| — | Implies TLS verification |
| — | Required for HTTP transport |
|
| Registers |
|
| |
|
| Confirmed writes |
|
| Response cap |
Tool surface
docs/tools.md contains the generated reference, including tiers, RPCs and side
effects. The read-only surface covers:
system, CPU/top, time, services, logs, diagnostic report, RRD graphs
disks, filesystems, fstab, SMART, quotas and a composite health summary
shared folders, ACLs, snapshots, SMB/NFS/rsyncd shares
users and groups
cron, rsync and background jobs
apt updates/changelogs, plugins
network interfaces, firewall rules, certificates (public material only)
mergerfs, SnapRAID, compose, WireGuard and writecache (when installed)
Operators and admins additionally get the plan/confirm write tools.
Development
make check # ruff, mypy, unit tests, docs freshness
make smoke # read-only check against the test VM
OMV_MCP_TEST_VM=1 uv run pytest -m integrationThe test VM is a real OMV 8 VM running under QEMU/KVM inside Docker:
make testenv-build # download Debian cloud image, create disks
make testenv-provision # install OMV, plugins, seed state
make testenv-up # boot overlays from the seeded base
make testenv-reset # discard overlay writes
make testenv-destroy # remove all VM statemake testenv-* and the integration suite only target 127.0.0.1:2222 and
127.0.0.1:8080/8081/18080, with hostname omv-test. This guard applies to the
bundled tests and scripts, not to a server you configure yourself.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Hosted remote MCP for protected account access, permissions, activity history and supported undo.
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
SSH client, server management and one remote MCP URL for your machines, with human approvals.
Related MCP Servers
- AlicenseAqualityBmaintenanceA secure MCP server for managing OPNsense firewalls through AI assistants. Provides 81 tools across system, firewall, network, DNS, DHCP, VPN, HAProxy, services, diagnostics, and security domains.81317 PyPI27MIT
- AlicenseBqualityDmaintenanceExposes tools to manage and inspect an OpenMediaVault NAS, running on the NAS and communicating over SSH with any MCP-capable coding harness.48MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for comprehensive OPNsense firewall management, enabling AI assistants to manage firewall rules, NAT, VLANs, and network diagnostics, plus execute SSH/CLI commands. Supports safety modes like read-only and dry-run for safe operation.MIT
- AlicenseAqualityCmaintenanceAn MCP server that lets AI assistants manage an OpenMediaVault NAS over SSH using OMV's own RPC interface, covering disks, filesystems, shares, users, S.M.A.R.T. health, services, and configuration changes. It exposes a small set of generic tools to discover and call RPC methods, plus optional shell access.6MIT