MCP 服务器

omv-mcp

Exposes tools to manage and inspect an OpenMediaVault NAS, running on the NAS and communicating over SSH with any MCP-capable coding harness.

README

omv-mcp — MCP server for the OpenMediaVault NAS

Exposes tools to manage/inspect an OpenMediaVault NAS to any MCP-capable coding harness (Claude Code, Copilot, Codex, …).

Throughout this README, <nas-ip> is your NAS host/IP and /opt/omv-mcp is wherever you deploy this project on the NAS — substitute your own values.

Architecture

Runs ON the NAS (Debian 11), not on your workstation. Every tool is a local subprocess call to omv-rpc / docker / df / lsblk — no per-call SSH. This sidesteps the official openmediavault-mcp, which drives OMV over HTTP /rpc.php with the web-admin password (a credential we don't have).
Transport: stdio over one SSH pipe. Each client launches the server as an ssh … python -m omv_mcp command; SSH carries JSON-RPC over a single connection per session. No listening port, no new auth — it reuses the existing passwordless SSH trust boundary.

workstation harness ──(spawns)──▶ ssh root@<nas-ip> -T -- <venv python> -m omv_mcp
                                            │ (runs on the NAS)
                                            ├─ omv-rpc -u admin …   (local, no password)
                                            ├─ docker …             (local)
                                            └─ Portainer @ localhost:9000

⚠️ Safety

This server runs as root and is meant for a single trusted user on a home LAN. There is no deny-list. run_command and omv_rpc are unrestricted root — they can do anything. The only guarded tools are the obviously destructive named ones (reboot, shutdown, update_stack), which require confirm=True. Do not expose this server to untrusted clients.

Install (on the NAS)

Source of truth is authored on the workstation and scp-deployed to /opt/omv-mcp. Then, on the NAS:

cd /opt/omv-mcp
cp .env.example .env          # then paste the real PORTAINER_API_KEY into .env
uv sync                       # builds .venv with Python 3.12 + deps

uv fetches a standalone CPython 3.12 (system python3 is 3.9, too old for the mcp SDK). The real .env lives only on the NAS and is never committed/scp'd.

Register with a client

Point the client at the venv interpreter over SSH (launch it directly, not via uv run, so nothing pollutes stdout):

claude mcp add omv -- ssh root@<nas-ip> -T -- \
  /opt/omv-mcp/.venv/bin/python -m omv_mcp

Equivalent .mcp.json / Claude Desktop config:

{
  "mcpServers": {
    "omv": {
      "command": "ssh",
      "args": [
        "root@<nas-ip>", "-T", "--",
        "/opt/omv-mcp/.venv/bin/python", "-m", "omv_mcp"
      ]
    }
  }
}

Tools

Group	Tools
System	`get_system_info`, `disk_usage`, `list_block_devices`, `top_processes`, `memory_info`, `network_info`, `service_status`, `service_logs`, `available_updates`, `apply_updates` ⚠️, `run_command` ⚠️, `reboot` ⚠️, `shutdown` ⚠️
Storage / health	`list_filesystems`, `list_disks`, `storage_summary`, `smart_status`, `smart_health`, `smart_attributes`, `smart_selftest_log`, `run_smart_test` ⚠️, `disk_temperatures`, `cpu_temp`, `sensors_readout`, `list_shared_folders`, `list_smb_shares`, `omv_rpc` ⚠️
Users/groups	`list_users`, `list_groups`
Docker	`list_containers`, `container_stats`, `container_inspect`, `container_logs`, `list_images`, `list_volumes`, `list_networks`, `docker_system_df`, `start_container`, `restart_container`, `stop_container` ⚠️, `docker_exec` ⚠️, `docker_prune` ⚠️
Portainer stacks	`list_stacks`, `get_stack_compose`, `start_stack`, `stop_stack` ⚠️, `restart_stack` ⚠️, `update_stack` ⚠️

⚠️ = unrestricted root or requires confirm=True.

Resources

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

URI	Content
`omv://system`	live host/OMV info (JSON)
`omv://storage/overview`	per-mount usage for OS + data disks (JSON)
`omv://health`	composite: SMART overall + disk/CPU temps + df (JSON)
`omv://stacks`	Portainer stacks (JSON)
`omv://container/{name}/logs`	last 100 log lines (template)
`omv://stack/{stack_id}/compose`	compose YAML (template)

Prompts

Canned diagnostic workflows: diagnose_storage_health, triage_containers, whats_using_space, audit_shares_and_permissions.

Completions

Argument autocompletion (spec-correct: for prompt/resource-template args, not tool inputs): container names for omv://container/{name}/logs, stack ids for omv://stack/{stack_id}/compose, and shared-folder names for the audit_shares_and_permissions prompt's share argument.

Long-running tools & progress

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

Smoke test (on the NAS)

uv run python tests/smoke_client.py

Spawns the server over stdio, lists tools, and calls a few read-only ones against live data.

Contributing

PRs welcome! 🎉 Whether it's a new tool, a bug fix, or docs — contributions are appreciated. See CONTRIBUTING.md for the full guide.

Quick start:

git clone https://github.com/vnaveenb/openmediavault-mcp-ssh.git
cd openmediavault-mcp-ssh/omv-mcp
uv sync                                  # build .venv (Python 3.12 + deps)
uv run python tests/smoke_client.py      # sanity-check against a live NAS

⚠️ 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.

Branching strategy

We follow GitHub Flow — lightweight and PR-driven:

main is always deployable. Never commit directly to it.
Branch off main with a descriptive, prefixed name:

Prefix Use for

feat/… new tools, resources, or features

fix/… bug fixes

docs/… documentation only

chore/… tooling, deps, refactors

e.g. feat/smart-selftest-schedule, fix/portainer-timeout.
Commit in small, focused steps (Conventional Commits encouraged: feat: …, fix: …, docs: …).
Open a PR into main, fill out the template, and link any related issue.
After review, squash-merge and delete the branch. Keep main linear.