mcp-openmediavault

A Model Context Protocol (MCP) server for OpenMediaVault (OMV), providing AI assistants with full access to NAS storage, shares, users, and system management through the OMV JSON-RPC API.

Compatible with OMV 5 and OMV 6.

Features

33 tools across five categories:

System

Tool	Description
`get_system_info`	Hostname, version, CPU model, uptime, memory
`get_system_stats`	CPU usage, memory usage, load averages
`get_cpu_temp`	CPU temperature readings
`get_network_interfaces`	Network interfaces with IP, netmask, gateway, speed
`get_system_log`	Syslog entries
`get_power_management`	Scheduled shutdown, wake-on-LAN settings

Storage

Tool	Description
`list_disks`	Physical disks with model, vendor, size, serial, temperature, SMART status
`list_filesystems`	Filesystems with type, label, size, usage, mount status
`get_mounted_filesystems`	Currently mounted filesystems with usage stats
`get_smart_info`	SMART attributes for a disk
`get_smart_extended_info`	Extended SMART info including self-test results
`get_smart_device_settings`	SMART monitoring settings per disk
`list_smart_jobs`	Scheduled SMART self-test jobs
`list_raid_devices`	Software RAID (mdadm) devices

Tool	Description
`list_shared_folders`	Shared folders with filesystem references and privileges
`get_shared_folder_privileges`	User/group access privileges for a shared folder
`list_smb_shares`	SMB/CIFS (Samba/Windows) shares
`get_smb_settings`	Global SMB service settings
`list_nfs_shares`	NFS shares with client and export options
`get_nfs_settings`	Global NFS service settings
`list_ftp_shares`	FTP shares
`get_ftp_settings`	Global FTP service settings

Users & Groups

Tool	Description
`list_users`	Local user accounts with UID, GID, groups
`get_user`	Detailed info about a specific user
`list_groups`	Local groups with GID, comment, members
`get_group`	Detailed info about a specific group
`enumerate_users`	All system users including system accounts
`enumerate_groups`	All system groups
`get_user_privileges`	Shared folder privileges for a user

Services

Tool	Description
`get_services_status`	Status of all services (SMB, NFS, SSH, FTP, rsync, etc.)
`list_cron_jobs`	Scheduled cron jobs with command and schedule
`get_ssh_settings`	SSH service settings
`list_rsync_jobs`	Rsync backup/sync jobs
`list_rsync_modules`	Rsync daemon modules
`get_rsync_settings`	Global rsync settings
`get_notification_settings`	Email notification settings
`get_updates`	Available software updates
`list_plugins`	Installed OMV plugins
`get_watchdog_settings`	Hardware watchdog timer settings

Installation

git clone git@github.com:fredriksknese/mcp-openmediavault.git
cd mcp-openmediavault
npm install
npm run build

Configuration

The server is configured via environment variables:

Variable	Required	Default	Description
`OMV_HOST`	Yes	—	OMV server hostname or IP address
`OMV_USERNAME`	No	`admin`	OMV admin username
`OMV_PASSWORD`	Yes	—	OMV admin password
`OMV_ALLOW_SELF_SIGNED`	No	`true`	Accept self-signed SSL certificates

OMV 5 / OMV 6 Compatibility

The server connects to the JSON-RPC endpoint at https://{host}/rpc.php, which is the standard endpoint for both OMV 5 and OMV 6.

Session management follows the OMV protocol:

Login via POST /rpc.php with Session.login
Extract the session cookie (PHPSESSID) from the Set-Cookie response header
Send both the Cookie header and X-OPENMEDIAVAULT-SESSIONID header on all subsequent requests

If the session expires (HTTP 401), the client automatically re-authenticates and retries.

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "openmediavault": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-openmediavault/dist/index.js"],
      "env": {
        "OMV_HOST": "192.168.1.100",
        "OMV_USERNAME": "admin",
        "OMV_PASSWORD": "your-password"
      }
    }
  }
}

Usage with Claude Code

claude mcp add openmediavault -- node /absolute/path/to/mcp-openmediavault/dist/index.js

Set environment variables before running, or configure them in your MCP settings.

Example Prompts

Once connected, you can ask your AI assistant things like:

"What is the current disk usage and which filesystems are mounted?"
"Show me the SMART health status for all disks"
"List all SMB shares and their enabled status"
"What services are currently running on the NAS?"
"Show me all users and their group memberships"
"Are there any software updates available for OMV?"
"What cron jobs are scheduled and when do they run?"
"Show me the NFS export configuration"
"What is the CPU temperature and system load?"

Development

npm run dev      # Run with tsx (auto-reloads)
npm run build    # Compile TypeScript to dist/
npm start        # Run compiled output

Architecture

src/
├── index.ts          # Entry point — creates MCP server + STDIO transport
├── omv-client.ts     # JSON-RPC client with session management and auto-retry
└── tools/
    ├── system.ts     # System info, stats, network interfaces (6 tools)
    ├── storage.ts    # Disks, filesystems, SMART, RAID (8 tools)
    ├── shares.ts     # Shared folders, SMB, NFS, FTP (8 tools)
    ├── users.ts      # Users and groups (7 tools)
    └── services.ts   # Services status, cron, SSH, rsync, plugins (10 tools)

Requirements

Node.js 18+
OpenMediaVault 5 or 6 with admin credentials
Admin account with API access (the default admin account works)

License

SEE LICENSE IN LICENSE

mcp-openmediavault

mcp-openmediavault

Features

System

Storage

Shares

Users & Groups

Services

Installation

Configuration

OMV 5 / OMV 6 Compatibility

Usage with Claude Desktop

Usage with Claude Code

Example Prompts

Development

Architecture

Requirements

License

Reviews