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

Go to Datacenter → Permissions → API Tokens
Click Add
Select a user (or create a new one with PVEAuditor role)
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

# 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

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

cd proxmox-mcp

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Lint
uv run ruff check src/

License

MIT