omv-mcp

An MCP server that lets an AI assistant manage an OpenMediaVault NAS.

Ask in plain language — "which disks are unhealthy?", "why is the SMB share not mounting?", "restart file sharing" — and the assistant works through OpenMediaVault's own API to answer or act.

It connects over ordinary SSH and drives omv-rpc, the command-line tool that ships with OpenMediaVault. That is the same RPC layer the web interface uses, so anything you can do by clicking, the assistant can do too. Nothing is 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)

Works with any MCP client. This is a plain stdio MCP server with no client-specific behaviour: Claude Desktop, Claude Code, Cursor, Zed, Cline, VS Code, the OpenAI Agents SDK and anything else that speaks the protocol can all run it. Any client needs the same three things — a Python interpreter, the path to omv_mcp.py, and a handful of environment variables.

For Claude Desktop specifically there is also a prebuilt .mcpb extension file. It contains that very same server, wrapped so the app can install it in one click and give you a settings panel instead of a config file to edit. It is a convenience, not a different product — and not a requirement.

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.

---

What it can do

Six tools, and between them they reach the whole of OpenMediaVault:

Tool	Purpose
omv_connection_info	Show the active configuration and test connectivity
omv_list_services	List every RPC service, including ones added by plugins
omv_list_methods	List the methods of one service
omv_call	Call an RPC method — the main tool
omv_wait_for_task	Collect the output of a background job
omv_shell	Run an arbitrary shell command on the NAS (off by default)

In practice that covers disks and S.M.A.R.T. health, filesystems and mount points, shared folders and their permissions, users and groups, the file-sharing services (SMB, NFS, FTP, rsync), network settings, scheduled jobs, package updates, and applying pending configuration changes.

Why only six tools

OpenMediaVault 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 stays generic: discover the services, discover a service's methods, call a method. The assistant explores the API the way a developer would, starting from what your particular installation actually offers.

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

---

Requirements

NAS	OpenMediaVault 7 or 8, reachable over SSH
Your computer	Python 3.9 or newer
MCP client	Any client that can run a stdio MCP server
Access	An SSH key that logs in to the NAS without a password, and an account that may run omv-rpc

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.

Platform support

Your computer	Extension (.mcpb)	Manual setup	Notes
macOS	Yes	Yes	Python 3.9 ships with the system; ssh is present
Windows	Yes	Yes	Python is not included — install it from python.org or the Microsoft Store first. ssh ships with Windows 10 1809 and later.
Linux	—	Yes	Claude Desktop is released for macOS and Windows only, so there is no extension to install. Everything else works: use Claude Code or any other MCP client.

The server is verified on macOS (Python 3.9) and Linux (Python 3.13). Windows is covered by CI but has not been run against a real NAS — reports welcome.

---

Two ways to install

Both routes install the same server. Pick one:

	Use this when	What you get
Claude Desktop extension	You use Claude Desktop on macOS or Windows	One click, and a settings panel instead of a config file to edit
Manual setup	Any other client, or Linux	Clone the repository and point your client at omv_mcp.py

The extension is simply this repository's omv_mcp.py packaged into a .mcpb file — a zip with a manifest that tells Claude Desktop how to start it and which settings to ask you for. Same code, same behaviour; only the installation differs. If your client is not Claude Desktop, you are not missing anything by going the manual route.

---

Install as a Claude Desktop extension

The extension gives you a settings panel, so nothing has to be edited in any file. macOS and Windows only; on Linux use the manual setup.

1. Download omv-mcp-<version>.mcpb from the latest release.
2. Double-click it, or drag it onto the Claude Desktop window. It is also available under Settings → Extensions → Advanced settings → Install Extension…
3. Fill in at least the NAS hostname or IP address, then enable the extension.

