Provides read-only access to Proxmox homelab infrastructure, enabling monitoring and querying of VMs, containers, nodes, cluster status, performance metrics, and snapshots across a Proxmox cluster.
Proxmox MCP Server
A read-only MCP (Model Context Protocol) server that allows LLM agents to interact with your Proxmox homelab VMs.
Features
📋 List all VMs and containers across your Proxmox cluster
🔍 Get detailed VM information including hardware specs, network config, and disks
📊 Monitor VM status with real-time CPU, memory, and I/O metrics
📈 Historical metrics with hourly, daily, weekly, monthly, or yearly data
📸 List VM snapshots to see backup points
🖥️ Cluster overview with node status and aggregate resources
All operations are read-only - your VMs are safe!
Quick Start
1. Install the package
2. Configure Proxmox credentials
3. Create a read-only API token in Proxmox
Go to Datacenter → Permissions → API Tokens
Click Add
Select a user (or create a new one with
PVEAuditorrole)Set Token ID (e.g.,
homelab-mcp)Uncheck "Privilege Separation" if using an auditor user
Copy the token secret (shown only once!)
Recommended: Create a dedicated auditor user
4. Run the server
Available Tools
Tool | Description |
| List all VMs and containers with basic info |
| Get detailed VM configuration and specs |
| Get current runtime status and metrics |
| Get historical performance data |
| List all Proxmox nodes |
| List snapshots for a VM |
| Get cluster health and totals |
Configuration
All settings can be configured via environment variables or a .env file:
Variable | Description | Default |
| Proxmox server hostname/IP |
|
| Proxmox API port |
|
| Verify SSL certificates |
|
| API token ID (user@realm!tokenid) | - |
| API token secret | - |
| SSE server bind address |
|
| SSE server port |
|
Using with LLM Clients
VS Code with GitHub Copilot
Add to your VS Code settings.json:
Claude Desktop
Add to claude_desktop_config.json:
Local stdio mode
For local usage, you can run with stdio transport:
Example Queries
Once connected, you can ask your LLM:
"List all my VMs"
"What's the status of VM 100?"
"Show me the CPU usage history for my plex server"
"Which VMs are currently stopped?"
"How much memory is my cluster using?"
Security Notes
Use API tokens instead of username/password
Use the PVEAuditor role for true read-only access
Run behind a reverse proxy with HTTPS in production
Firewall the MCP port to trusted networks only
Development
License
MIT
This server cannot be installed