README.md
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 |
Shares
| 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.phpwithSession.login - Extract the session cookie (
PHPSESSID) from theSet-Cookieresponse header - Send both the
Cookieheader andX-OPENMEDIAVAULT-SESSIONIDheader 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?"
Tools 5
get_system_infoRetrieves hostname, version, CPU model, uptime, and memory information.get_system_statsRetrieves CPU usage, memory usage, and load averages.list_disksLists physical disks with model, vendor, size, serial, temperature, and SMART status.list_shared_foldersLists shared folders with filesystem references and privileges.get_services_statusRetrieves the status of all services like SMB, NFS, SSH, FTP, and rsync.Environment Variables
OMV_HOSTrequiredOMV server hostname or IP addressOMV_USERNAMEOMV admin usernameOMV_PASSWORDrequiredOMV admin passwordOMV_ALLOW_SELF_SIGNEDAccept self-signed SSL certificatesTry it
→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?