Setting	Default	What it does
NAS hostname or IP address	—	Required. An IP address, or a host defined in your ~/.ssh/config.
SSH username	root	The account used to log in
SSH port	22	Change only for a non-standard port
SSH private key (path)	(empty)	Best left empty — that uses your ssh-agent and ~/.ssh/config. See SSH setup.
OpenMediaVault user	admin	The OMV login the RPC runs as — not the SSH user
Run commands with sudo	off	Turn on when the SSH user is not root
Read-only mode	on	Refuses anything that is not a read operation
Allow arbitrary shell commands	off	Adds the unrestricted omv_shell tool
Command timeout	60s	Per-command limit

After changing any setting: click Save, then fully quit Claude Desktop (⌘Q on macOS) and reopen it. The server reads its settings once at startup, so a running server keeps the values it was started with — closing the window is not enough. Until you restart, changes appear not to have saved: writes keep getting refused and omv_connection_info reports the old values.

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

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 its root, so the build script needs nothing but the standard library — no Node.js and no mcpb CLI.

---

Install manually

The route for every client other than Claude Desktop — and the only route on Linux.

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. Whatever the client, it needs the same three things: the command python3, the argument /absolute/path/to/omv_mcp.py, and the environment variables from the table below. The examples that follow are just those three things written in each client's own configuration format.

Claude Code — the same on macOS, Linux and Windows:

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

Add -s user to make it available in every project rather than only the current one. claude mcp list reports ✔ Connected once the handshake succeeds.

Cursor, Zed, Cline, VS Code, the OpenAI Agents SDK and others — most use a JSON block in the same shape as the Claude Desktop one below, under whatever key that client calls its server list. Consult its documentation for the file, then fill in the same command, argument and environment variables.

Claude Desktop by hand — useful if you would rather not use the extension, in claude_desktop_config.json — ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on 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 ~, and restart the client completely afterwards.

Environment variables

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

Variable	Default	Meaning
OMV_SSH_HOST	(empty)	Hostname or IP of the NAS. Empty runs commands locally — use that if the server itself runs on the NAS.
OMV_SSH_USER	root	SSH user
OMV_SSH_PORT	22	SSH port
OMV_SSH_KEY	(empty)	Path to a private key. Empty uses your ssh-agent and ~/.ssh/config.
OMV_RPC_USER	admin	The OMV user the RPC call runs as
OMV_SUDO	0	1 prefixes every command with sudo, for non-root SSH users
OMV_READONLY	0	1 refuses anything that does not look like a read method, and disables omv_shell
OMV_ALLOW_SHELL	1	0 removes the omv_shell tool entirely
OMV_TIMEOUT	60	Per-command timeout in seconds

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

Running on the NAS itself

Leave OMV_SSH_HOST empty and commands run locally instead of over SSH, so the server can live on the NAS alongside OpenMediaVault. This only helps when the MCP client also runs there — Claude Code over an SSH session, for instance — because stdio means the client starts the server as a child process. omv_connection_info reports "mode": "local" when it is working this way.

---

SSH setup

The server runs ssh with BatchMode=yes, so password logins will not work. That 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 user@nas                      # your NAS address
ssh user@nas 'omv-rpc -u admin System getInformation'

If that last command prints JSON, the server will work. Run it whenever something is wrong: it separates an SSH problem from an MCP problem in one step.

Which key goes where. The public key (.pub) belongs on the NAS, in ~/.ssh/authorized_keys — that is what ssh-copy-id puts there. The private key stays on your computer and is what proves your identity. So if you fill in the key setting, give it the path to the private key: ~/.ssh/id_ed25519, not ~/.ssh/id_ed25519.pub.

Better still, leave that setting empty. Then ssh uses your agent and ~/.ssh/config, which is where this kind of detail belongs:

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

and set the NAS address to nas. Note that leaving the setting empty only works if ssh can find the key on its own — that means a standard name (id_ed25519, id_rsa), an entry in ~/.ssh/config, or a key loaded into your ssh-agent. A key with a custom name and no config entry has to be given explicitly.

