omv-mcp — MCP server for the OpenMediaVault NAS

Manage and inspect an OpenMediaVault NAS from any MCP-capable AI harness (Claude Code, Claude Desktop, Copilot, Cursor, Codex, …): 48 tools across system, storage/SMART health, Docker, and Portainer stacks, plus resources, prompts, and completions.

Install (one command)

Install uv if you don't have it, then run setup:

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
uvx omv-mcp setup

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx omv-mcp setup

Setup asks for your NAS address and SSH login, then does everything else:

1. Passwordless SSH — if key login isn't set up yet, it installs your public key using your OMV password once (never stored; an ed25519 key is generated if you don't have one).

2. Live verification — runs real omv-rpc and docker ps on the NAS and shows the results.

3. Portainer (optional) — paste an API key to enable the compose-stack tools (Portainer → user icon → Access tokens); blank to skip.

4. Registration — registers with Claude Code automatically and prints paste-ready config blocks for Claude Desktop, VS Code, and Cursor.

Requirements: root SSH login on the NAS (OMV's default) and any address that reaches it — a LAN IP like 192.168.x.x is what v1 is tested on. Tailscale IPs usually work as-is; official Tailscale support lands in v2.

Related MCP server: mcp-ssh-tool

Two modes, one package

Mode B — run anywhere (default). The server runs on your machine and executes every command on the NAS over one persistent SSH connection (~25 ms per call after the handshake). Nothing is installed on the NAS.

your machine                                 NAS (OMV, Debian)
┌────────────────────────────┐               ┌──────────────────────┐
│ MCP client ──▶ omv-mcp     │ ═ ssh (1) ══▶ │ omv-rpc / docker / … │
│              (uvx omv-mcp) │ ─ tunnel ───▶ │ Portainer :9000      │
└────────────────────────────┘               └──────────────────────┘

Mode A — run on the NAS (advanced). Choose A during setup: it installs uv on the NAS and registers the client to launch the server there over stdio-on-SSH. Commands are then local subprocess calls on the NAS.

your machine                        NAS (OMV, Debian)
┌─────────────┐                     ┌────────────────────────────────┐
│ MCP client ─┼── ssh … uvx omv-mcp ▶ omv-mcp ─▶ omv-rpc / docker / …│
└─────────────┘                     └────────────────────────────────┘

The selector is one config key: OMV_HOST set → Mode B; unset → Mode A.

Configuration

omv-mcp setup writes this for you. File location: %APPDATA%\omv-mcp\config.env (Windows) or ~/.config/omv-mcp/config.env (macOS/Linux/NAS). Real environment variables override the file.

Host keys are trust-on-first-use, pinned in <config dir>/known_hosts; a changed host key fails loudly. Dropped SSH connections reconnect once, transparently. In Mode B, Portainer traffic rides an SSH tunnel — the API key never crosses your network in cleartext, and no port besides SSH needs to be reachable.

Register a client manually

Setup prints these for you; for reference (Mode B):

{ "mcpServers": { "omv": { "command": "uvx", "args": ["omv-mcp"] } } }

claude mcp add omv -- uvx omv-mcp

VS Code (.vscode/mcp.json) uses "servers" with "type": "stdio", same command. For Mode A, setup prints the equivalent ssh …@nas -T -- uvx omv-mcp form.

Updating: uvx caches the package; refresh with uvx omv-mcp@latest --version (or uv cache clean omv-mcp).

⚠️ Safety

This server executes as root on the NAS and is meant for a single trusted user. There is no deny-list — run_command and omv_rpc are unrestricted root. The destructive named tools (reboot, shutdown, apply_updates, docker_prune, stop_container, stop_stack, restart_stack, update_stack, run_smart_test) require confirm=True. Your Portainer API key is stored in the per-user config file on whichever machine runs the server. Do not expose this server to untrusted clients.

Tools

⚠️ = unrestricted root or requires confirm=True.

Resources

Read-only NAS context any client can pull without a tool call:

Prompts & completions

Canned diagnostic workflows — diagnose_storage_health, triage_containers, whats_using_space, audit_shares_and_permissions — plus argument autocompletion for container names, stack ids, and share names.

apply_updates, docker_prune, stop_stack, restart_stack, and update_stack are async and emit MCP log/progress notifications while they run.

Development

git clone https://github.com/vnaveenb/openmediavault-mcp-ssh.git
cd openmediavault-mcp-ssh
uv sync                                  # venv with Python 3.12 + deps
uv run pytest                            # unit tests (no NAS needed)
uv run python tests/smoke_client.py      # live smoke test (uses your config.env)
uv run omv-mcp setup --dev               # register THIS checkout instead of PyPI

PRs welcome! See CONTRIBUTING.md for the workflow (GitHub Flow, conventional commits, squash-merge).

⚠️ This server runs as root on the NAS. Review every change with that in mind — never merge a PR you haven't read and understood.

License

MIT © 2026 Naveen Busiraju.