Skip to main content
Glama

omv-mcp

A safety-first MCP server for administering OpenMediaVault 8 over SSH or HTTP.

  • Read-only by default. The server starts in the readonly tier.

  • 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_apply with 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_hosts entry

  • HTTP 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 --help

Or install the command from Git:

uv tool install git+https://github.com/alex-rs/omv-mcp
omv-mcp --help

This 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_hosts

The 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 readonly

HTTP 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 CA

If 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 readonly

Generic 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

readonly (default)

All read tools, including read-only rpc_call

operator

Share/user/group/cron/rsync edits, SMART and SnapRAID jobs, writecache flush, config apply/revert

admin

Deletes, package/plugin installs, arbitrary non-read-only RPCs, and power (only with OMV_MCP_ALLOW_POWER=true)

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:

  1. Inspect with config_pending and the relevant read tools.

  2. A write tool returns a plan: RPCs, before/after, side effects and dirty modules.

  3. 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.

  4. Execution re-checks the target and dirty-module set. apply=true is refused when unrelated modules were already dirty.

  5. Call config_apply with 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

OMV_MCP_MODE

readonly

readonly, operator, admin

OMV_MCP_BACKEND

ssh

ssh or http

OMV_MCP_TRANSPORT

stdio

stdio or http

OMV_MCP_SSH_HOST

—

Required for SSH

OMV_MCP_SSH_PORT

22

OMV_MCP_SSH_USER

root

Must be root in v1

OMV_MCP_SSH_KEY

OpenSSH default

Path; ~ expanded

OMV_MCP_SSH_KNOWN_HOSTS

OpenSSH default

Usually ~/.ssh/known_hosts; set explicitly for production

OMV_MCP_RPC_USER

admin

User passed to omv-rpc -u

OMV_MCP_HTTP_URL

—

Required for HTTP backend

OMV_MCP_HTTP_USERNAME

admin

OMV_MCP_HTTP_PASSWORD

—

Required for HTTP backend

OMV_MCP_TLS_VERIFY

true

Do not disable against a real NAS

OMV_MCP_TLS_CA

—

Implies TLS verification

OMV_MCP_HTTP_TOKEN

—

Required for HTTP transport

OMV_MCP_ALLOW_POWER

false

Registers system_power

OMV_MCP_AUDIT_PATH

~/.local/state/omv-mcp/audit.jsonl

OMV_MCP_RATE_LIMIT_PER_MINUTE

10

Confirmed writes

OMV_MCP_RESPONSE_MAX_BYTES

25000

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 integration

The 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 state

make 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      81
      317 PyPI
      27
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Exposes tools to manage and inspect an OpenMediaVault NAS, running on the NAS and communicating over SSH with any MCP-capable coding harness.
      48
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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
    • A
      license
      A
      quality
      C
      maintenance
      An 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.
      6
      MIT