First connection from a new computer. The NAS will not be in that machine's known_hosts yet, and BatchMode stops ssh from asking whether to trust it. omv-mcp therefore connects with StrictHostKeyChecking=accept-new: an unknown host is recorded on first contact, exactly as answering yes would, while a host key that changes later is still refused. To approve it yourself instead, run ssh user@nas once in a terminal before enabling the extension.

Root login refused? OpenMediaVault 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.

---

Using it

Start by asking the assistant to check the connection; it will call omv_connection_info and report your OpenMediaVault version. From there, ask for what you want in ordinary language:

• "Are any of my disks reporting SMART errors?"
• "What is using space on the data pool?"
• "Show me the shared folders and who can write to them."
• "The SMB service is not responding — what does its status say?"
• "Are there package updates pending, and what would they change?"
• "Apply the pending configuration changes."

Under the hood the assistant calls omv_call with a service and a method:

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

You do not need to memorise service names — omv_list_services and omv_list_methods always reflect your own installation, plugins included. Service names are case sensitive, and a few are lowercase (kernel, omvextras), so use them exactly as returned.

Background jobs. Heavier methods return {"filename": "..."} and keep running on the NAS. omv_wait_for_task 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)

The shell tool is an escape hatch for everything outside the RPC layer — journalctl, docker ps, smartctl, package state. Prefer omv_call for anything OpenMediaVault manages itself, so its configuration database stays in sync with the system. Off by default.

---

Security

This server can do anything you can do in the OpenMediaVault 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 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 need it.
• Use a dedicated SSH key for this rather than your everyday key.
• Consider a non-root user with sudo and a narrowed sudoers rule.
• Keep it on your LAN. This server has no authentication of its own; 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 goes through shlex.quote, so parameters cannot break out into the shell.

On host keys: the connection uses StrictHostKeyChecking=accept-new, which trusts the NAS on first contact and pins it from then on. That is trust-on-first-use, the same bargain you make when you type yes at an ssh prompt, and it is what makes an unattended first connection possible. It is not StrictHostKeyChecking=no: a key that changes after that first connection is still refused. Connect once from a terminal beforehand if you want to avoid the first-use window entirely.

---

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 OpenMediaVault's sources that this parser handles, and which are easy to get wrong when writing your own:

1. Quoting is inconsistent. The 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.
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 small 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 identifying values replaced. The tests therefore assert against what a NAS actually returns rather than against an idealised sample.

---

Troubleshooting

Symptom	Likely cause
Extension will not install	Python 3.9 or newer is missing. Check with python3 --version.
Extension will not start	No python3 on PATH (python on Windows)
Server does not appear in the client	JSON syntax error, or a relative path in a manual config
Permission denied (publickey)	This computer's key is not in authorized_keys on the NAS, or you gave the .pub instead of the private key
Host key verification failed	The NAS key could not be accepted automatically — run ssh user@nas once in a terminal
No connection from a newly set up computer	That machine has no SSH key on the NAS yet. Test with ssh user@nas 'omv-rpc -u admin System getInformation'.
No RPC services found	The SSH user cannot read /usr/share/openmediavault/engined/rpc
command not found: omv-rpc	/usr/sbin is not in the SSH user's PATH — turn on sudo
Command exceeded 60s	Raise the timeout, or use omv_wait_for_task for long jobs
A method is refused as "not a read method"	Read-only mode is on. If you just turned it off, fully quit and reopen Claude Desktop.
Settings disagree with omv_connection_info	The server still holds its startup values, or a second registration in another client answered
A setting will not stick	Quit Claude Desktop and edit the extension's JSON under ~/Library/Application Support/Claude/Claude Extensions Settings/, then reopen
A newly installed plugin is invisible	Restart the MCP server; the service list is cached

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

---

Contributing

Issues and pull requests are welcome — particularly reports from OpenMediaVault 7, from plugins whose RPC sources are laid out unusually, and from setups where discovery finds fewer services than the web interface 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.