omv-mcp

An MCP server that lets an AI assistant manage an OpenMediaVault NAS — check disks and filesystems, inspect shares and users, read S.M.A.R.T. health, restart services, apply configuration changes, run background jobs and tail their output.

It connects over plain SSH and drives OMV's own omv-rpc CLI, which is the exact same RPC layer the web interface uses. Nothing gets installed on the NAS and no extra port is opened.

MCP client  --stdio-->  omv_mcp.py  --ssh-->  NAS  -->  omv-rpc  -->  OMV RPC layer
 (your PC)              (your PC)                        (the same layer as the web UI)

No dependencies. The server is pure standard library — including its MCP protocol layer — so there is no virtualenv to create, nothing to pip install, and it runs on any Python 3.9 or newer.

Why only six tools

OMV exposes roughly 50 RPC services with several hundred methods between them, and every plugin adds more. Rather than wrapping each one in a hand-written tool, omv-mcp exposes a small generic set: discover the services, discover a service's methods, call a method. The assistant explores the API the same way a developer would.

The practical benefit: any plugin you install later — Docker/Compose, ZFS, K8s, whatever — works immediately, with no update to this server.

Related MCP server: Simple SSH MCP Server

Requirements

Developed and verified against OpenMediaVault 8.5.6-1 (Synchrony) on Debian 13. OMV 7 uses the same RPC layer and is expected to work; reports welcome.

Install as a Claude Desktop extension (recommended)

The extension gives you a settings panel — NAS address, SSH user, key, read-only mode — so nothing has to be edited in any file.

1. Download omv-mcp-<version>.mcpb from the latest release.

2. Double-click it, or drag it onto the Claude Desktop window. (Also available under Settings → Extensions → Advanced settings → Install Extension…)

3. Fill in at least the NAS hostname or IP address, then enable the extension.

Read-only mode is on by default. Turn it off once you are comfortable letting Claude change things.

You still need working SSH key access to the NAS — see SSH setup below.

Building the bundle yourself

git clone https://github.com/mbgroen/omv-mcp.git
cd omv-mcp
python3 scripts/build_mcpb.py

The .mcpb lands in dist/. It is an ordinary zip archive with a manifest.json at the root, so the build script needs nothing but the standard library — no Node.js, no mcpb CLI.

Install manually

Useful for Claude Code, for other MCP clients, or if you would rather not use an extension.

git clone https://github.com/mbgroen/omv-mcp.git

There is nothing to install. Point your client at omv_mcp.py with your system Python.

Claude Code:

claude mcp add openmediavault -e OMV_SSH_HOST=192.168.1.100 -e OMV_READONLY=1 -- python3 "$PWD/omv_mcp.py"

Claude Desktop, in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "openmediavault": {
      "command": "python3",
      "args": ["/absolute/path/to/omv-mcp/omv_mcp.py"],
      "env": {
        "OMV_SSH_HOST": "192.168.1.100",
        "OMV_SSH_USER": "root",
        "OMV_RPC_USER": "admin",
        "OMV_READONLY": "1"
      }
    }
  }
}

Use absolute paths, not ~. Restart the client completely afterwards — closing the window is not enough for Claude Desktop.

Environment variables

The extension sets these for you; this table is for manual setups.

Booleans accept 1/true/yes/on and their opposites.

SSH setup

The server runs ssh with BatchMode=yes, so password logins will not work. This is deliberate: an MCP server has no way to prompt you for a password. Use a key.

ssh-keygen -t ed25519 -C "omv-mcp"        # skip if you already have a key
ssh-copy-id root@192.168.1.100            # use your own NAS address
ssh root@192.168.1.100 'omv-rpc -u admin System getInformation'

If that last command prints JSON, the server will work.

Root login refused? OMV disables SSH root login by default. Either enable it under Services → SSH → Permit root login, or use your own account and turn on sudo — that account needs to be in the sudo group.

Because ~/.ssh/config is honoured, you can keep the details there instead:

Host nas
    HostName 192.168.1.100
    User root
    IdentityFile ~/.ssh/id_ed25519

and then use nas as the hostname.

Verify

Ask your assistant "Is my OMV connection working?". It should call omv_connection_info and report your OMV version.

Tools

omv_call

The workhorse. Takes a service, a method, and optionally a parameter dict:

omv_call("System", "getInformation")
omv_call("FileSystemMgmt", "enumerateMountedFilesystems", {"includeRoot": True})
omv_call("ShareMgmt", "enumerateSharedFolders")
omv_call("Smart", "getListBg", {"start": 0, "limit": -1})

