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:

1. Login via POST /rpc.php with Session.login
2. Extract the session cookie (PHPSESSID) from the Set-Cookie response header
3. 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