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

Storage

Shares

Users & Groups

Services

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:

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