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 UV (if not already installed)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Configure Proxmox credentials

cp .env.example .env
# Edit .env with your Proxmox details

3. Create a read-only API token in Proxmox

1. Go to Datacenter → Permissions → API Tokens
2. Click Add
3. Select a user (or create a new one with PVEAuditor role)
4. Set Token ID (e.g., homelab-mcp)
5. Uncheck "Privilege Separation" if using an auditor user
6. Copy the token secret (shown only once!)

Recommended: Create a dedicated auditor user

# SSH to your Proxmox server
pveum user add mcp-reader@pve
pveum acl modify / -user mcp-reader@pve -role PVEAuditor
pveum user token add mcp-reader@pve proxmox-mcp

4. Run the server

cd proxmox-mcp

# SSE mode (recommended for remote access)
uv run proxmox-mcp --transport sse

# Or stdio mode (for local VS Code/CLI usage)
uv run proxmox-mcp --transport stdio

Alternative: Install globally with pip

pip install -e .
proxmox-mcp --transport sse

Available Tools

Tool	Description
list_vms	List all VMs and containers with basic info
get_vm_info	Get detailed VM configuration and specs
get_vm_status	Get current runtime status and metrics
get_vm_metrics	Get historical performance data
get_vm_filesystem_info	Get disk space from inside a VM (requires guest agent)
list_nodes	List all Proxmox nodes
list_vm_snapshots	List snapshots for a VM
get_cluster_status	Get cluster health and totals

Configuration

All settings can be configured via environment variables or a .env file:

Variable	Description	Default
PROXMOX_HOST	Proxmox server hostname/IP	localhost
PROXMOX_PORT	Proxmox API port	8006
PROXMOX_VERIFY_SSL	Verify SSL certificates	false
PROXMOX_API_TOKEN_ID	API token ID (user@realm!tokenid)	-
PROXMOX_API_TOKEN_SECRET	API token secret	-
MCP_SERVER_HOST	SSE server bind address	0.0.0.0
MCP_SERVER_PORT	SSE server port	8080

Using with LLM Clients

VS Code with GitHub Copilot

Add to your VS Code settings.json or user mcp.json:

{
  "servers": {
    "proxmox": {
      "url": "http://your-server:8080/sse"
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "proxmox": {
      "url": "http://your-server:8080/sse"
    }
  }
}

Local stdio mode

For local usage, you can run with stdio transport:

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/proxmox-mcp",
        "proxmox-mcp",
        "--transport", "stdio"
      ]
    }
  }
}

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

1. Use API tokens instead of username/password
2. Use the PVEAuditor role for true read-only access
3. Run behind a reverse proxy with HTTPS in production
4. Firewall the MCP port to trusted networks only

Development

cd proxmox-mcp

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Lint
uv run ruff check src/

License

MIT