A few services to know about:

Rather than memorising these, let the assistant call omv_list_services and omv_list_methods — that always reflects your actual installation.

Background jobs

Heavier methods return {"filename": "..."} and keep running on the NAS. Pass that filename to omv_wait_for_task, which polls until the job finishes and returns the accumulated output:

result = omv_call("Apt", "upgrade")           # -> {"filename": "/tmp/bgstatus..."}
omv_wait_for_task(result["filename"], max_seconds=600)

omv_shell

An escape hatch for everything outside the RPC layer — journalctl, docker ps, smartctl, package state. Prefer omv_call for anything OMV manages itself, so OMV's configuration database stays in sync with the system. Disabled by default in the extension.

Security

This server can do anything you can do in the OMV web interface, and — if you enable the shell tool — run arbitrary commands as root. That is the point of it, but be clear-eyed about what it means: the only thing standing between a mistaken suggestion and a wiped filesystem is the tool confirmation dialog in your MCP client. Read what it says before approving.

Sensible precautions:

• Keep read-only mode on until you have a feel for what the assistant does with it.

• Leave the shell tool off unless you actually need it.

• Use a dedicated SSH key for this server rather than your everyday key.

• Consider a non-root user with sudo and a narrowed sudoers rule.

• Keep it on your LAN. There is no authentication in this server itself; its security boundary is your SSH configuration.

Read-only mode uses a prefix heuristic — a method is allowed if its name starts with get, enumerate, list, is, has, read, query, find, exists, count or check. It is deliberately conservative and will occasionally block a harmless method. It is a guard rail, not a security boundary: it cannot stop a read method that happens to have side effects.

Service and method names are validated against ^[A-Za-z0-9_]+$ and every value interpolated into a shell command is passed through shlex.quote, so parameters cannot break out into the shell.

How it works

Discovery

An RPC service's name is not its file name — it is whatever the PHP getName() method returns. So omv_list_services greps the sources in /usr/share/openmediavault/engined/rpc/ and reads the names out. The result is cached for the lifetime of the process; restart the server after installing a plugin.

Three details about OMV's sources that this parser handles, and which are easy to get wrong if you write your own:

1. Quoting is inconsistent. OMV's PHP mixes ' and " freely. On OMV 8.5, six of the 52 service names and about a third of all registerMethod() calls use single quotes. Matching only double quotes silently loses them.

2. Some service names are lowercase — kernel and omvextras, for instance — and omv-rpc is case sensitive. Use names exactly as omv_list_services returns them.

3. One file can hold several RPC classes. notification.inc defines both Notification and EmailNotification, so methods are scoped to the class block they appear in rather than to the whole file.

Errors are cleaned up too: a failed omv-rpc call writes a JSON blob to stderr containing a full PHP stack trace, and only the message field is surfaced.

The MCP layer

mcp_stdio.py implements the protocol directly: newline-delimited JSON-RPC 2.0 over stdio, initialize with version negotiation, tools/list with input schemas derived from each function's signature and docstring, and tools/call.

That is a deliberate choice rather than an exercise. The official MCP Python SDK depends on pydantic, which ships compiled binaries — and the MCPB documentation is explicit that you cannot portably bundle compiled dependencies. Implementing the handful of methods a tools-only server needs keeps the extension a single 26 KB file that works on macOS, Windows and Linux alike, with no runtime to install and no Python version floor beyond 3.9.

Tests

No dependencies, nothing to install:

python3 -m unittest discover -s tests -t tests -v

Or with pytest, if you prefer its output:

pip install pytest && pytest

The fixtures under tests/fixtures/ are real output captured from an OpenMediaVault 8.5.6-1 system (grep dumps of the RPC sources, a successful RPC response and an error response), with host-identifying values replaced. The tests therefore assert against what a NAS actually returns rather than against an idealised sample.

Troubleshooting

Claude Desktop writes per-server logs to ~/Library/Logs/Claude/mcp-server-openmediavault.log on macOS.

Contributing

Issues and pull requests are welcome — particularly reports from OMV 7, from plugins whose RPC sources are laid out unusually, and from setups where discovery finds fewer services than the web UI offers.

Please run the test suite before opening a PR. If you are fixing a parsing issue, add a fixture captured from the real system alongside it; that is how the existing tests are built.

License

MIT — see LICENSE.

This project is not affiliated with or endorsed by the OpenMediaVault project.